# Contracts

Soda Cloud API Contract Endpoints

## List 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiListContractsResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ContractContentDTO"}},"first":{"type":"boolean"},"last":{"type":"boolean"},"number":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32"}},"required":["content","first","last","number","size","totalElements","totalPages"]},"ContractContentDTO":{"type":"object","properties":{"contents":{"type":"string"},"created":{"type":"string","format":"date-time"},"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"},"id":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts":{"get":{"description":"This endpoint allows you to list contracts in your organization.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `size`: Supply an integer value between 10 and 1000, inclusive. The default value is 10.\n\n- `page`: Supply an integer value. The default value is 0.\n\n- `datasetId`: Optionally, use this parameter to list only the contracts for a specific dataset.\n\n- `datasetQualifiedName`: Optionally, use this parameter instead of `datasetId` to identify the dataset by its qualified name. Do not supply both `datasetId` and `datasetQualifiedName`.\n\n## Authorization\n\nWhen 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.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/contracts","parameters":[{"in":"query","name":"datasetId","schema":{"type":"string"}},{"in":"query","name":"datasetQualifiedName","schema":{"type":"string"}},{"in":"query","name":"page","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiListContractsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List contracts","tags":["Contracts"]}}}}
```

## Create a contract

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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiCreateContractRequestDTO":{"type":"object","properties":{"contents":{"type":"string"},"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"}},"required":["contents"]},"PublicApiCreateContractResponse":{"type":"object","properties":{"contract":{"type":"object","$ref":"#/components/schemas/ContractContentDTO"}}},"ContractContentDTO":{"type":"object","properties":{"contents":{"type":"string"},"created":{"type":"string","format":"date-time"},"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"},"id":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts":{"post":{"description":"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.\n\nProvide 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.\n\n## Authorization\n\nOnly users with **Manage contracts** permission can create contracts.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"POST/api/v1/contracts","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateContractRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateContractResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Create a contract","tags":["Contracts"]}}}}
```

## Generate skeleton contract

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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiCreateSkeletonContractRequestDTO":{"type":"object","properties":{"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/actions/createSkeleton":{"post":{"description":"Triggers skeleton contract generation for a single dataset based on its schema.\n\nThe dataset must be connected to a Soda Agent and must not already have a published contract.\n\nProvide either `datasetId` (UUID) or `datasetQualifiedName` (e.g. `my_datasource/my_schema/my_table`). Exactly one must be supplied.\n\nReturns `202 Accepted` with a `Location` header pointing to the status endpoint. Use the status endpoint to monitor the progress of the skeleton generation.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n10 requests/60 seconds","operationId":"POST/api/v1/contracts/actions/createSkeleton","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateSkeletonContractRequestDTO"}}},"required":true},"responses":{"202":{"description":"Accepted","headers":{"Location":{"schema":{"type":"string"}}}},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Generate skeleton contract","tags":["Contracts"]}}}}
```

## Get skeleton contract generation status

> 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiCreateSkeletonContractStatusResponse":{"type":"object","properties":{"created":{"type":"string","format":"date-time"},"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"},"operationId":{"type":"string"},"state":{"type":"object","$ref":"#/components/schemas/SkeletonContractOperationStateDTO"}}},"SkeletonContractOperationStateDTO":{"type":"string","enum":["ongoing","completed","failed","canceled"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/actions/createSkeleton/{operationId}":{"get":{"description":"Returns the status of a skeleton contract generation operation that was triggered via the **Generate skeleton contract** endpoint.\n\nThe `operationId` is the last path segment of the `Location` header returned by the **Generate skeleton contract** response.\n\nThe response includes the operation state, dataset information, and creation timestamp.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/contracts/actions/createSkeleton/{operationId}","parameters":[{"in":"path","name":"operationId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateSkeletonContractStatusResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Get skeleton contract generation status","tags":["Contracts"]}}}}
```

