> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/apis/rest-api/domains.md).

# Domains

Soda Cloud API Domain Endpoints

## List domains

> This endpoint lists the domains of your organization, sorted by \`name\`.\
> \
> This GET is a paginated API that uses the following parameters:\
> \
> \- \`cursor\`: Omit for the first page. Pass the previous response's \`nextCursor\`, with the same other parameters, to continue after its last item. Cursors are opaque; invalid cursors return 400.\
> \
> \- \`size\`: Number of items per page, from 1 to 1000, default 10. The size may change between pages.\
> \
> \- \`name\`: Optionally, return only the domain with this exact \`name\`, or an empty \`content\` when no domain has it. Use it to look a domain up by its \`name\` before creating it. A value that is not a valid domain name returns 400.\
> \
> The response contains \`content\` and, when more items are available, \`nextCursor\`. An absent \`nextCursor\` marks the end of the results. Page numbers and totals are not 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\
> \
> \`Domains\`\
> \
> \## Rate limiting\
> \
> 60 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Domain Endpoints","name":"Domains"}],"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":{"PublicApiListDomainsResponse":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","$ref":"#/components/schemas/DomainContentDTO"}},"nextCursor":{"type":"string"}},"required":["content"]},"DomainContentDTO":{"type":"object","properties":{"created":{"type":"string","format":"date-time"},"description":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"},"name":{"type":"string","description":"The unique handle of the domain, the value other resources refer to it by. It cannot change; the label can."}},"required":["created","id","label","lastUpdated","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/domains":{"get":{"description":"This endpoint lists the domains of your organization, sorted by `name`.\n\nThis GET is a paginated API that uses the following parameters:\n\n- `cursor`: Omit for the first page. Pass the previous response's `nextCursor`, with the same other parameters, to continue after its last item. Cursors are opaque; invalid cursors return 400.\n\n- `size`: Number of items per page, from 1 to 1000, default 10. The size may change between pages.\n\n- `name`: Optionally, return only the domain with this exact `name`, or an empty `content` when no domain has it. Use it to look a domain up by its `name` before creating it. A value that is not a valid domain name returns 400.\n\nThe response contains `content` and, when more items are available, `nextCursor`. An absent `nextCursor` marks the end of the results. Page numbers and totals are not 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`Domains`\n\n## Rate limiting\n\n60 requests/60 seconds","operationId":"GET/api/v1/domains","parameters":[{"in":"query","name":"cursor","schema":{"type":"string"}},{"in":"query","name":"name","schema":{"type":"string"}},{"in":"query","name":"size","schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiListDomainsResponse"}}},"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"},"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 domains","tags":["Domains"]}}}}
```

## Create a domain

> This endpoint creates a domain in your organization. A domain groups the resources of one part of your organization, such as a business unit or a team.\
> \
> \`name\` is the handle other resources refer to the domain by. It must be lowercase letters and digits separated by single - or \_, starting with a letter; true, false, null, yes, no, on, off, y, n and base are reserved; at most 64 characters. It is unique within the organization and cannot change afterwards.\
> \
> \`label\` is the display name, at most 255 characters. \`description\` is optional, at most 4000 characters. Both can be changed later.\
> \
> Requires the \`manageOrganisationSettings\` right. A name that is already in use returns 400 with code \`domain\_name\_already\_exists\`.\
> \
> \## 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.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Domains\`\
> \
> \## Rate limiting\
> \
> 100 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Domain Endpoints","name":"Domains"}],"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":{"PublicApiCreateDomainRequestDTO":{"type":"object","properties":{"description":{"type":"string"},"label":{"type":"string"},"name":{"type":"string"}},"required":["label","name"]},"PublicApiCreateDomainResponse":{"type":"object","properties":{"domain":{"type":"object","$ref":"#/components/schemas/DomainContentDTO"}},"required":["domain"]},"DomainContentDTO":{"type":"object","properties":{"created":{"type":"string","format":"date-time"},"description":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"},"name":{"type":"string","description":"The unique handle of the domain, the value other resources refer to it by. It cannot change; the label can."}},"required":["created","id","label","lastUpdated","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/domains":{"post":{"description":"This endpoint creates a domain in your organization. A domain groups the resources of one part of your organization, such as a business unit or a team.\n\n`name` is the handle other resources refer to the domain by. It must be lowercase letters and digits separated by single - or _, starting with a letter; true, false, null, yes, no, on, off, y, n and base are reserved; at most 64 characters. It is unique within the organization and cannot change afterwards.\n\n`label` is the display name, at most 255 characters. `description` is optional, at most 4000 characters. Both can be changed later.\n\nRequires the `manageOrganisationSettings` right. A name that is already in use returns 400 with code `domain_name_already_exists`.\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## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Domains`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"POST/api/v1/domains","requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateDomainRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiCreateDomainResponse"}}},"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"},"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 domain","tags":["Domains"]}}}}
```

## Get a domain

> This endpoint returns one domain of your organization by its id.\
> \
> An unknown id, or the id of a domain in another organization, returns 404 with code \`domain\_not\_found\`.\
> \
> \## 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\
> \
> \`Domains\`\
> \
> \## Rate limiting\
> \
> 1000 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Domain Endpoints","name":"Domains"}],"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":{"PublicApiGetDomainResponse":{"type":"object","properties":{"domain":{"type":"object","$ref":"#/components/schemas/DomainContentDTO"}},"required":["domain"]},"DomainContentDTO":{"type":"object","properties":{"created":{"type":"string","format":"date-time"},"description":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"},"name":{"type":"string","description":"The unique handle of the domain, the value other resources refer to it by. It cannot change; the label can."}},"required":["created","id","label","lastUpdated","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/domains/{domainId}":{"get":{"description":"This endpoint returns one domain of your organization by its id.\n\nAn unknown id, or the id of a domain in another organization, returns 404 with code `domain_not_found`.\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`Domains`\n\n## Rate limiting\n\n1000 requests/60 seconds","operationId":"GET/api/v1/domains/{domainId}","parameters":[{"in":"path","name":"domainId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiGetDomainResponse"}}},"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 domain","tags":["Domains"]}}}}
```

