Contracts | Soda v3 | Documentation

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

200

Successful response

application/json

firstbooleanRequired

lastbooleanRequired

numberinteger · int32Required

sizeinteger · int32Required

totalElementsinteger · int32Required

totalPagesinteger · int32Required

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/contracts

GET /api/v1/contracts HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "content": [
    {
      "contents": "text",
      "created": "text",
      "datasetId": "text",
      "datasetQualifiedName": "text",
      "id": "text",
      "lastUpdated": "text"
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}

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

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/contracts

POST /api/v1/contracts HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 68

{
  "contents": "text",
  "datasetId": "text",
  "datasetQualifiedName": "text"
}

{
  "contract": {
    "contents": "text",
    "created": "text",
    "datasetId": "text",
    "datasetQualifiedName": "text",
    "id": "text",
    "lastUpdated": "text"
  }
}

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

202

Accepted

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/contracts/actions/createSkeleton

POST /api/v1/contracts/actions/createSkeleton HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 50

{
  "datasetId": "text",
  "datasetQualifiedName": "text"
}

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

200

Successful response

application/json

createdstringOptional

datasetIdstringOptional

datasetQualifiedNamestringOptional

operationIdstringOptional

stateobject · enumOptionalPossible values:

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

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

GET /api/v1/contracts/actions/createSkeleton/{operationId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "created": "text",
  "datasetId": "text",
  "datasetQualifiedName": "text",
  "operationId": "text",
  "state": "ongoing"
}

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

202

Accepted

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/contracts/actions/generate

POST /api/v1/contracts/actions/generate HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "datasetIds": [
    "text"
  ],
  "datasetQualifiedNames": [
    "text"
  ]
}

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

200

Successful response

application/json

createdstringOptional

operationIdstringOptional

stateobject · enumOptionalPossible values:

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

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

GET /api/v1/contracts/actions/generate/{operationId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "created": "text",
  "datasets": [
    {
      "datasetId": "text",
      "datasetQualifiedName": "text",
      "scanCloudUrl": "text",
      "scanId": "text",
      "scanState": "queuing"
    }
  ],
  "operationId": "text",
  "state": "ongoing"
}

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

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/api/v1/contracts/{contractId}

GET /api/v1/contracts/{contractId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*

{
  "contract": {
    "contents": "text",
    "created": "text",
    "datasetId": "text",
    "datasetQualifiedName": "text",
    "id": "text",
    "lastUpdated": "text"
  }
}

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

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/api/v1/contracts/{contractId}

POST /api/v1/contracts/{contractId} HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 19

{
  "contents": "text"
}

{
  "contract": {
    "contents": "text",
    "created": "text",
    "datasetId": "text",
    "datasetQualifiedName": "text",
    "id": "text",
    "lastUpdated": "text"
  }
}

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

201

Created

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not found

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

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

POST /api/v1/contracts/{contractId}/verify HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "checkPaths": [
    "text"
  ]
}

No content

hashtagList contracts

hashtagAuthorization

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagCreate a contract

hashtagAuthorization

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagGenerate skeleton contract

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagGet skeleton contract generation status

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagGenerate contracts

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagGet contract generation status

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagGet a contract

hashtagAuthorization

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagPublish a contract

hashtagAuthorization

hashtagAuthentication

hashtagTags

hashtagRate limiting

hashtagVerify a contract

hashtagAuthorization

hashtagAuthentication

hashtagTags

hashtagRate limiting

List contracts

Authorization

Authentication

Tags

Rate limiting

Create a contract

Authorization

Authentication

Tags

Rate limiting

Generate skeleton contract

Authentication

Tags

Rate limiting

Get skeleton contract generation status

Authentication

Tags

Rate limiting

Generate contracts

Authentication

Tags

Rate limiting

Get contract generation status

Authentication

Tags

Rate limiting

Get a contract

Authorization

Authentication

Tags

Rate limiting

Publish a contract

Authorization

Authentication

Tags

Rate limiting

Verify a contract

Authorization

Authentication

Tags

Rate limiting