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

# Entity Types

Use these operations to interact with [entity types](/ingesting-data-into-cortex/entities-overview/entities/adding-entities/entity-types.md) in Cortex.

### Required permissions

Your API key must have the `Edit entity types` permission.

## Operations

## List entity types

> List entity types\
> \
> Response excludes Cortex default types of service, domain, and team.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Entity Types"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CatalogDefinitionsListResponse":{"required":["definitions","page","total","totalPages"],"type":"object","properties":{"definitions":{"type":"array","items":{"$ref":"#/components/schemas/CatalogDefinitionResponse"}},"page":{"type":"integer","description":"Current page number, 0-indexed","format":"int32"},"total":{"type":"integer","description":"Total number of results","format":"int32"},"totalPages":{"type":"integer","description":"Total number of pages","format":"int32"}}},"CatalogDefinitionResponse":{"required":["schema","source","type"],"type":"object","properties":{"description":{"type":"string"},"iconTag":{"type":"string"},"name":{"type":"string"},"schema":{"$ref":"#/components/schemas/JsonNode"},"source":{"type":"string","enum":["CORTEX","CUSTOM"]},"type":{"type":"string"}}},"JsonNode":{"type":"object"},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/definitions":{"get":{"description":"List entity types\n\nResponse excludes Cortex default types of service, domain, and team.","operationId":"listDefinitions","parameters":[{"description":"When true, returns the built-in entity types that Cortex provides, such as `rds` and `s3`. Defaults to false.","in":"query","name":"includeBuiltIn","required":false,"schema":{"type":"boolean"}},{"description":"Number of results to return per page, between 1 and 1000. Default 250.","in":"query","name":"pageSize","required":true,"schema":{"type":"integer","format":"int32","default":250}},{"description":"Page number to return, 0-indexed. Default 0.","in":"query","name":"page","required":true,"schema":{"type":"integer","format":"int32","default":0}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogDefinitionsListResponse"}}},"description":"Successfully found entity types"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List entity types","tags":["Entity Types"]}}}}
```

## GET /api/v1/catalog/definitions/{type}

> Retrieve entity type

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Entity Types"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CatalogDefinitionResponse":{"required":["schema","source","type"],"type":"object","properties":{"description":{"type":"string"},"iconTag":{"type":"string"},"name":{"type":"string"},"schema":{"$ref":"#/components/schemas/JsonNode"},"source":{"type":"string","enum":["CORTEX","CUSTOM"]},"type":{"type":"string"}}},"JsonNode":{"type":"object"},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/definitions/{type}":{"get":{"operationId":"getDefinition","parameters":[{"in":"path","name":"type","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogDefinitionResponse"}}},"description":"Successfully found entity types"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity type not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Retrieve entity type","tags":["Entity Types"]}}}}
```

## POST /api/v1/catalog/definitions

> Create entity type

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Entity Types"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"CreateCatalogDefinitionRequest":{"required":["schema","type"],"type":"object","properties":{"description":{"type":"string"},"iconTag":{"type":"string"},"name":{"type":"string"},"schema":{"$ref":"#/components/schemas/JsonNode"},"type":{"type":"string"}}},"JsonNode":{"type":"object"},"CatalogDefinitionResponse":{"required":["schema","source","type"],"type":"object","properties":{"description":{"type":"string"},"iconTag":{"type":"string"},"name":{"type":"string"},"schema":{"$ref":"#/components/schemas/JsonNode"},"source":{"type":"string","enum":["CORTEX","CUSTOM"]},"type":{"type":"string"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/definitions":{"post":{"operationId":"createDefinition","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCatalogDefinitionRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogDefinitionResponse"}}},"description":"Successfully created entity type"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Failed to create entity type"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Create entity type","tags":["Entity Types"]}}}}
```

## PUT /api/v1/catalog/definitions/{type}

> Update entity type

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Entity Types"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"UpdateCatalogDefinitionRequest":{"required":["schema"],"type":"object","properties":{"description":{"type":"string"},"iconTag":{"type":"string"},"name":{"type":"string"},"schema":{"$ref":"#/components/schemas/JsonNode"}}},"JsonNode":{"type":"object"},"CatalogDefinitionResponse":{"required":["schema","source","type"],"type":"object","properties":{"description":{"type":"string"},"iconTag":{"type":"string"},"name":{"type":"string"},"schema":{"$ref":"#/components/schemas/JsonNode"},"source":{"type":"string","enum":["CORTEX","CUSTOM"]},"type":{"type":"string"}}},"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/definitions/{type}":{"put":{"operationId":"updateDefinition","parameters":[{"in":"path","name":"type","required":true,"schema":{"type":"string"}},{"description":"When true, schema will be updated even if it results in broken schemas for existing entities. Defaults to false.","in":"query","name":"force","required":false,"schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCatalogDefinitionRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogDefinitionResponse"}}},"description":"Successfully updated entity type"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Failed to update entity type"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity type not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Update entity type","tags":["Entity Types"]}}}}
```

