Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Contracts

Soda Cloud API Contract Endpoints

Create a contract change request

post
/api/v1/contractRequests

Create a discussion-style change request for an onboarded dataset, with a required title and optional reasoning. Reasoning is added as the initial comment. An existing published contract is not required; this endpoint does not submit YAML proposals or publish a contract.

Provide exactly one of datasetId or datasetQualifiedName. The response contains the new request in open status with its organisation-wide number and authenticated author.

Malformed requests and organisations with contracts disabled receive 400. Datasets that are missing, not onboarded, or in another organisation receive 404.

Authorization

A human user with either Manage contracts or Create check proposals permission on the dataset is required. Insufficient permissions, service accounts, and runner service users receive 403. Use a human-owned API key or a human cookie session when public API cookie authentication is enabled.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
datasetIdstringOptional
datasetQualifiedNamestringOptional
reasoningstringOptional
titlestringRequired
Responses
200

Successful response

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

{
  "datasetId": "text",
  "datasetQualifiedName": "text",
  "reasoning": "text",
  "title": "text"
}
{
  "contractRequest": {
    "authorId": "text",
    "created": "2026-01-01T00:00:00.000Z",
    "datasetId": "text",
    "id": "text",
    "lastUpdated": "2026-01-01T00:00:00.000Z",
    "number": 1,
    "status": "open",
    "title": "text"
  }
}

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 accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

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
get/api/v1/contracts
GET /api/v1/contracts HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*
{
  "content": [
    {
      "contents": "text",
      "created": "2026-01-01T00:00:00.000Z",
      "datasetId": "text",
      "datasetQualifiedName": "text",
      "id": "text",
      "lastUpdated": "2026-01-01T00:00:00.000Z"
    }
  ],
  "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 YAML in contents is published as the contract of the dataset, and the checks_schedule of the contract and of each of its scopes is applied.

A schedule needs a datasource that is configured in Soda Cloud and has a default runner that can run contracts. If one of these is missing, or if the cron runs more frequently than every 15 minutes, the request is rejected with a 400 error and no contract is created.

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 accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
contentsstringRequired
datasetIdstringOptional
datasetQualifiedNamestringOptional
Responses
200

Successful response

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": "2026-01-01T00:00:00.000Z",
    "datasetId": "text",
    "datasetQualifiedName": "text",
    "id": "text",
    "lastUpdated": "2026-01-01T00:00:00.000Z"
  }
}

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 Runner 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 accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
datasetIdstringOptional
datasetQualifiedNamestringOptional
Responses
202

Accepted

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 accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
operationIdstringRequired
Responses
200

Successful response

application/json
createdstring · date-timeOptional
datasetIdstringOptional
datasetQualifiedNamestringOptional
operationIdstringOptional
stateobject · enumOptionalPossible values:
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": "2026-01-01T00:00:00.000Z",
  "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 Runner 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 either datasetIds (list of UUIDs) or datasetQualifiedNames (list of qualified names, e.g. my_datasource/my_schema/my_table). Exactly one of the two lists must be non-empty; sending both is rejected with a 400 response.

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 accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Body
datasetIdsstring[]Optional
datasetQualifiedNamesstring[]Optional
Responses
202

Accepted

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 accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
operationIdstringRequired
Responses
200

Successful response

application/json
createdstring · date-timeOptional
operationIdstringOptional
stateobject · enumOptionalPossible values:
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": "2026-01-01T00:00:00.000Z",
  "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 accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

1000 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
contractIdstringRequired
Responses
200

Successful response

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": "2026-01-01T00:00:00.000Z",
    "datasetId": "text",
    "datasetQualifiedName": "text",
    "id": "text",
    "lastUpdated": "2026-01-01T00:00:00.000Z"
  }
}

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.

The dataset in the YAML must name the dataset that contractId belongs to. Contents naming a different dataset are rejected with a 400 error.

Authorization

Only users with Manage contracts permission can publish contracts.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

100 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
contractIdstringRequired
Body
contentsstringRequired
Responses
200

Successful response

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": "2026-01-01T00:00:00.000Z",
    "datasetId": "text",
    "datasetQualifiedName": "text",
    "id": "text",
    "lastUpdated": "2026-01-01T00:00:00.000Z"
  }
}

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.

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

Authorization

Only users with Manage contracts permission can verify contracts.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

10 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
contractIdstringRequired
Body
checkPathsstring[]Optional
Responses
201

Created

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: 90

{
  "checkFilters": [
    {
      "field": "scope",
      "negate": true,
      "values": [
        "text"
      ]
    }
  ],
  "checkPaths": [
    "text"
  ]
}

No content

List contract versions

get
/api/v1/contracts/{contractId}/versions

This endpoint allows you to list versions of a specific contract.

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.

  • createdBefore: Optionally, supply a UTC datetime value (ISO 8601, e.g. 2024-01-15T10:30:00) to only return versions created strictly before this timestamp. Use this for consistent pagination.

Authentication

User authentication required: true

This endpoint accepts authentication via API keys in the Basic authentication header, or a pre-authenticated token in HTTP cookie token. Cookie sessions extend automatically on each request.

Tags

Contracts

Rate limiting

60 requests/60 seconds

Authorizations
AuthorizationstringRequired
Path parameters
contractIdstringRequired
Query parameters
createdBeforestring · date-timeOptional
pageinteger · int32Optional
sizeinteger · int32Optional
Responses
200

Successful response

application/json
firstbooleanRequired
lastbooleanRequired
numberinteger · int32Required
sizeinteger · int32Required
totalElementsinteger · int32Required
totalPagesinteger · int32Required
get/api/v1/contracts/{contractId}/versions
GET /api/v1/contracts/{contractId}/versions HTTP/1.1
Host: cloud.soda.io
Authorization: Basic username:password
Accept: */*
{
  "content": [
    {
      "checksum": "text",
      "contents": "text",
      "contractId": "text",
      "created": "2026-01-01T00:00:00.000Z",
      "creatorId": "text",
      "id": "text"
    }
  ],
  "first": true,
  "last": true,
  "number": 1,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1
}

Last updated

Was this helpful?