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

# Domains

## Get parentable domain IDs

> Return IDs of domains that can be assigned as parents to the specified domain.

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains/{domain_id}/parentable_ids":{"get":{"description":"Return IDs of domains that can be assigned as parents to the specified domain.","operationId":"TdBgWeb.DomainController.parentable_ids","parameters":[{"description":"Domain ID","in":"path","name":"domain_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParentableDomainIdsResponse"}}},"description":"Parentable IDs"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get parentable domain IDs","tags":["Domains"]}}},"components":{"schemas":{"ParentableDomainIdsResponse":{"additionalProperties":false,"properties":{"data":{"description":"List of domain IDs that can be parents","items":{"type":"integer"},"type":"array"}},"required":["data"],"title":"ParentableDomainIdsResponse","type":"object"},"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```

## Count business concepts in domain for user

> Count the business concepts within a domain for the specified user.

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains/{domain_id}/business_concepts/{user_name}/count":{"get":{"description":"Count the business concepts within a domain for the specified user.","operationId":"TdBgWeb.DomainController.count_bc_in_domain_for_user","parameters":[{"description":"Domain ID","in":"path","name":"domain_id","required":true,"schema":{"type":"string"}},{"description":"User name","in":"query","name":"user_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainBCCountResponse"}}},"description":"Count response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgNotFoundResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Count business concepts in domain for user","tags":["Domains"]}}},"components":{"schemas":{"DomainBCCountResponse":{"additionalProperties":false,"properties":{"data":{"properties":{"counter":{"description":"Number of business concepts","type":"integer"}},"type":"object"}},"required":["data"],"title":"DomainBCCountResponse","type":"object"},"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgNotFoundResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgNotFoundResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```

## List domains

> Returns all domains, optionally filtered by actions and permissions

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains":{"get":{"description":"Returns all domains, optionally filtered by actions and permissions","operationId":"TdBgWeb.DomainController.index","parameters":[{"description":"Comma-separated list of actions (e.g. show,create,update)","in":"query","name":"actions","required":false,"schema":{"type":"string"}},{"description":"Filter mode (e.g. all)","in":"query","name":"filter","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainIndexResponse"}}},"description":"Domains list"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List domains","tags":["Domains"]}}},"components":{"schemas":{"DomainIndexResponse":{"additionalProperties":false,"properties":{"_actions":{"type":"object"},"data":{"items":{"$ref":"#/components/schemas/Domain"},"type":"array"},"hypermedia":{"additionalProperties":true,"description":"Hypermedia links","type":"object"}},"title":"DomainIndexResponse","type":"object"},"Domain":{"additionalProperties":false,"properties":{"description":{"description":"Domain description","type":"string"},"domain_group":{"additionalProperties":false,"description":"Associated domain group","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"enum":["root"],"type":"string"}},"type":"object"},"external_id":{"description":"External identifier","type":"string"},"id":{"description":"Domain ID","type":"integer"},"name":{"description":"Domain name","type":"string"},"parent_id":{"description":"Parent domain ID","nullable":true,"type":"integer"},"parents":{"description":"Ancestor domains","items":{"additionalProperties":false,"properties":{"external_id":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id"],"type":"object"},"nullable":true,"type":"array"},"type":{"default":"domain","description":"Domain type","nullable":true,"type":"string"}},"required":["id"],"title":"Domain","type":"object"},"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```

## Create domain

> Create a new domain with the provided domain payload.

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains":{"post":{"description":"Create a new domain with the provided domain payload.","operationId":"TdBgWeb.DomainController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainCreateRequest"}}},"description":"Domain payload","required":false},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainShowResponse"}}},"description":"Domain created"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create domain","tags":["Domains"]}}},"components":{"schemas":{"DomainCreateRequest":{"additionalProperties":false,"properties":{"domain":{"additionalProperties":false,"properties":{"name":{"description":"Domain name","type":"string"},"parent_id":{"description":"Parent domain ID","nullable":true,"type":"integer"}},"required":["name"],"type":"object"}},"required":["domain"],"title":"DomainCreateRequest","type":"object"},"DomainShowResponse":{"additionalProperties":false,"properties":{"_actions":{"type":"object"},"data":{"$ref":"#/components/schemas/Domain"},"hypermedia":{"additionalProperties":true,"type":"object"}},"required":["data"],"title":"DomainShowResponse","type":"object"},"Domain":{"additionalProperties":false,"properties":{"description":{"description":"Domain description","type":"string"},"domain_group":{"additionalProperties":false,"description":"Associated domain group","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"enum":["root"],"type":"string"}},"type":"object"},"external_id":{"description":"External identifier","type":"string"},"id":{"description":"Domain ID","type":"integer"},"name":{"description":"Domain name","type":"string"},"parent_id":{"description":"Parent domain ID","nullable":true,"type":"integer"},"parents":{"description":"Ancestor domains","items":{"additionalProperties":false,"properties":{"external_id":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id"],"type":"object"},"nullable":true,"type":"array"},"type":{"default":"domain","description":"Domain type","nullable":true,"type":"string"}},"required":["id"],"title":"Domain","type":"object"},"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgUnprocessableEntityObjectResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgUnprocessableEntityObjectResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```

## Get domain by id

