# 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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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 enforces authentication using the API keys you provide in the \`Basic\` authentication header.\
> \
> \## 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":[]}],"components":{"securitySchemes":{"basicAuthApiKey":{"scheme":"basic","type":"http"}},"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 enforces authentication using the API keys you provide in the `Basic` authentication header.\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"]}}}}
```