## Update a domain

> This endpoint replaces the \`label\` (at most 255 characters) and the \`description\` (optional, at most 4000 characters) of a domain. A body without \`description\` clears it.\
> \
> The \`name\` of a domain cannot change. Requires the \`manageOrganisationSettings\` right.\
> \
> An unknown id, or the id of a domain in another organization, returns 404 with code \`domain\_not\_found\`.\
> \
> \## 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.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Domains\`\
> \
> \## Rate limiting\
> \
> 100 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Domain Endpoints","name":"Domains"}],"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":{"PublicApiUpdateDomainRequestDTO":{"type":"object","properties":{"description":{"type":"string"},"label":{"type":"string"}},"required":["label"]},"PublicApiUpdateDomainResponse":{"type":"object","properties":{"domain":{"type":"object","$ref":"#/components/schemas/DomainContentDTO"}},"required":["domain"]},"DomainContentDTO":{"type":"object","properties":{"created":{"type":"string","format":"date-time"},"description":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"lastUpdated":{"type":"string","format":"date-time"},"name":{"type":"string","description":"The unique handle of the domain, the value other resources refer to it by. It cannot change; the label can."}},"required":["created","id","label","lastUpdated","name"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/domains/{domainId}":{"post":{"description":"This endpoint replaces the `label` (at most 255 characters) and the `description` (optional, at most 4000 characters) of a domain. A body without `description` clears it.\n\nThe `name` of a domain cannot change. Requires the `manageOrganisationSettings` right.\n\nAn unknown id, or the id of a domain in another organization, returns 404 with code `domain_not_found`.\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## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Domains`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"POST/api/v1/domains/{domainId}","parameters":[{"in":"path","name":"domainId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiUpdateDomainRequestDTO"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiUpdateDomainResponse"}}},"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":"Update a domain","tags":["Domains"]}}}}
```

## Delete a domain

> This endpoint deletes a domain of your organization. Requires the \`manageOrganisationSettings\` right.\
> \
> The deletion is performed asynchronously: the response confirms that it was scheduled, and the domain disappears from the list and the lookup shortly after.\
> \
> An unknown id, or the id of a domain in another organization, returns 404 with code \`domain\_not\_found\`.\
> \
> A domain that a data product refers to cannot be deleted: the response is 400 with code \`domain\_still\_in\_use\`, and the message names up to ten of the data products you can view. If a data product starts to refer to the domain after the deletion was scheduled, the domain is not deleted and stays in the list and the lookup.\
> \
> \## 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.\
> \
> \## Authorization\
> \
> Users must have global role permission MANAGE\_ORGANISATION\_SETTINGS to execute this call.\
> \
> \## Auditable\
> \
> This API is marked as \*\*audited\*\* on execution.\
> \
> \## Tags\
> \
> \`Domains\`\
> \
> \## Rate limiting\
> \
> 100 requests/60 seconds

```json
{"openapi":"3.1.0","info":{"title":"Soda Cloud API v4","version":"v1"},"tags":[{"description":"Soda Cloud API Domain Endpoints","name":"Domains"}],"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":{"PublicApiDeleteDomainResponse":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"ErrorResponse":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/api/v1/domains/{domainId}":{"delete":{"description":"This endpoint deletes a domain of your organization. Requires the `manageOrganisationSettings` right.\n\nThe deletion is performed asynchronously: the response confirms that it was scheduled, and the domain disappears from the list and the lookup shortly after.\n\nAn unknown id, or the id of a domain in another organization, returns 404 with code `domain_not_found`.\n\nA domain that a data product refers to cannot be deleted: the response is 400 with code `domain_still_in_use`, and the message names up to ten of the data products you can view. If a data product starts to refer to the domain after the deletion was scheduled, the domain is not deleted and stays in the list and the lookup.\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## Authorization\n\nUsers must have global role permission MANAGE_ORGANISATION_SETTINGS to execute this call.\n\n## Auditable\n\nThis API is marked as **audited** on execution.\n\n## Tags\n\n`Domains`\n\n## Rate limiting\n\n100 requests/60 seconds","operationId":"DELETE/api/v1/domains/{domainId}","parameters":[{"in":"path","name":"domainId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","$ref":"#/components/schemas/PublicApiDeleteDomainResponse"}}},"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":"Delete a domain","tags":["Domains"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/apis/rest-api/domains.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
