> 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.12/api-integrations/link-manager-apis/tags.md).
# Tags
## List all tags
> Returns tags available to the current caller, optionally filtered by dynamic \`value\` fields.\
> \
> The optional value query parameter (a JSON object) filters tags by matching fields inside the tag’s value metadata. Common filter keys include target\_type (e.g., "ingest", "data\_field"), type (e.g., "business\_concept", "technical"), and expandable ("true"/"false").\
> \
> This endpoint supports deep object filtering so users can query tag metadata precisely.\
> \
> If no filter is sent, the API returns the available tags without additional narrowing. The results only include tags the current user can access.
```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/tags":{"get":{"description":"Returns tags available to the current caller, optionally filtered by dynamic `value` fields.\n\nThe optional value query parameter (a JSON object) filters tags by matching fields inside the tag’s value metadata. Common filter keys include target_type (e.g., \"ingest\", \"data_field\"), type (e.g., \"business_concept\", \"technical\"), and expandable (\"true\"/\"false\").\n\nThis endpoint supports deep object filtering so users can query tag metadata precisely.\n\nIf no filter is sent, the API returns the available tags without additional narrowing. The results only include tags the current user can access.\n","operationId":"TdLmWeb.TagController.index","parameters":[{"description":"Filter by tag value fields. The optional `value` parameter is a JSON object that filters tags where the `value` field matches the provided keys.\nCommon filter keys:\n - `target_type` (string): e.g., \"ingest\", \"data_field\"\n - `type` (string): e.g., \"business_concept\", \"technical\"\n - `expandable` (string): e.g., \"true\" or \"false\"\n\nYou can also use any other key present in the tag's `value` object.\nExample: `{\"target_type\": \"ingest\", \"type\": \"business_concept\"}`\n","explode":true,"in":"query","name":"value","required":false,"schema":{"additionalProperties":true,"type":"object"},"style":"deepObject"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagListResponse"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List all tags","tags":["Tags"]}}},"components":{"schemas":{"TagListResponse":{"additionalProperties":false,"properties":{"data":{"description":"List of tags","items":{"$ref":"#/components/schemas/TagObject"},"type":"array"}},"required":["data"],"title":"TagListResponse","type":"object"},"TagObject":{"additionalProperties":false,"properties":{"id":{"description":"Tag ID","type":"integer"},"value":{"$ref":"#/components/schemas/TagValue"}},"required":["id","value"],"title":"TagObject","type":"object"},"TagValue":{"additionalProperties":true,"description":"Dynamic value of a tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"title":"TagValue","type":"object"},"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```
## Create a new tag
> Creates a new tag and stores its value metadata.\
> \
> \*\*Only administrators\*\* can create a new tag.
```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/tags":{"post":{"description":"Creates a new tag and stores its value metadata.\n\n**Only administrators** can create a new tag.\n","operationId":"TdLmWeb.TagController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagRequest"}}},"description":"Tag data","required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagShowResponse"}}},"description":"Created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmBadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnprocessableEntityResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create a new tag","tags":["Tags"]}}},"components":{"schemas":{"TagRequest":{"additionalProperties":false,"properties":{"tag":{"additionalProperties":false,"description":"Tag data","properties":{"value":{"additionalProperties":true,"description":"Dynamic value of the tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"type":"object"}},"required":["value"],"type":"object"}},"required":["tag"],"title":"TagRequest","type":"object"},"TagShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/TagObject"}},"required":["data"],"title":"TagShowResponse","type":"object"},"TagObject":{"additionalProperties":false,"properties":{"id":{"description":"Tag ID","type":"integer"},"value":{"$ref":"#/components/schemas/TagValue"}},"required":["id","value"],"title":"TagObject","type":"object"},"TagValue":{"additionalProperties":true,"description":"Dynamic value of a tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"title":"TagValue","type":"object"},"TdLmBadRequestResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmBadRequestResponse","type":"object"},"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmForbiddenResponse","type":"object"},"TdLmUnprocessableEntityResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnprocessableEntityResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```
## Search tags
> Searches tags using request body filters, allowing users to find tags by tag value fields such as target resource type or tag category.\
> \
> If no filter criteria are provided, the request behaves as a general tag listing.\
> \
> The results only include tags the current user can access.
```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/tags/search":{"post":{"description":"Searches tags using request body filters, allowing users to find tags by tag value fields such as target resource type or tag category.\n\nIf no filter criteria are provided, the request behaves as a general tag listing.\n\nThe results only include tags the current user can access.\n","operationId":"TdLmWeb.TagController.search","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagSearchRequest"}}},"description":"Search filters","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagListResponse"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Search tags","tags":["Tags"]}}},"components":{"schemas":{"TagSearchRequest":{"additionalProperties":false,"description":"Search filters for tags. Can filter by value fields (e.g., target_type).","properties":{"value":{"additionalProperties":true,"description":"Filter by tag value fields","type":"object"}},"title":"TagSearchRequest","type":"object"},"TagListResponse":{"additionalProperties":false,"properties":{"data":{"description":"List of tags","items":{"$ref":"#/components/schemas/TagObject"},"type":"array"}},"required":["data"],"title":"TagListResponse","type":"object"},"TagObject":{"additionalProperties":false,"properties":{"id":{"description":"Tag ID","type":"integer"},"value":{"$ref":"#/components/schemas/TagValue"}},"required":["id","value"],"title":"TagObject","type":"object"},"TagValue":{"additionalProperties":true,"description":"Dynamic value of a tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"title":"TagValue","type":"object"},"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```
## Get a tag by ID
> Retrieves a single tag by its identifier, returning the tag metadata and value object for the requested resource.\
> \
> Requires access to the tag and the related resource data.
```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/tags/{id}":{"get":{"description":"Retrieves a single tag by its identifier, returning the tag metadata and value object for the requested resource.\n\nRequires access to the tag and the related resource data.\n","operationId":"TdLmWeb.TagController.show","parameters":[{"description":"Tag ID","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagShowResponse"}}},"description":"OK"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get a tag by ID","tags":["Tags"]}}},"components":{"schemas":{"TagShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/TagObject"}},"required":["data"],"title":"TagShowResponse","type":"object"},"TagObject":{"additionalProperties":false,"properties":{"id":{"description":"Tag ID","type":"integer"},"value":{"$ref":"#/components/schemas/TagValue"}},"required":["id","value"],"title":"TagObject","type":"object"},"TagValue":{"additionalProperties":true,"description":"Dynamic value of a tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"title":"TagValue","type":"object"},"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmForbiddenResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```
## Update a tag
> Updates an existing tag's metadata, allowing users to change its value object and associated filtering characteristics.\
> \
> \*\*Only administrators\*\* can update a tag.
```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/tags/{id}":{"put":{"description":"Updates an existing tag's metadata, allowing users to change its value object and associated filtering characteristics.\n\n**Only administrators** can update a tag.\n","operationId":"TdLmWeb.TagController.update","parameters":[{"description":"Tag ID","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagRequest"}}},"description":"Tag data","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagShowResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmBadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnprocessableEntityResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update a tag","tags":["Tags"]}}},"components":{"schemas":{"TagRequest":{"additionalProperties":false,"properties":{"tag":{"additionalProperties":false,"description":"Tag data","properties":{"value":{"additionalProperties":true,"description":"Dynamic value of the tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"type":"object"}},"required":["value"],"type":"object"}},"required":["tag"],"title":"TagRequest","type":"object"},"TagShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/TagObject"}},"required":["data"],"title":"TagShowResponse","type":"object"},"TagObject":{"additionalProperties":false,"properties":{"id":{"description":"Tag ID","type":"integer"},"value":{"$ref":"#/components/schemas/TagValue"}},"required":["id","value"],"title":"TagObject","type":"object"},"TagValue":{"additionalProperties":true,"description":"Dynamic value of a tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"title":"TagValue","type":"object"},"TdLmBadRequestResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmBadRequestResponse","type":"object"},"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmForbiddenResponse","type":"object"},"TdLmUnprocessableEntityResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnprocessableEntityResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```
## Delete a tag
> Permanently deletes a tag from the system, removing the metadata used to classify relations and resources.\
> \
> \*\*Only administrators\*\* can delete a tag.
```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/tags/{id}":{"delete":{"description":"Permanently deletes a tag from the system, removing the metadata used to classify relations and resources.\n\n**Only administrators** can delete a tag.\n","operationId":"TdLmWeb.TagController.delete","parameters":[{"description":"Tag ID","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"responses":{"204":{"description":"Tag deleted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete a tag","tags":["Tags"]}}},"components":{"schemas":{"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmForbiddenResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```
## Update a tag
> Updates an existing tag's metadata, allowing users to change its value object and associated filtering characteristics.\
> \
> \*\*Only administrators\*\* can update a tag.
```json
{"openapi":"3.0.0","info":{"title":"td-lm","version":"Truedat 8.11.1"},"paths":{"/api/tags/{id}":{"patch":{"description":"Updates an existing tag's metadata, allowing users to change its value object and associated filtering characteristics.\n\n**Only administrators** can update a tag.\n","operationId":"TdLmWeb.TagController.update (2)","parameters":[{"description":"Tag ID","in":"path","name":"id","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagRequest"}}},"description":"Tag data","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagShowResponse"}}},"description":"OK"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmBadRequestResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmUnprocessableEntityResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdLmInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update a tag","tags":["Tags"]}}},"components":{"schemas":{"TagRequest":{"additionalProperties":false,"properties":{"tag":{"additionalProperties":false,"description":"Tag data","properties":{"value":{"additionalProperties":true,"description":"Dynamic value of the tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"type":"object"}},"required":["value"],"type":"object"}},"required":["tag"],"title":"TagRequest","type":"object"},"TagShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/TagObject"}},"required":["data"],"title":"TagShowResponse","type":"object"},"TagObject":{"additionalProperties":false,"properties":{"id":{"description":"Tag ID","type":"integer"},"value":{"$ref":"#/components/schemas/TagValue"}},"required":["id","value"],"title":"TagObject","type":"object"},"TagValue":{"additionalProperties":true,"description":"Dynamic value of a tag","properties":{"expandable":{"description":"Optional expandable flag","nullable":true,"type":"string"},"target_type":{"description":"Target resource type","type":"string"},"type":{"description":"Tag type","type":"string"}},"required":["target_type","type"],"title":"TagValue","type":"object"},"TdLmBadRequestResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmBadRequestResponse","type":"object"},"TdLmUnauthorizedResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnauthorizedResponse","type":"object"},"TdLmForbiddenResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmForbiddenResponse","type":"object"},"TdLmUnprocessableEntityResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmUnprocessableEntityResponse","type":"object"},"TdLmInternalServerErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"title":"TdLmInternalServerErrorResponse","type":"object"}}}}
```