Contracts
Soda Cloud API Contract Endpoints
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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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"
}
}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 ofdatasetIdto identify the dataset by its qualified name. Do not supply bothdatasetIdanddatasetQualifiedName.
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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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
}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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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"
}
}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
Accepted
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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
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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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"
}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
Accepted
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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
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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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"
}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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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"
}
}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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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"
}
}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
Created
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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
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
Successful response
Bad request
Unauthorized
Forbidden
Not found
Too many requests
Internal server error
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?