## DELETE /api/v1/catalog/definitions/{type}

> Delete entity type

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Entity Types"}],"servers":[{"url":"https://api.getcortexapp.com","description":"Cortex Cloud API host"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT","description":"All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.","scheme":"bearer","type":"http"}},"schemas":{"ErrorResponse":{"required":["message","type"],"type":"object","properties":{"details":{"type":"string"},"gatewayHttpStatus":{"type":"integer","format":"int32"},"httpStatus":{"type":"integer","format":"int32"},"message":{"type":"string"},"requestId":{"type":"string"},"type":{"type":"string","enum":["INTEGRATION_MISSING","INTEGRATION_UNREGISTERED","INTEGRATION_UNSUPPORTED","INTEGRATION_GRAPHQL_ERROR","INTEGRATION_BAD_REQUEST","INTEGRATION_UNAUTHORIZED","INTEGRATION_FORBIDDEN","INTEGRATION_NOT_FOUND","INTEGRATION_UNPROCESSABLE_CONTENT","INTEGRATION_RATE_LIMITED","INTEGRATION_INTERNAL_ERROR","INTEGRATION_NOT_IMPLEMENTED","INTEGRATION_BAD_GATEWAY","INTEGRATION_UNAVAILABLE","INTEGRATION_GATEWAY_TIMEOUT","INTEGRATION_TIMED_OUT","INTEGRATION_CACHE_ERROR","INTEGRATION_UNHANDLED_HTTP_ERROR","INTEGRATION_UNHANDLED_EXCEPTION","INTEGRATION_UNEXPECTED_ERROR","ILLEGAL_ARGUMENT_ERROR","BAD_REQUEST","FORBIDDEN","NOT_FOUND","REQUEST_TIMEOUT","CONFLICT","UNHANDLED_EXCEPTION","UNCATEGORIZED","SERVICE_CREATOR","UNKNOWN_HOST","TOO_MANY_REQUESTS"]}}},"TooManyRequestsProblemDetail":{"required":["type","title","status"],"type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string","format":"uri-reference"},"retryAfter":{"minimum":0,"type":"integer","description":"The number of seconds until the rate limiting resets.","format":"int32"},"status":{"maximum":599,"minimum":100,"type":"integer","format":"int32","enum":[429]},"title":{"type":"string"},"type":{"type":"string","format":"uri-reference"}}}},"responses":{"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/TooManyRequestsProblemDetail"}}},"description":"The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.","headers":{"Retry-After":{"description":"The number of seconds until the rate limiting resets.","schema":{"minimum":0,"type":"integer","format":"int32"}}}}}},"paths":{"/api/v1/catalog/definitions/{type}":{"delete":{"operationId":"deleteDefinition","parameters":[{"in":"path","name":"type","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully deleted entity type"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity type not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete entity type","tags":["Entity Types"]}}}}
```