Contracts

Soda Cloud API Contract Endpoints

List contracts

get
/api/v1/contracts

This endpoint allows you to list contracts in your organization.

This GET is a paginated API that uses the following parameters to request specific details:

  • size: Supply an integer value between 10 and 1000, inclusive. The default value is 10.

  • page: Supply an integer value. The default value is 0.

  • datasetId: Optionally, use this parameter to list only the contracts for a specific dataset.

  • datasetQualifiedName: Optionally, use this parameter instead of datasetId to identify the dataset by its qualified name. Do not supply both datasetId and datasetQualifiedName.

Authorization

When filtering by dataset, only users with View dataset permission on the specified dataset can list its contracts. When no dataset filter is supplied, all contracts in the organization are returned.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Query parameters
datasetIdstringOptional
datasetQualifiedNamestringOptional
pageinteger · int32Optional
sizeinteger · int32Optional
Responses
chevron-right
200

Successful response

application/json
firstbooleanRequired
lastbooleanRequired
numberinteger · int32Required
sizeinteger · int32Required
totalElementsinteger · int32Required
totalPagesinteger · int32Required
get
/api/v1/contracts

Create a contract

post
/api/v1/contracts

This endpoint allows you to create a new contract on a dataset. The contract is initialized with a template containing the dataset identifier and an empty columns list. Use the publish endpoint to replace this with your full contract YAML.

Provide either datasetId or datasetQualifiedName in the request body to identify the target dataset. Exactly one must be supplied. If both are supplied, the request is rejected with a 400 error.

Authorization

Only users with Manage contracts permission can create contracts.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
contentsstringRequired
datasetIdstringOptional
datasetQualifiedNamestringOptional
Responses
chevron-right
200

Successful response

application/json
post
/api/v1/contracts

Generate skeleton contract

post
/api/v1/contracts/actions/createSkeleton

Triggers skeleton contract generation for a single dataset based on its schema.

The dataset must be connected to a Soda Agent and must not already have a published contract.

Provide either datasetId (UUID) or datasetQualifiedName (e.g. my_datasource/my_schema/my_table). Exactly one must be supplied.

Returns 202 Accepted with a Location header pointing to the status endpoint. Use the status endpoint to monitor the progress of the skeleton generation.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
datasetIdstringOptional
datasetQualifiedNamestringOptional
Responses
post
/api/v1/contracts/actions/createSkeleton

No content

Get skeleton contract generation status

get
/api/v1/contracts/actions/createSkeleton/{operationId}

Returns the status of a skeleton contract generation operation that was triggered via the Generate skeleton contract endpoint.

The operationId is the last path segment of the Location header returned by the Generate skeleton contract response.

The response includes the operation state, dataset information, and creation timestamp.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
operationIdstringRequired
Responses
chevron-right
200

Successful response

application/json
createdstringOptional
datasetIdstringOptional
datasetQualifiedNamestringOptional
operationIdstringOptional
stateobject · enumOptionalPossible values:
get
/api/v1/contracts/actions/createSkeleton/{operationId}

Generate contracts

post
/api/v1/contracts/actions/generate

Triggers AI-powered contract generation for one or more datasets. The contract generation runs asynchronously.

Each dataset must be connected to a Soda Agent and must not already have a contract. If any dataset is not eligible, the request is rejected with a 400 response listing the ineligible datasets and reasons.

Provide datasetIds (list of UUIDs) and/or datasetQualifiedNames (list of qualified names, e.g. my_datasource/my_schema/my_table). Both lists are additive. At least one must be non-empty.

Returns 202 Accepted with a Location header pointing to the status endpoint. Use the status endpoint to monitor the progress of the contract generation.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
datasetIdsstring[]Optional
datasetQualifiedNamesstring[]Optional
Responses
post
/api/v1/contracts/actions/generate

No content

Get contract generation status

get
/api/v1/contracts/actions/generate/{operationId}

Returns the status of a contract generation operation that was triggered via the Generate contracts endpoint.

The operationId is the last path segment of the Location header returned by the Generate contracts response.

While the operation is ongoing, only the operation state is returned (datasets will be null). Once the operation reaches a terminal state (completed, failed, or canceled), the full per-dataset scan details are included.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
operationIdstringRequired
Responses
chevron-right
200

Successful response

application/json
createdstringOptional
operationIdstringOptional
stateobject · enumOptionalPossible values:
get
/api/v1/contracts/actions/generate/{operationId}

Get a contract

get
/api/v1/contracts/{contractId}

This endpoint allows you to retrieve a specific contract, including its YAML content.

Authorization

Only users with View dataset permission can view contracts.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

1000 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
contractIdstringRequired
Responses
chevron-right
200

Successful response

application/json
get
/api/v1/contracts/{contractId}

Publish a contract

post
/api/v1/contracts/{contractId}

This endpoint allows you to publish new YAML content for an existing contract.

The contents field must contain valid Soda contract YAML. If the YAML is malformed or does not conform to the contract schema, the request is rejected with a 400 error.

Authorization

Only users with Manage contracts permission can publish contracts.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
contractIdstringRequired
Body
contentsstringRequired
Responses
chevron-right
200

Successful response

application/json
post
/api/v1/contracts/{contractId}

Verify a contract

post
/api/v1/contracts/{contractId}/verify

This endpoint triggers a contract verification scan for the specified contract.

The response, when successful, is 201 and contains headers Location and X-Soda-Scan-Id which identify the triggered scan. Use the value of X-Soda-Scan-Id in the scanId parameter of the Get scan status, Get scan logs, and Cancel a scan endpoints.

Optionally, you can provide checkPaths to limit verification to specific checks within the contract. Note: checkPaths may not be available for all organizations.

Authorization

Only users with Manage contracts permission can verify contracts.

Authentication

User authentication required: true

This endpoint enforces authentication using the API keys you provide in the Basic authentication header.

Tags

Contracts

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
contractIdstringRequired
Body
checkPathsstring[]Optional
Responses
post
/api/v1/contracts/{contractId}/verify

No content

Last updated

Was this helpful?