> Retrieve details for a specific domain by its ID.

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains/{id}":{"get":{"description":"Retrieve details for a specific domain by its ID.","operationId":"TdBgWeb.DomainController.show","parameters":[{"description":"Domain ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainShowResponse"}}},"description":"Domain"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get domain by id","tags":["Domains"]}}},"components":{"schemas":{"DomainShowResponse":{"additionalProperties":false,"properties":{"_actions":{"type":"object"},"data":{"$ref":"#/components/schemas/Domain"},"hypermedia":{"additionalProperties":true,"type":"object"}},"required":["data"],"title":"DomainShowResponse","type":"object"},"Domain":{"additionalProperties":false,"properties":{"description":{"description":"Domain description","type":"string"},"domain_group":{"additionalProperties":false,"description":"Associated domain group","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"enum":["root"],"type":"string"}},"type":"object"},"external_id":{"description":"External identifier","type":"string"},"id":{"description":"Domain ID","type":"integer"},"name":{"description":"Domain name","type":"string"},"parent_id":{"description":"Parent domain ID","nullable":true,"type":"integer"},"parents":{"description":"Ancestor domains","items":{"additionalProperties":false,"properties":{"external_id":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id"],"type":"object"},"nullable":true,"type":"array"},"type":{"default":"domain","description":"Domain type","nullable":true,"type":"string"}},"required":["id"],"title":"Domain","type":"object"},"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```

## Update domain

> Update an existing domain using the provided payload.

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains/{id}":{"put":{"description":"Update an existing domain using the provided payload.","operationId":"TdBgWeb.DomainController.update","parameters":[{"description":"Domain ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainUpdateRequest"}}},"description":"Domain update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainShowResponse"}}},"description":"Domain updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update domain","tags":["Domains"]}}},"components":{"schemas":{"DomainUpdateRequest":{"additionalProperties":false,"properties":{"domain":{"additionalProperties":false,"properties":{"name":{"description":"Updated name","type":"string"},"parent_id":{"description":"New parent ID","nullable":true,"type":"integer"}},"type":"object"}},"required":["domain"],"title":"DomainUpdateRequest","type":"object"},"DomainShowResponse":{"additionalProperties":false,"properties":{"_actions":{"type":"object"},"data":{"$ref":"#/components/schemas/Domain"},"hypermedia":{"additionalProperties":true,"type":"object"}},"required":["data"],"title":"DomainShowResponse","type":"object"},"Domain":{"additionalProperties":false,"properties":{"description":{"description":"Domain description","type":"string"},"domain_group":{"additionalProperties":false,"description":"Associated domain group","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"enum":["root"],"type":"string"}},"type":"object"},"external_id":{"description":"External identifier","type":"string"},"id":{"description":"Domain ID","type":"integer"},"name":{"description":"Domain name","type":"string"},"parent_id":{"description":"Parent domain ID","nullable":true,"type":"integer"},"parents":{"description":"Ancestor domains","items":{"additionalProperties":false,"properties":{"external_id":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id"],"type":"object"},"nullable":true,"type":"array"},"type":{"default":"domain","description":"Domain type","nullable":true,"type":"string"}},"required":["id"],"title":"Domain","type":"object"},"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgNotFoundResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgNotFoundResponse","type":"object"},"TdBgUnprocessableEntityObjectResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgUnprocessableEntityObjectResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```

## Delete domain

> Delete a domain identified by the given ID.

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains/{id}":{"delete":{"description":"Delete a domain identified by the given ID.","operationId":"TdBgWeb.DomainController.delete","parameters":[{"description":"Domain ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Domain deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgNotFoundResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete domain","tags":["Domains"]}}},"components":{"schemas":{"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgNotFoundResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgNotFoundResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```

## Update domain

> Update an existing domain using the provided payload.

```json
{"openapi":"3.0.0","info":{"title":"td-bg","version":"Truedat 8.8.0"},"paths":{"/api/domains/{id}":{"patch":{"description":"Update an existing domain using the provided payload.","operationId":"TdBgWeb.DomainController.update (2)","parameters":[{"description":"Domain ID","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainUpdateRequest"}}},"description":"Domain update payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainShowResponse"}}},"description":"Domain updated"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgNotFoundResponse"}}},"description":"Not found"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdBgInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update domain","tags":["Domains"]}}},"components":{"schemas":{"DomainUpdateRequest":{"additionalProperties":false,"properties":{"domain":{"additionalProperties":false,"properties":{"name":{"description":"Updated name","type":"string"},"parent_id":{"description":"New parent ID","nullable":true,"type":"integer"}},"type":"object"}},"required":["domain"],"title":"DomainUpdateRequest","type":"object"},"DomainShowResponse":{"additionalProperties":false,"properties":{"_actions":{"type":"object"},"data":{"$ref":"#/components/schemas/Domain"},"hypermedia":{"additionalProperties":true,"type":"object"}},"required":["data"],"title":"DomainShowResponse","type":"object"},"Domain":{"additionalProperties":false,"properties":{"description":{"description":"Domain description","type":"string"},"domain_group":{"additionalProperties":false,"description":"Associated domain group","nullable":true,"properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"enum":["root"],"type":"string"}},"type":"object"},"external_id":{"description":"External identifier","type":"string"},"id":{"description":"Domain ID","type":"integer"},"name":{"description":"Domain name","type":"string"},"parent_id":{"description":"Parent domain ID","nullable":true,"type":"integer"},"parents":{"description":"Ancestor domains","items":{"additionalProperties":false,"properties":{"external_id":{"type":"string"},"id":{"type":"integer"},"name":{"type":"string"}},"required":["id"],"type":"object"},"nullable":true,"type":"array"},"type":{"default":"domain","description":"Domain type","nullable":true,"type":"string"}},"required":["id"],"title":"Domain","type":"object"},"TdBgUnauthorizedResponse":{"properties":{"errors":{"properties":{"message":{"type":"string"}},"type":"object"}},"title":"TdBgUnauthorizedResponse","type":"object"},"TdBgForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgForbiddenResponse","type":"object"},"TdBgNotFoundResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgNotFoundResponse","type":"object"},"TdBgUnprocessableEntityObjectResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgUnprocessableEntityObjectResponse","type":"object"},"TdBgInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdBgInternalServerErrorResponse","type":"object"}}}}
```