Contracts

Soda Cloud API Contract Endpoints

List contracts

get

https://cloud.soda.iohttps://cloud.us.soda.io

/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

basicAuthApiKey

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

HTTPcURLJavaScriptPython

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

https://cloud.soda.iohttps://cloud.us.soda.io

/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

basicAuthApiKey

AuthorizationstringRequired

Body

application/json

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

HTTPcURLJavaScriptPython

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"
  }
}

Get a contract

get

https://cloud.soda.iohttps://cloud.us.soda.io

/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

basicAuthApiKey

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}

HTTPcURLJavaScriptPython

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

https://cloud.soda.iohttps://cloud.us.soda.io

/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

basicAuthApiKey

AuthorizationstringRequired

Path parameters

contractIdstringRequired

Body

application/json

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}

HTTPcURLJavaScriptPython

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"
  }
}