> 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/catalog-entities.md).

# Catalog Entities

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

To see additional API operations specific to team entities, see the [Teams API page](/api/readme/teams.md).

### Required permissions

* Edit entities: Your API key must have the `Edit entities` permission.
* Archive entities: Your API key must have the `Archive entities` permission.
* Delete entities: Your API key must have `Delete entities` permission.

## Operations

## List entities

> List all entities across the Service, Resource and Domain Catalogs.\
> \
> This API returns summary data for each entity, so refer to the retrieve entity method to lookup more details for a single entity.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"ListCatalogEntities":{"required":["entities","page","total","totalPages"],"type":"object","properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/EntityDetailsSummary"}},"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"}},"description":"List of all catalog entities, including services, resources, and domains. Use the \\\"type\\\" field to determine what type each entity is."},"EntityDetailsSummary":{"required":["groups","hierarchy","id","isArchived","lastUpdated","links","name","slackChannels","tag","type"],"type":"object","properties":{"description":{"type":"string","description":"Description of the entity visible in the Service, Resource, or Domain Catalog. This may contain markdown."},"git":{"$ref":"#/components/schemas/GitDetails"},"groups":{"type":"array","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor","items":{"type":"string","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor"}},"hierarchy":{"$ref":"#/components/schemas/EntityHierarchyDetails"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the entity."},"isArchived":{"type":"boolean"},"lastUpdated":{"type":"string","description":"Last updated ISO timestamp","format":"date-time"},"links":{"type":"array","description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor","items":{"$ref":"#/components/schemas/Link"}},"members":{"type":"array","items":{"$ref":"#/components/schemas/TeamMember"}},"metadata":{"type":"array","description":"Custom data key/values associated with the entity.","items":{"$ref":"#/components/schemas/Metadata"}},"name":{"type":"string","description":"Human-readable name for the entity"},"owners":{"$ref":"#/components/schemas/OwnersDetails"},"slackChannels":{"type":"array","items":{"$ref":"#/components/schemas/SlackChannelDetails"}},"tag":{"type":"string","description":"Unique identifier for the entity. Corresponds to the x-cortex-tag field in the entity descriptor."},"type":{"type":"string","description":"Type of the entity. Corresponds to the x-cortex-type field in the entity descriptor or 'service' for services."}}},"GitDetails":{"required":["provider","repository","repositoryUrl"],"type":"object","properties":{"alias":{"type":"string","description":"Custom defined alias (this is only relevant if you have opted into multi account support)"},"basepath":{"type":"string","description":"If the entity is in a monorepo (e.g. in a subdirectory), this field defines the subdirectory"},"provider":{"type":"string","description":"Name of the Git provider"},"repository":{"type":"string","description":"Repository name as defined in your Git provider"},"repositoryUrl":{"type":"string","description":"URL of the Git repository"}},"description":"Metadata about the entity's git repository"},"EntityHierarchyDetails":{"required":["children","parents"],"type":"object","properties":{"children":{"uniqueItems":true,"type":"array","description":"Nested children chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyChildNode"}},"parents":{"uniqueItems":true,"type":"array","description":"Nested parent chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyParentNode"}}},"description":"Hierarchy details for the entity. Includes both the parent & the children chains."},"HierarchyChildNode":{"required":["children","id","name","tag","type"],"type":"object","properties":{"children":{"$ref":"#/components/schemas/HierarchyChildNode"},"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Child at the current depth, and its children."},"JsonNode":{"type":"object"},"HierarchyParentNode":{"required":["id","name","parents","tag","type"],"type":"object","properties":{"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"parents":{"$ref":"#/components/schemas/HierarchyParentNode"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Parent at the current depth, and its parents."},"Link":{"required":["name","type","url"],"type":"object","properties":{"description":{"type":"string","description":"An optional description of the link"},"name":{"type":"string","description":"Human-readable name for the link visible in the Catalog"},"type":{"type":"string","description":"Corresponds to the type field in a link definition provided in the Catalog Descriptor"},"url":{"type":"string"}},"description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor"},"TeamMember":{"required":["roles","sources"],"type":"object","properties":{"description":{"type":"string","description":"Description of the team member"},"email":{"type":"string","description":"Email of the team member"},"name":{"type":"string","description":"Name of the team member"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/Role"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/TeamMemberSource"}}},"description":"Team member information"},"Role":{"required":["name"],"type":"object","properties":{"name":{"type":"string","description":"Name of the role"},"source":{"type":"string","description":"Source of the role if pulled in through integration. This will be blank if manually defined in Cortex."}}},"TeamMemberSource":{"required":["type"],"type":"object","properties":{"externalGroupId":{"type":"string"},"externalId":{"type":"string"},"provider":{"type":"string","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]},"type":{"type":"string","enum":["ENTITY_DEFINED","IDP_GROUP"]}}},"Metadata":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string","description":"The custom data key, referred to in CQL as custom(\"key\")"},"value":{"$ref":"#/components/schemas/JsonNode"}},"description":"Custom data key/values associated with the entity."},"OwnersDetails":{"required":["individuals","teams"],"type":"object","properties":{"individuals":{"type":"array","items":{"$ref":"#/components/schemas/IndividualOwnerDetails"}},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamDetails"}}},"description":"Entity owners information"},"IndividualOwnerDetails":{"required":["email"],"type":"object","properties":{"description":{"type":"string","description":"Description of the email owner"},"email":{"type":"string"}}},"TeamDetails":{"required":["id","isArchived","name","tag"],"type":"object","properties":{"description":{"type":"string","description":"Description of the team entity"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the team entity"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"isArchived":{"type":"boolean"},"name":{"type":"string","description":"Human-readable name for the team entity"},"provider":{"type":"string","description":"If defined, indicates the ownership provider the team slug references","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","CORTEX","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]},"tag":{"type":"string","description":"Unique identifier for the team entity. Corresponds to the x-cortex-tag field in the entity descriptor"}}},"SlackChannelDetails":{"required":["name","notificationsEnabled"],"type":"object","properties":{"description":{"type":"string","description":"Description of the Slack channel"},"name":{"type":"string","description":"Name of the Slack channel"},"notificationsEnabled":{"type":"boolean","description":"Whether notifications are enabled for this channel"}},"description":"Slack channel information"},"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":{"get":{"description":"List all entities across the Service, Resource and Domain Catalogs.\n\nThis API returns summary data for each entity, so refer to the retrieve entity method to lookup more details for a single entity.","operationId":"listAllEntities","parameters":[{"description":"Filter based on groups, which correspond to the `x-cortex-groups` field in the Catalog Descriptor. Accepts a comma-delimited list of groups","in":"query","name":"groups","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[]}},{"description":"Filter based on owner group names. Returns entities owned by the specified groups, as well as entities owned by any child/sub-teams of those groups. Group names correspond to the `x-cortex-owners` field in the Catalog Descriptor. Accepts a comma-delimited list of owner group names.","in":"query","name":"owners","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[]}},{"description":"Depth of the parent / children hierarchy nodes. Can be 'full' or a valid integer","in":"query","name":"hierarchyDepth","required":false,"schema":{"type":"string","default":"full"}},{"description":"Filter by git repositories. Supports GitHub (`github:org/repo` or `org/repo`), GitLab (`gitlab:namespace/project`), Bitbucket (`bitbucket:workspace/repo`), and Azure DevOps (`azure-devops:project/repo`). Unprefixed values default to GitHub for backward compatibility.","in":"query","name":"gitRepositories","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[]}},{"description":"List of sub fields to include for hierarchies. Only supports 'groups'","in":"query","name":"includeHierarchyFields","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"description":"Filter the response to specific types of entities. By default, this includes services, resources, and domains. Corresponds to the `x-cortex-type` field in the entity descriptor.","in":"query","name":"types","required":false,"schema":{"type":"array","items":{"type":"string"},"default":[]}},{"description":"Filter based on a [search query](https://docs.cortex.io/settings/search). This will search across entity properties. If provided, results will be sorted by relevance.","in":"query","name":"query","required":false,"schema":{"type":"string","default":""}},{"description":"Whether to include archived entities in the response","in":"query","name":"includeArchived","required":false,"schema":{"type":"boolean","default":false}},{"description":"Whether to include custom data for each entity in the response","in":"query","name":"includeMetadata","required":false,"schema":{"type":"boolean","default":false}},{"description":"Whether to include links for each entity in the response","in":"query","name":"includeLinks","required":false,"schema":{"type":"boolean","default":false}},{"description":"Whether to include Slack channels for each entity in the response","in":"query","name":"includeSlackChannels","required":false,"schema":{"type":"boolean"}},{"description":"Whether to include ownership information for each entity in the response","in":"query","name":"includeOwners","required":false,"schema":{"type":"boolean","default":false}},{"description":"List of sub fields to include for different types","in":"query","name":"includeNestedFields","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"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/ListCatalogEntities"}}},"description":"Successfully found entities"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid filters"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List entities","tags":["Catalog Entities"]}}}}
```

## List entity descriptors

> List entity descriptors\
> \
> The descriptors do not include objects (e.g. custom data, dependencies, etc) defined via the API

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"YamlDescriptorsListResponse":{"required":["descriptors","page","total","totalPages"],"type":"object","properties":{"descriptors":{"type":"array","items":{"type":"string"}},"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"}}},"JsonDescriptorsListResponse":{"required":["descriptors","page","total","totalPages"],"type":"object","properties":{"descriptors":{"type":"array","items":{"$ref":"#/components/schemas/JsonNode"}},"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"}}},"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/descriptors":{"get":{"description":"List entity descriptors\n\nThe descriptors do not include objects (e.g. custom data, dependencies, etc) defined via the API","operationId":"listEntityDescriptors","parameters":[{"description":"When true, returns the YAML representation of the descriptors","in":"query","name":"yaml","schema":{"type":"boolean"}},{"description":"Filter the response to specific types of entities. By default, this includes services, resources, and domains. Corresponds to the `x-cortex-type` field in the entity descriptor.","in":"query","name":"types","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"description":"Number of entities to return per page","in":"query","name":"pageSize","required":true,"schema":{"type":"integer","format":"int32"}},{"description":"Page number to return, 0 indexed","in":"query","name":"page","required":true,"schema":{"type":"integer","format":"int32"}},{"description":"Whether to include archived entities in the response","in":"query","name":"includeArchived","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/YamlDescriptorsListResponse"},{"$ref":"#/components/schemas/JsonDescriptorsListResponse"}]}}},"description":"Successfully retrieved entity descriptors"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"List entity descriptors","tags":["Catalog Entities"]}}}}
```

## GET /api/v1/catalog/{tagOrId}

> Retrieve entity details

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"DetailsResponse":{"required":["groups","hierarchy","id","isArchived","lastUpdated","links","metadata","name","owners","ownership","slackChannels","tag","type"],"type":"object","properties":{"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string","description":"Description of the entity visible in the Service, Resource, or Domain Catalog. Markdown is supported."},"git":{"$ref":"#/components/schemas/GitDetails"},"groups":{"type":"array","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor","items":{"type":"string","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor"}},"hierarchy":{"$ref":"#/components/schemas/EntityHierarchyDetails"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the entity."},"isArchived":{"type":"boolean"},"lastUpdated":{"type":"string","description":"Last updated ISO timestamp","format":"date-time"},"links":{"type":"array","description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor","items":{"$ref":"#/components/schemas/Link"}},"metadata":{"type":"array","description":"Custom data key/values associated with the entity","items":{"$ref":"#/components/schemas/Metadata"}},"name":{"type":"string","description":"Human-readable name for the entity"},"owners":{"$ref":"#/components/schemas/DeprecatedOwners"},"ownersV2":{"$ref":"#/components/schemas/OwnersDetails"},"ownership":{"$ref":"#/components/schemas/Owners"},"slackChannels":{"type":"array","items":{"$ref":"#/components/schemas/SlackChannelDetails"}},"tag":{"type":"string","description":"Unique identifier for the entity. Corresponds to the x-cortex-tag field in the entity descriptor."},"type":{"type":"string","description":"Type of the entity. Corresponds to the x-cortex-type field in the entity descriptor or 'service' for services."}}},"JsonNode":{"type":"object"},"GitDetails":{"required":["provider","repository","repositoryUrl"],"type":"object","properties":{"alias":{"type":"string","description":"Custom defined alias (this is only relevant if you have opted into multi account support)"},"basepath":{"type":"string","description":"If the entity is in a monorepo (e.g. in a subdirectory), this field defines the subdirectory"},"provider":{"type":"string","description":"Name of the Git provider"},"repository":{"type":"string","description":"Repository name as defined in your Git provider"},"repositoryUrl":{"type":"string","description":"URL of the Git repository"}},"description":"Metadata about the entity's git repository"},"EntityHierarchyDetails":{"required":["children","parents"],"type":"object","properties":{"children":{"uniqueItems":true,"type":"array","description":"Nested children chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyChildNode"}},"parents":{"uniqueItems":true,"type":"array","description":"Nested parent chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyParentNode"}}},"description":"Hierarchy details for the entity. Includes both the parent & the children chains."},"HierarchyChildNode":{"required":["children","id","name","tag","type"],"type":"object","properties":{"children":{"$ref":"#/components/schemas/HierarchyChildNode"},"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Child at the current depth, and its children."},"HierarchyParentNode":{"required":["id","name","parents","tag","type"],"type":"object","properties":{"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"parents":{"$ref":"#/components/schemas/HierarchyParentNode"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Parent at the current depth, and its parents."},"Link":{"required":["name","type","url"],"type":"object","properties":{"description":{"type":"string","description":"An optional description of the link"},"name":{"type":"string","description":"Human-readable name for the link visible in the Catalog"},"type":{"type":"string","description":"Corresponds to the type field in a link definition provided in the Catalog Descriptor"},"url":{"type":"string"}},"description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor"},"Metadata":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string","description":"The custom data key, referred to in CQL as custom(\"key\")"},"value":{"$ref":"#/components/schemas/JsonNode"}},"description":"Custom data key/values associated with the entity."},"DeprecatedOwners":{"required":["emails","groups","slackChannels"],"type":"object","properties":{"emails":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"slackChannels":{"type":"array","items":{"type":"string"}}},"description":"Deprecated. Use `ownership` (same semantics) or `ownersV2` (newer, richer shape). Retained in the response for backwards compatibility with older integrations and may be removed in a future release.","deprecated":true},"OwnersDetails":{"required":["individuals","teams"],"type":"object","properties":{"individuals":{"type":"array","items":{"$ref":"#/components/schemas/IndividualOwnerDetails"}},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamDetails"}}},"description":"Entity owners information"},"IndividualOwnerDetails":{"required":["email"],"type":"object","properties":{"description":{"type":"string","description":"Description of the email owner"},"email":{"type":"string"}}},"TeamDetails":{"required":["id","isArchived","name","tag"],"type":"object","properties":{"description":{"type":"string","description":"Description of the team entity"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the team entity"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"isArchived":{"type":"boolean"},"name":{"type":"string","description":"Human-readable name for the team entity"},"provider":{"type":"string","description":"If defined, indicates the ownership provider the team slug references","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","CORTEX","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]},"tag":{"type":"string","description":"Unique identifier for the team entity. Corresponds to the x-cortex-tag field in the entity descriptor"}}},"Owners":{"required":["emails","groups","slackChannels"],"type":"object","properties":{"emails":{"type":"array","items":{"$ref":"#/components/schemas/Email"}},"groups":{"type":"array","description":"List of IdP or Cortex Teams (not to be confused with the x-cortex-groups).","items":{"$ref":"#/components/schemas/OwnerGroup"}},"slackChannels":{"type":"array","description":"Use the top-level `slackChannels` field instead of the one nested inside `ownership`","deprecated":true,"items":{"$ref":"#/components/schemas/SlackChannel"}}}},"Email":{"required":["email"],"type":"object","properties":{"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor, not to be confused with the description of the team in the Team pages"},"email":{"type":"string"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]}}},"OwnerGroup":{"required":["groupName"],"type":"object","properties":{"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor. Not to be confused with the description of the team in the Team pages."},"groupName":{"type":"string","description":"The slug for the group as defined in the ownership provider. For example, the org/team for GitHub teams or the team tag for Cortex Teams"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"provider":{"type":"string","description":"If defined, indicates the ownership provider the team slug references","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","CORTEX","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]}},"description":"List of IdP or Cortex Teams (not to be confused with the x-cortex-groups)."},"SlackChannel":{"required":["channel"],"type":"object","properties":{"channel":{"type":"string","description":"The Slack channel identifier without the preceding #"},"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor. Not to be confused with the description of the team in the Team pages."},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"notificationsEnabled":{"type":"boolean","description":"Refers to the corresponding field in the Catalog Descriptor. This is meant to be used for your automation purposes and does not actually impact the notification behavior in Cortex."}},"description":"Use the top-level `slackChannels` field instead of the one nested inside `ownership`","deprecated":true},"SlackChannelDetails":{"required":["name","notificationsEnabled"],"type":"object","properties":{"description":{"type":"string","description":"Description of the Slack channel"},"name":{"type":"string","description":"Name of the Slack channel"},"notificationsEnabled":{"type":"boolean","description":"Whether notifications are enabled for this channel"}},"description":"Slack channel information"},"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/{tagOrId}":{"get":{"operationId":"getEntityDetails","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}},{"description":"Depth of the parent / children hierarchy nodes. Can be 'full' or a valid integer","in":"query","name":"hierarchyDepth","required":false,"schema":{"type":"string","default":"full"}},{"description":"List of sub fields to include for hierarchies. Only supports 'groups'","in":"query","name":"includeHierarchyFields","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"description":"Include ownership information, default is true","in":"query","name":"includeOwners","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailsResponse"}}},"description":"Successfully found entity"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Retrieve entity details","tags":["Catalog Entities"]}}}}
```

## GET /api/v1/catalog/{tagOrId}/gitops-logs

> Retrieve most recent GitOps log for entity

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"GitOpsLogEntityResponse":{"required":["commit","dateCreated","fileName","repository"],"type":"object","properties":{"commit":{"type":"string"},"dateCreated":{"type":"string","description":"Date when the GitOps log was created","format":"date-time"},"fileName":{"type":"string","description":"Relative path of the cortex.yaml file"},"repository":{"$ref":"#/components/schemas/GitOpsLogRepositoryResponse"}}},"GitOpsLogRepositoryResponse":{"required":["provider","repositoryName"],"type":"object","properties":{"provider":{"type":"string","description":"Git provider (GitHub, GitLab, etc.)","enum":["AZURE_DEVOPS","BITBUCKET","GITHUB","GITLAB"]},"repositoryName":{"type":"string","description":"Repository name as defined in your Git provider"}}},"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/{tagOrId}/gitops-logs":{"get":{"operationId":"latestGitOpsLogForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GitOpsLogEntityResponse"}}}},"description":"Retrieve most recent GitOps log for entity"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity GitOps log not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Retrieve most recent GitOps log for entity","tags":["Catalog Entities"]}}}}
```

## Retrieve entity descriptor

> Retrieve entity descriptor\
> \
> The descriptor does not include objects (e.g. custom data, dependencies, etc) defined via the API

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"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/{tagOrId}/openapi":{"get":{"description":"Retrieve entity descriptor\n\nThe descriptor does not include objects (e.g. custom data, dependencies, etc) defined via the API","operationId":"getEntityDescriptor","parameters":[{"description":"When true, returns the YAML representation of the descriptor","in":"query","name":"yaml","schema":{"type":"boolean"}},{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"responses":{"200":{"content":{"application/json":{"schema":{"oneOf":[{"type":"string"},{"$ref":"#/components/schemas/JsonNode"}]}}},"description":"Successfully found entity descriptor"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Retrieve entity descriptor","tags":["Catalog Entities"]}}}}
```

## GET /api/v1/catalog/{tagOrId}/scorecards

> Retrieve entity Scorecard scores

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"ScorecardScore":{"required":["ladderLevels","score","scorePercentage","scorecardId","scorecardName","totalPossibleScore"],"type":"object","properties":{"ladderLevels":{"type":"array","items":{"$ref":"#/components/schemas/LadderLevel"}},"score":{"type":"number"},"scorePercentage":{"type":"number"},"scorecardId":{"type":"integer","format":"int64"},"scorecardName":{"type":"string"},"totalPossibleScore":{"type":"number"}}},"LadderLevel":{"type":"object","properties":{"level":{"$ref":"#/components/schemas/CurrentLevel"}}},"CurrentLevel":{"required":["name","number"],"type":"object","properties":{"name":{"type":"string","description":"Name of the level"},"number":{"type":"integer","description":"Rank of the level where 1 is the highest","format":"int32"}}},"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/{tagOrId}/scorecards":{"get":{"operationId":"listScorecardScoresForEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ScorecardScore"}}}},"description":"All entity Scorecard scores"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Retrieve entity Scorecard scores","tags":["Catalog Entities"]}}}}
```

## Create or update entity

> Create a catalog entity using a descriptor YAML. By default (UPSERT mode), if the entity already exists (as referenced by the \`x-cortex-tag\`), this API will update the existing entity. In CREATE mode, the API will fail if the entity already exists.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"OpenApiResponse":{"required":["ok","violations"],"type":"object","properties":{"ok":{"type":"boolean"},"violations":{"type":"array","items":{"$ref":"#/components/schemas/ViolationDTO"}}}},"ViolationDTO":{"required":["paths"],"type":"object","properties":{"description":{"type":"string"},"endLine":{"type":"integer","format":"int32"},"paths":{"type":"array","items":{"type":"string"}},"pointer":{"type":"string"},"ruleLink":{"type":"string"},"startLine":{"type":"integer","format":"int32"},"title":{"type":"string"},"violationType":{"type":"string","enum":["MUST","SHOULD","MAY","HINT"]}}},"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/open-api":{"post":{"description":"Create a catalog entity using a descriptor YAML. By default (UPSERT mode), if the entity already exists (as referenced by the `x-cortex-tag`), this API will update the existing entity. In CREATE mode, the API will fail if the entity already exists.","operationId":"createOrUpdateEntity","parameters":[{"description":"When true, this endpoint only validates the descriptor contents and returns any errors or warnings.","in":"query","name":"dryRun","required":false,"schema":{"type":"boolean"}},{"description":"Add a comment with validation errors on the pull request with the given ID","in":"query","name":"githubPullRequest","required":false,"schema":{"type":"integer","format":"int32"}},{"description":"Mode of operation: UPSERT (default) creates or updates existing entity, CREATE fails if entity already exists.","in":"query","name":"mode","required":false,"schema":{"type":"string","enum":["UPSERT","CREATE"]}},{"description":"Maximum time (milliseconds) to wait for asynchronous property updates. Default is zero.","in":"query","name":"asyncUpdateWaitTimeMs","required":false,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/openapi;charset=UTF-8":{"schema":{"type":"string"}}},"description":"Raw text of the YAML  \n See examples of cortex.yaml files for each entity type [here](https://docs.cortex.io/docs/reference/basics/entities#example-cortexyaml-for-service-entity)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiResponse"}}},"description":"Indicates that the entity was accepted and processed successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiResponse"}}},"description":"Invalid YAML (major errors or incorrectly formatted YAML)"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Create or update entity","tags":["Catalog Entities"]}}}}
```

## PUT /api/v1/catalog/{tagOrId}/archive

> Archive an entity

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"DetailsResponse":{"required":["groups","hierarchy","id","isArchived","lastUpdated","links","metadata","name","owners","ownership","slackChannels","tag","type"],"type":"object","properties":{"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string","description":"Description of the entity visible in the Service, Resource, or Domain Catalog. Markdown is supported."},"git":{"$ref":"#/components/schemas/GitDetails"},"groups":{"type":"array","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor","items":{"type":"string","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor"}},"hierarchy":{"$ref":"#/components/schemas/EntityHierarchyDetails"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the entity."},"isArchived":{"type":"boolean"},"lastUpdated":{"type":"string","description":"Last updated ISO timestamp","format":"date-time"},"links":{"type":"array","description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor","items":{"$ref":"#/components/schemas/Link"}},"metadata":{"type":"array","description":"Custom data key/values associated with the entity","items":{"$ref":"#/components/schemas/Metadata"}},"name":{"type":"string","description":"Human-readable name for the entity"},"owners":{"$ref":"#/components/schemas/DeprecatedOwners"},"ownersV2":{"$ref":"#/components/schemas/OwnersDetails"},"ownership":{"$ref":"#/components/schemas/Owners"},"slackChannels":{"type":"array","items":{"$ref":"#/components/schemas/SlackChannelDetails"}},"tag":{"type":"string","description":"Unique identifier for the entity. Corresponds to the x-cortex-tag field in the entity descriptor."},"type":{"type":"string","description":"Type of the entity. Corresponds to the x-cortex-type field in the entity descriptor or 'service' for services."}}},"JsonNode":{"type":"object"},"GitDetails":{"required":["provider","repository","repositoryUrl"],"type":"object","properties":{"alias":{"type":"string","description":"Custom defined alias (this is only relevant if you have opted into multi account support)"},"basepath":{"type":"string","description":"If the entity is in a monorepo (e.g. in a subdirectory), this field defines the subdirectory"},"provider":{"type":"string","description":"Name of the Git provider"},"repository":{"type":"string","description":"Repository name as defined in your Git provider"},"repositoryUrl":{"type":"string","description":"URL of the Git repository"}},"description":"Metadata about the entity's git repository"},"EntityHierarchyDetails":{"required":["children","parents"],"type":"object","properties":{"children":{"uniqueItems":true,"type":"array","description":"Nested children chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyChildNode"}},"parents":{"uniqueItems":true,"type":"array","description":"Nested parent chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyParentNode"}}},"description":"Hierarchy details for the entity. Includes both the parent & the children chains."},"HierarchyChildNode":{"required":["children","id","name","tag","type"],"type":"object","properties":{"children":{"$ref":"#/components/schemas/HierarchyChildNode"},"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Child at the current depth, and its children."},"HierarchyParentNode":{"required":["id","name","parents","tag","type"],"type":"object","properties":{"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"parents":{"$ref":"#/components/schemas/HierarchyParentNode"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Parent at the current depth, and its parents."},"Link":{"required":["name","type","url"],"type":"object","properties":{"description":{"type":"string","description":"An optional description of the link"},"name":{"type":"string","description":"Human-readable name for the link visible in the Catalog"},"type":{"type":"string","description":"Corresponds to the type field in a link definition provided in the Catalog Descriptor"},"url":{"type":"string"}},"description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor"},"Metadata":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string","description":"The custom data key, referred to in CQL as custom(\"key\")"},"value":{"$ref":"#/components/schemas/JsonNode"}},"description":"Custom data key/values associated with the entity."},"DeprecatedOwners":{"required":["emails","groups","slackChannels"],"type":"object","properties":{"emails":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"slackChannels":{"type":"array","items":{"type":"string"}}},"description":"Deprecated. Use `ownership` (same semantics) or `ownersV2` (newer, richer shape). Retained in the response for backwards compatibility with older integrations and may be removed in a future release.","deprecated":true},"OwnersDetails":{"required":["individuals","teams"],"type":"object","properties":{"individuals":{"type":"array","items":{"$ref":"#/components/schemas/IndividualOwnerDetails"}},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamDetails"}}},"description":"Entity owners information"},"IndividualOwnerDetails":{"required":["email"],"type":"object","properties":{"description":{"type":"string","description":"Description of the email owner"},"email":{"type":"string"}}},"TeamDetails":{"required":["id","isArchived","name","tag"],"type":"object","properties":{"description":{"type":"string","description":"Description of the team entity"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the team entity"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"isArchived":{"type":"boolean"},"name":{"type":"string","description":"Human-readable name for the team entity"},"provider":{"type":"string","description":"If defined, indicates the ownership provider the team slug references","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","CORTEX","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]},"tag":{"type":"string","description":"Unique identifier for the team entity. Corresponds to the x-cortex-tag field in the entity descriptor"}}},"Owners":{"required":["emails","groups","slackChannels"],"type":"object","properties":{"emails":{"type":"array","items":{"$ref":"#/components/schemas/Email"}},"groups":{"type":"array","description":"List of IdP or Cortex Teams (not to be confused with the x-cortex-groups).","items":{"$ref":"#/components/schemas/OwnerGroup"}},"slackChannels":{"type":"array","description":"Use the top-level `slackChannels` field instead of the one nested inside `ownership`","deprecated":true,"items":{"$ref":"#/components/schemas/SlackChannel"}}}},"Email":{"required":["email"],"type":"object","properties":{"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor, not to be confused with the description of the team in the Team pages"},"email":{"type":"string"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]}}},"OwnerGroup":{"required":["groupName"],"type":"object","properties":{"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor. Not to be confused with the description of the team in the Team pages."},"groupName":{"type":"string","description":"The slug for the group as defined in the ownership provider. For example, the org/team for GitHub teams or the team tag for Cortex Teams"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"provider":{"type":"string","description":"If defined, indicates the ownership provider the team slug references","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","CORTEX","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]}},"description":"List of IdP or Cortex Teams (not to be confused with the x-cortex-groups)."},"SlackChannel":{"required":["channel"],"type":"object","properties":{"channel":{"type":"string","description":"The Slack channel identifier without the preceding #"},"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor. Not to be confused with the description of the team in the Team pages."},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"notificationsEnabled":{"type":"boolean","description":"Refers to the corresponding field in the Catalog Descriptor. This is meant to be used for your automation purposes and does not actually impact the notification behavior in Cortex."}},"description":"Use the top-level `slackChannels` field instead of the one nested inside `ownership`","deprecated":true},"SlackChannelDetails":{"required":["name","notificationsEnabled"],"type":"object","properties":{"description":{"type":"string","description":"Description of the Slack channel"},"name":{"type":"string","description":"Name of the Slack channel"},"notificationsEnabled":{"type":"boolean","description":"Whether notifications are enabled for this channel"}},"description":"Slack channel information"},"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/{tagOrId}/archive":{"put":{"operationId":"archiveEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailsResponse"}}},"description":"Successfully archived entity"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Archive an entity","tags":["Catalog Entities"]}}}}
```

## PUT /api/v1/catalog/{tagOrId}/unarchive

> Unarchive an entity

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"DetailsResponse":{"required":["groups","hierarchy","id","isArchived","lastUpdated","links","metadata","name","owners","ownership","slackChannels","tag","type"],"type":"object","properties":{"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string","description":"Description of the entity visible in the Service, Resource, or Domain Catalog. Markdown is supported."},"git":{"$ref":"#/components/schemas/GitDetails"},"groups":{"type":"array","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor","items":{"type":"string","description":"Corresponds to the x-cortex-groups field in the Catalog Descriptor"}},"hierarchy":{"$ref":"#/components/schemas/EntityHierarchyDetails"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the entity."},"isArchived":{"type":"boolean"},"lastUpdated":{"type":"string","description":"Last updated ISO timestamp","format":"date-time"},"links":{"type":"array","description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor","items":{"$ref":"#/components/schemas/Link"}},"metadata":{"type":"array","description":"Custom data key/values associated with the entity","items":{"$ref":"#/components/schemas/Metadata"}},"name":{"type":"string","description":"Human-readable name for the entity"},"owners":{"$ref":"#/components/schemas/DeprecatedOwners"},"ownersV2":{"$ref":"#/components/schemas/OwnersDetails"},"ownership":{"$ref":"#/components/schemas/Owners"},"slackChannels":{"type":"array","items":{"$ref":"#/components/schemas/SlackChannelDetails"}},"tag":{"type":"string","description":"Unique identifier for the entity. Corresponds to the x-cortex-tag field in the entity descriptor."},"type":{"type":"string","description":"Type of the entity. Corresponds to the x-cortex-type field in the entity descriptor or 'service' for services."}}},"JsonNode":{"type":"object"},"GitDetails":{"required":["provider","repository","repositoryUrl"],"type":"object","properties":{"alias":{"type":"string","description":"Custom defined alias (this is only relevant if you have opted into multi account support)"},"basepath":{"type":"string","description":"If the entity is in a monorepo (e.g. in a subdirectory), this field defines the subdirectory"},"provider":{"type":"string","description":"Name of the Git provider"},"repository":{"type":"string","description":"Repository name as defined in your Git provider"},"repositoryUrl":{"type":"string","description":"URL of the Git repository"}},"description":"Metadata about the entity's git repository"},"EntityHierarchyDetails":{"required":["children","parents"],"type":"object","properties":{"children":{"uniqueItems":true,"type":"array","description":"Nested children chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyChildNode"}},"parents":{"uniqueItems":true,"type":"array","description":"Nested parent chain for the specific entity.","items":{"$ref":"#/components/schemas/HierarchyParentNode"}}},"description":"Hierarchy details for the entity. Includes both the parent & the children chains."},"HierarchyChildNode":{"required":["children","id","name","tag","type"],"type":"object","properties":{"children":{"$ref":"#/components/schemas/HierarchyChildNode"},"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Child at the current depth, and its children."},"HierarchyParentNode":{"required":["id","name","parents","tag","type"],"type":"object","properties":{"definition":{"$ref":"#/components/schemas/JsonNode"},"description":{"type":"string"},"groups":{"type":"array","description":"List of groups for this node. Only included if includeHierarchyFields contains groups","items":{"type":"string","description":"List of groups for this node. Only included if includeHierarchyFields contains groups"}},"id":{"type":"string"},"name":{"type":"string"},"parents":{"$ref":"#/components/schemas/HierarchyParentNode"},"tag":{"type":"string"},"type":{"type":"string"}},"description":"Parent at the current depth, and its parents."},"Link":{"required":["name","type","url"],"type":"object","properties":{"description":{"type":"string","description":"An optional description of the link"},"name":{"type":"string","description":"Human-readable name for the link visible in the Catalog"},"type":{"type":"string","description":"Corresponds to the type field in a link definition provided in the Catalog Descriptor"},"url":{"type":"string"}},"description":"Relevant links for the entity. Corresponds to the x-cortex-links field in the entity descriptor"},"Metadata":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string","description":"The custom data key, referred to in CQL as custom(\"key\")"},"value":{"$ref":"#/components/schemas/JsonNode"}},"description":"Custom data key/values associated with the entity."},"DeprecatedOwners":{"required":["emails","groups","slackChannels"],"type":"object","properties":{"emails":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"}},"slackChannels":{"type":"array","items":{"type":"string"}}},"description":"Deprecated. Use `ownership` (same semantics) or `ownersV2` (newer, richer shape). Retained in the response for backwards compatibility with older integrations and may be removed in a future release.","deprecated":true},"OwnersDetails":{"required":["individuals","teams"],"type":"object","properties":{"individuals":{"type":"array","items":{"$ref":"#/components/schemas/IndividualOwnerDetails"}},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamDetails"}}},"description":"Entity owners information"},"IndividualOwnerDetails":{"required":["email"],"type":"object","properties":{"description":{"type":"string","description":"Description of the email owner"},"email":{"type":"string"}}},"TeamDetails":{"required":["id","isArchived","name","tag"],"type":"object","properties":{"description":{"type":"string","description":"Description of the team entity"},"id":{"type":"string","description":"Unique, immutable, 18-character auto-generated identifier for the team entity"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"isArchived":{"type":"boolean"},"name":{"type":"string","description":"Human-readable name for the team entity"},"provider":{"type":"string","description":"If defined, indicates the ownership provider the team slug references","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","CORTEX","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]},"tag":{"type":"string","description":"Unique identifier for the team entity. Corresponds to the x-cortex-tag field in the entity descriptor"}}},"Owners":{"required":["emails","groups","slackChannels"],"type":"object","properties":{"emails":{"type":"array","items":{"$ref":"#/components/schemas/Email"}},"groups":{"type":"array","description":"List of IdP or Cortex Teams (not to be confused with the x-cortex-groups).","items":{"$ref":"#/components/schemas/OwnerGroup"}},"slackChannels":{"type":"array","description":"Use the top-level `slackChannels` field instead of the one nested inside `ownership`","deprecated":true,"items":{"$ref":"#/components/schemas/SlackChannel"}}}},"Email":{"required":["email"],"type":"object","properties":{"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor, not to be confused with the description of the team in the Team pages"},"email":{"type":"string"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]}}},"OwnerGroup":{"required":["groupName"],"type":"object","properties":{"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor. Not to be confused with the description of the team in the Team pages."},"groupName":{"type":"string","description":"The slug for the group as defined in the ownership provider. For example, the org/team for GitHub teams or the team tag for Cortex Teams"},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"provider":{"type":"string","description":"If defined, indicates the ownership provider the team slug references","enum":["ACTIVE_DIRECTORY","BAMBOO_HR","CORTEX","GITHUB","GITLAB","GOOGLE","OKTA","OPSGENIE","WORKDAY","SERVICE_NOW"]}},"description":"List of IdP or Cortex Teams (not to be confused with the x-cortex-groups)."},"SlackChannel":{"required":["channel"],"type":"object","properties":{"channel":{"type":"string","description":"The Slack channel identifier without the preceding #"},"description":{"type":"string","description":"Description of this owner defined in the Catalog Descriptor. Not to be confused with the description of the team in the Team pages."},"inheritance":{"type":"string","description":"Inheritance type, only defined for domain entities","enum":["APPEND","FALLBACK","NONE"]},"notificationsEnabled":{"type":"boolean","description":"Refers to the corresponding field in the Catalog Descriptor. This is meant to be used for your automation purposes and does not actually impact the notification behavior in Cortex."}},"description":"Use the top-level `slackChannels` field instead of the one nested inside `ownership`","deprecated":true},"SlackChannelDetails":{"required":["name","notificationsEnabled"],"type":"object","properties":{"description":{"type":"string","description":"Description of the Slack channel"},"name":{"type":"string","description":"Name of the Slack channel"},"notificationsEnabled":{"type":"boolean","description":"Whether notifications are enabled for this channel"}},"description":"Slack channel information"},"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/{tagOrId}/unarchive":{"put":{"operationId":"unarchiveEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetailsResponse"}}},"description":"Successfully unarchived entity"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Unarchive an entity","tags":["Catalog Entities"]}}}}
```

## Create or patch entity

> Creates or updates an entity using OpenAPI. If the YAML refers to an entity that already exists (as referenced by the \`x-cortex-tag\`), this API will merge the specified changes into the existing entity.

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"OpenApiResponse":{"required":["ok","violations"],"type":"object","properties":{"ok":{"type":"boolean"},"violations":{"type":"array","items":{"$ref":"#/components/schemas/ViolationDTO"}}}},"ViolationDTO":{"required":["paths"],"type":"object","properties":{"description":{"type":"string"},"endLine":{"type":"integer","format":"int32"},"paths":{"type":"array","items":{"type":"string"}},"pointer":{"type":"string"},"ruleLink":{"type":"string"},"startLine":{"type":"integer","format":"int32"},"title":{"type":"string"},"violationType":{"type":"string","enum":["MUST","SHOULD","MAY","HINT"]}}},"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/open-api":{"patch":{"description":"Creates or updates an entity using OpenAPI. If the YAML refers to an entity that already exists (as referenced by the `x-cortex-tag`), this API will merge the specified changes into the existing entity.","operationId":"createOrPatchEntity","parameters":[{"description":"When true, this endpoint only validates the descriptor contents and returns any errors or warnings.","in":"query","name":"dryRun","required":false,"schema":{"type":"boolean"}},{"description":"Delete keys with this value from the merged yaml, e.g. `__delete__`, if any values match this, they will not be included in merged YAML. For example `my_value: __delete__` will remove `my_value` from the merged YAML.","in":"query","name":"deleteMarkerValue","required":false,"schema":{"type":"string"}},{"description":"Default merge behavior is to replace arrays, set this to true to append arrays instead. For simple types, duplicate values will be removed from the merged array.","in":"query","name":"appendArrays","required":false,"schema":{"type":"boolean"}},{"description":"Default behavior is to upsert the entity, set `failIfEntityDoesNotExist=true` to fail (404) if the entity specified in `x-cortex-tag` does not exist.","in":"query","name":"failIfEntityDoesNotExist","required":false,"schema":{"type":"boolean"}},{"description":"Maximum time (milliseconds) to wait for asynchronous property updates. Default is zero.","in":"query","name":"asyncUpdateWaitTimeMs","required":false,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"content":{"application/openapi;charset=UTF-8":{"schema":{"type":"string"}}},"description":"Raw text of the YAML  \n See examples of cortex.yaml files for each entity type [here](https://docs.cortex.io/docs/reference/basics/entities#example-cortexyaml-for-service-entity)"},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiResponse"}}},"description":"Indicates that the entity body was accepted, and the referenced `x-cortex-tag` existed and patched successfully"},"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiResponse"}}},"description":"Indicates that the entity body was accepted, and the referenced `x-cortex-tag` did not exist and was created successfully"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiResponse"}}},"description":"Invalid YAML (major errors or incorrectly formatted YAML)"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenApiResponse"}}},"description":"Specified entity does not exist (when failIfDoesNotExist is set to true)"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Create or patch entity","tags":["Catalog Entities"]}}}}
```

## DELETE /api/v1/catalog/{tagOrId}

> Delete entity

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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/{tagOrId}":{"delete":{"operationId":"deleteEntity","parameters":[{"description":"The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.","in":"path","name":"tagOrId","required":true,"schema":{"type":"string","description":"Entity identifier - can be a tag or CID"}}],"responses":{"200":{"description":"Successfully deleted entity"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Entity not found"},"405":{"description":"Entity delete is not allowed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete entity","tags":["Catalog Entities"]}}}}
```

## Delete entities by type

> Note: Dangerous operation that will delete all entities that are of the given type

```json
{"openapi":"3.0.1","info":{"title":"Cortex API","version":"v1"},"tags":[{"name":"Catalog Entities"}],"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":{"delete":{"description":"Note: Dangerous operation that will delete all entities that are of the given type","operationId":"deleteEntitiesByType","parameters":[{"description":"A list of entity types or IDs delete","in":"query","name":"types","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"in":"query","name":"ids","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Successfully deleted entities"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Invalid filters"},"405":{"description":"Entity delete is not allowed"},"429":{"$ref":"#/components/responses/TooManyRequests"}},"summary":"Delete entities by type","tags":["Catalog Entities"]}}}}
```