> 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/data-catalog-data-lineage-and-grants-apis/units.md).

# Units

## Get unit

> Retrieves a specific unit by name.

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.8.2"},"paths":{"/api/units/{name}":{"get":{"description":"Retrieves a specific unit by name.","operationId":"TdDdWeb.UnitController.show","parameters":[{"description":"Unit name","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitShowResponse"}}},"description":"Unit retrieved"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdNotFoundErrorResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Get unit","tags":["Units"]}}},"components":{"schemas":{"UnitShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/UnitResponse"}},"required":["data"],"title":"UnitShowResponse","type":"object"},"UnitResponse":{"additionalProperties":false,"properties":{"events":{"items":{"additionalProperties":true,"type":"object"},"nullable":true,"type":"array"},"id":{"description":"Unit ID (may be absent in some responses)","nullable":true,"type":"integer"},"inserted_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/UnitStatus"},"updated_at":{"format":"date-time","nullable":true,"type":"string"}},"required":["name"],"title":"UnitResponse","type":"object"},"UnitStatus":{"additionalProperties":false,"properties":{"event":{"description":"Last event type","type":"string"},"info":{"additionalProperties":true,"description":"Status metadata","nullable":true,"type":"object"},"timestamp":{"description":"Timestamp of the status event","format":"date-time","nullable":true,"type":"string"}},"required":["event"],"title":"UnitStatus","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdNotFoundErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdNotFoundErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Update unit

> Updates a unit with nodes and relationships data from uploaded files.

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.8.2"},"paths":{"/api/units/{name}":{"put":{"description":"Updates a unit with nodes and relationships data from uploaded files.","operationId":"TdDdWeb.UnitController.update","parameters":[{"description":"Unit name","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UnitUpdateRequest"}}},"description":"Unit update payload","required":false},"responses":{"202":{"description":"Unit update accepted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update unit","tags":["Units"]}}},"components":{"schemas":{"UnitUpdateRequest":{"properties":{"nodes":{"description":"File upload for nodes data","format":"binary","type":"string"},"rels":{"description":"File upload for relationships data","format":"binary","type":"string"}},"required":["nodes","rels"],"title":"UnitUpdateRequest","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnprocessableEntityObjectResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Delete unit

> Deletes a unit asynchronously.

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.8.2"},"paths":{"/api/units/{name}":{"delete":{"description":"Deletes a unit asynchronously.","operationId":"TdDdWeb.UnitController.delete","parameters":[{"description":"Unit name","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Unit deletion accepted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdNotFoundErrorResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Delete unit","tags":["Units"]}}},"components":{"schemas":{"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdNotFoundErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdNotFoundErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Update unit

> Updates a unit with nodes and relationships data from uploaded files.

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.8.2"},"paths":{"/api/units/{name}":{"patch":{"description":"Updates a unit with nodes and relationships data from uploaded files.","operationId":"TdDdWeb.UnitController.update (2)","parameters":[{"description":"Unit name","in":"path","name":"name","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UnitUpdateRequest"}}},"description":"Unit update payload","required":false},"responses":{"202":{"description":"Unit update accepted"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Update unit","tags":["Units"]}}},"components":{"schemas":{"UnitUpdateRequest":{"properties":{"nodes":{"description":"File upload for nodes data","format":"binary","type":"string"},"rels":{"description":"File upload for relationships data","format":"binary","type":"string"}},"required":["nodes","rels"],"title":"UnitUpdateRequest","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnprocessableEntityObjectResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## List units

> Retrieves all active units

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.8.2"},"paths":{"/api/units":{"get":{"description":"Retrieves all active units","operationId":"TdDdWeb.UnitController.index","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitsIndexResponse"}}},"description":"Units retrieved"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List units","tags":["Units"]}}},"components":{"schemas":{"UnitsIndexResponse":{"additionalProperties":false,"properties":{"data":{"description":"List of units","items":{"$ref":"#/components/schemas/UnitResponse"},"type":"array"}},"required":["data"],"title":"UnitsIndexResponse","type":"object"},"UnitResponse":{"additionalProperties":false,"properties":{"events":{"items":{"additionalProperties":true,"type":"object"},"nullable":true,"type":"array"},"id":{"description":"Unit ID (may be absent in some responses)","nullable":true,"type":"integer"},"inserted_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/UnitStatus"},"updated_at":{"format":"date-time","nullable":true,"type":"string"}},"required":["name"],"title":"UnitResponse","type":"object"},"UnitStatus":{"additionalProperties":false,"properties":{"event":{"description":"Last event type","type":"string"},"info":{"additionalProperties":true,"description":"Status metadata","nullable":true,"type":"object"},"timestamp":{"description":"Timestamp of the status event","format":"date-time","nullable":true,"type":"string"}},"required":["event"],"title":"UnitStatus","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## Create unit

> Creates a new unit.

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.8.2"},"paths":{"/api/units":{"post":{"description":"Creates a new unit.","operationId":"TdDdWeb.UnitController.create","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitCreateRequest"}}},"description":"Unit create payload","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitShowResponse"}}},"description":"Unit created"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnprocessableEntityObjectResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"Create unit","tags":["Units"]}}},"components":{"schemas":{"UnitCreateRequest":{"additionalProperties":false,"properties":{"name":{"description":"Unit name","type":"string"},"status":{"description":"Unit status","nullable":true,"type":"boolean"}},"required":["name"],"title":"UnitCreateRequest","type":"object"},"UnitShowResponse":{"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/UnitResponse"}},"required":["data"],"title":"UnitShowResponse","type":"object"},"UnitResponse":{"additionalProperties":false,"properties":{"events":{"items":{"additionalProperties":true,"type":"object"},"nullable":true,"type":"array"},"id":{"description":"Unit ID (may be absent in some responses)","nullable":true,"type":"integer"},"inserted_at":{"format":"date-time","nullable":true,"type":"string"},"name":{"type":"string"},"status":{"$ref":"#/components/schemas/UnitStatus"},"updated_at":{"format":"date-time","nullable":true,"type":"string"}},"required":["name"],"title":"UnitResponse","type":"object"},"UnitStatus":{"additionalProperties":false,"properties":{"event":{"description":"Last event type","type":"string"},"info":{"additionalProperties":true,"description":"Status metadata","nullable":true,"type":"object"},"timestamp":{"description":"Timestamp of the status event","format":"date-time","nullable":true,"type":"string"}},"required":["event"],"title":"UnitStatus","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdUnprocessableEntityObjectResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnprocessableEntityObjectResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```

## List unit events

> Retrieves all events for a specific unit

```json
{"openapi":"3.0.0","info":{"title":"td-dd","version":"Truedat 8.8.2"},"paths":{"/api/units/{unit_name}/events":{"get":{"description":"Retrieves all events for a specific unit","operationId":"TdDdWeb.UnitEventController.index","parameters":[{"description":"Unit name","in":"path","name":"unit_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitEventsIndexResponse"}}},"description":"Unit events retrieved"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdUnauthorizedResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdForbiddenResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdNotFoundErrorResponse"}}},"description":"Not found"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TdDdInternalServerErrorResponse"}}},"description":"Internal Server Error"}},"summary":"List unit events","tags":["Units"]}}},"components":{"schemas":{"UnitEventsIndexResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/UnitEventResponse"},"type":"array"}},"title":"UnitEventsIndexResponse","type":"object"},"UnitEventResponse":{"properties":{"data":{"additionalProperties":true,"nullable":true,"type":"object"},"id":{"type":"integer"},"inserted_at":{"format":"date-time","type":"string"},"status":{"type":"string"},"type":{"type":"string"},"unit_id":{"type":"integer"},"updated_at":{"format":"date-time","type":"string"}},"title":"UnitEventResponse","type":"object"},"TdDdUnauthorizedResponse":{"anyOf":[{"$ref":"#/components/schemas/TdDdUnauthorizedMessageResponse"},{"$ref":"#/components/schemas/TdDdUnauthorizedErrorResponse"}],"description":"Unauthorized response from auth plug or error view","title":"TdDdUnauthorizedResponse"},"TdDdUnauthorizedMessageResponse":{"additionalProperties":false,"properties":{"message":{"type":"string"}},"required":["message"],"title":"TdDdUnauthorizedMessageResponse","type":"object"},"TdDdUnauthorizedErrorResponse":{"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdUnauthorizedErrorResponse","type":"object"},"TdDdForbiddenResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdForbiddenResponse","type":"object"},"TdDdNotFoundErrorResponse":{"additionalProperties":false,"properties":{"errors":{"properties":{"detail":{"type":"string"}},"type":"object"}},"required":["errors"],"title":"TdDdNotFoundErrorResponse","type":"object"},"TdDdInternalServerErrorResponse":{"additionalProperties":false,"properties":{"errors":{"additionalProperties":false,"properties":{"detail":{"type":"string"}},"required":["detail"],"type":"object"}},"required":["errors"],"title":"TdDdInternalServerErrorResponse","type":"object"}}}}
```