## Generate contracts

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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiGenerateContractRequestDTO":{"type":"object","properties":{"datasetIds":{"type":"array","items":{"type":"string"}},"datasetQualifiedNames":{"type":"array","items":{"type":"string"}}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/actions/generate":{"post":{"description":"Triggers AI-powered contract generation for one or more datasets. The contract generation runs asynchronously.\n\nEach 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.\n\nProvide `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.\n\nReturns `202 Accepted` with a `Location` header pointing to the status endpoint. Use the status endpoint to monitor the progress of the contract generation.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n10 requests/60 seconds","operationId":"POST/api/v1/contracts/actions/generate","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGenerateContractRequestDTO"}}},"required":true},"responses":{"202":{"description":"Accepted","headers":{"Location":{"schema":{"type":"string"}}}},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Generate contracts","tags":["Contracts"]}}}}
```

## Get contract generation status

> 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiGenerateContractStatusResponse":{"type":"object","properties":{"created":{"type":"string","format":"date-time"},"datasets":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/PublicApiGenerateContractStatusResponse_DatasetGenerationStatus"}},"operationId":{"type":"string"},"state":{"type":"object","$ref":"#/components/schemas/GenerateContractOperationStateDTO"}}},"PublicApiGenerateContractStatusResponse_DatasetGenerationStatus":{"type":"object","properties":{"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"},"scanCloudUrl":{"type":"string"},"scanId":{"type":"string"},"scanState":{"type":"object","$ref":"#/components/schemas/ScanStateDTO"}}},"ScanStateDTO":{"type":"string","enum":["queuing","executing","started","cancelationRequested","timeOutRequested","canceled","timedOut","failed","completedWithErrors","completedWithFailures","completedWithWarnings","completed"]},"GenerateContractOperationStateDTO":{"type":"string","enum":["ongoing","completed","failed","canceled"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/actions/generate/{operationId}":{"get":{"description":"Returns the status of a contract generation operation that was triggered via the **Generate contracts** endpoint.\n\nThe `operationId` is the last path segment of the `Location` header returned by the **Generate contracts** response.\n\nWhile 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.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/contracts/actions/generate/{operationId}","parameters":[{"in":"path","name":"operationId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGenerateContractStatusResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Get contract generation status","tags":["Contracts"]}}}}
```

## Get a contract

> 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiGetContractResponse":{"type":"object","properties":{"contract":{"type":"object","$ref":"#/components/schemas/ContractContentDTO"}}},"ContractContentDTO":{"type":"object","properties":{"contents":{"type":"string"},"created":{"type":"string","format":"date-time"},"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"},"id":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/{contractId}":{"get":{"description":"This endpoint allows you to retrieve a specific contract, including its YAML content.\n\n## Authorization\n\nOnly users with **View dataset** permission can view contracts.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n1000 requests/60 seconds","operationId":"GET/api/v1/contracts/{contractId}","parameters":[{"in":"path","name":"contractId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGetContractResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Get a contract","tags":["Contracts"]}}}}
```

## Publish a contract

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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiPublishContractRequestDTO":{"type":"object","properties":{"contents":{"type":"string"}},"required":["contents"]},"PublicApiPublishContractResponse":{"type":"object","properties":{"contract":{"type":"object","$ref":"#/components/schemas/ContractContentDTO"}}},"ContractContentDTO":{"type":"object","properties":{"contents":{"type":"string"},"created":{"type":"string","format":"date-time"},"datasetId":{"type":"string"},"datasetQualifiedName":{"type":"string"},"id":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/{contractId}":{"post":{"description":"This endpoint allows you to publish new YAML content for an existing contract.\n\nThe `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.\n\n## Authorization\n\nOnly users with **Manage contracts** permission can publish contracts.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"POST/api/v1/contracts/{contractId}","parameters":[{"in":"path","name":"contractId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiPublishContractRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiPublishContractResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Publish a contract","tags":["Contracts"]}}}}
```

## Verify a contract

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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiVerifyContractRequestDTO":{"type":"object","properties":{"checkPaths":{"type":"array","items":{"type":"string"}}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/{contractId}/verify":{"post":{"description":"This endpoint triggers a contract verification scan for the specified contract.\n\nThe 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.\n\nOptionally, you can provide `checkPaths` to limit verification to specific checks within the contract. Note: `checkPaths` may not be available for all organizations.\n\n## Authorization\n\nOnly users with **Manage contracts** permission can verify contracts.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n10 requests/60 seconds","operationId":"POST/api/v1/contracts/{contractId}/verify","parameters":[{"in":"path","name":"contractId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiVerifyContractRequestDTO"}}},"required":true},"responses":{"201":{"description":"Created","headers":{"Location":{"schema":{"type":"string"}},"X-Soda-Scan-Id":{"schema":{"type":"string"}}}},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"Verify a contract","tags":["Contracts"]}}}}
```

## List contract 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

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Contract Endpoints","name":"Contracts"}],"servers":[{"description":"Cloud EU","url":"https://cloud.soda.io"},{"description":"Cloud US","url":"https://cloud.us.soda.io"}],"security":[{"basicAuthApiKey":[]},{"cookieToken":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"},"cookieToken":{"in":"cookie","name":"token","type":"apiKey"}},"schemas":{"PublicApiListContractVersionsResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/ContractVersionDTO"}},"first":{"type":"boolean"},"last":{"type":"boolean"},"number":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"totalElements":{"type":"integer","format":"int32"},"totalPages":{"type":"integer","format":"int32"}},"required":["content","first","last","number","size","totalElements","totalPages"]},"ContractVersionDTO":{"type":"object","properties":{"checksum":{"type":"string"},"contents":{"type":"string"},"contractId":{"type":"string"},"created":{"type":"string","format":"date-time"},"creatorId":{"type":"string"},"id":{"type":"string"}}},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/contracts/{contractId}/versions":{"get":{"description":"This endpoint allows you to list versions of a specific contract.\n\nThis GET is a paginated API that uses the following parameters to request specific details:\n\n- `size`: Supply an integer value between 10 and 1000, inclusive. The default value is 10.\n\n- `page`: Supply an integer value. The default value is 0.\n\n- `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.\n\n## Authentication\n\nUser authentication required: `true`\n\nThis 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.\n\n## Tags\n\n`Contracts`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/contracts/{contractId}/versions","parameters":[{"in":"path","name":"contractId","required":true,"schema":{"type":"string"}},{"in":"query","name":"createdBefore","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"page","schema":{"type":"integer","format":"int32"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiListContractVersionsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Bad request"},"401":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not found"},"429":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Too many requests"},"500":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/ErrorResponse"}}},"description":"Internal server error"}},"summary":"List contract versions","tags":["Contracts"]}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.soda.io/reference/rest-api/contracts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.