Catalog Entities
Use these operations to interact with entities in Cortex.
To see additional API operations specific to team entities, see the Teams API page.
Required permissions
Edit entities: Your API key must have the
Edit entitiespermission.Archive entities: Your API key must have the
Archive entitiespermission.Delete entities: Your API key must have
Delete entitiespermission.
Operations
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.
Filter based on groups, which correspond to the x-cortex-groups field in the Catalog Descriptor. Accepts a comma-delimited list of groups
[]Filter based on owner group names, which correspond to the x-cortex-owners field in the Catalog Descriptor. Accepts a comma-delimited list of owner group names
[]Depth of the parent / children hierarchy nodes. Can be 'full' or a valid integer
fullSupports only GitHub repositories in the org/repo format
[]Example: cortexapps%2Fbackend,cortexapps%2FfrontendList of sub fields to include for hierarchies. Only supports 'groups'
groupsFilter 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.
[]Example: service,rds,s3,domainFilter based on a search query. This will search across entity properties. If provided, results will be sorted by relevance.
""Whether to include archived entities in the response
falseWhether to include custom data for each entity in the response
falseWhether to include links for each entity in the response
falseWhether to include Slack channels for each entity in the response
Whether to include ownership information for each entity in the response
falseList of sub fields to include for different types
team:membersNumber of results to return per page, between 1 and 1000. Default 250.
250Page number to return, 0-indexed. Default 0.
0Successfully found entities
Invalid filters
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
GET /api/v1/catalog HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
{
"entities": [
{
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
}
],
"parents": [
{
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2025-09-16T17:40:14.737Z",
"links": [
{
"description": "text",
"name": "text",
"type": "text",
"url": "text"
}
],
"members": [
{
"description": "Product manager",
"email": "[email protected]",
"name": "Aditya Bansal",
"roles": [
{
"name": "Team Leader",
"source": "WORKDAY"
}
],
"sources": [
{
"externalGroupId": "text",
"externalId": "text",
"provider": "ACTIVE_DIRECTORY",
"type": "ENTITY_DEFINED"
}
]
}
],
"metadata": [
{
"key": "text",
"value": {}
}
],
"name": "My Favorite Entity",
"owners": {
"individuals": [
{
"description": "Product manager",
"email": "text"
}
],
"teams": [
{
"description": "This is my team",
"id": "en2da8159dbeefb974",
"inheritance": "APPEND",
"isArchived": true,
"name": "My Favorite Team",
"provider": "ACTIVE_DIRECTORY",
"tag": "my-favorite-team-entity"
}
]
},
"slackChannels": [
{
"description": "This is the engineering channel",
"name": "engineering",
"notificationsEnabled": true
}
],
"tag": "my-favorite-entity",
"type": "service"
}
],
"page": 1,
"total": 1,
"totalPages": 1
}List entity descriptors
The descriptors do not include objects (e.g. custom data, dependencies, etc) defined via the API
When true, returns the YAML representation of the descriptors
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.
service,rds,s3,domainNumber of entities to return per page
Page number to return, 0 indexed
Successfully retrieved entity descriptors
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
GET /api/v1/catalog/descriptors HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
{
"descriptors": [
"text"
],
"page": 1,
"total": 1,
"totalPages": 1
}The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.
Depth of the parent / children hierarchy nodes. Can be 'full' or a valid integer
fullList of sub fields to include for hierarchies. Only supports 'groups'
groupsInclude ownership information, default is true
Successfully found entity
Entity not found
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
GET /api/v1/catalog/{tagOrId} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
{
"definition": {},
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
}
],
"parents": [
{
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2025-09-16T17:40:14.737Z",
"links": [
{
"description": "text",
"name": "text",
"type": "text",
"url": "text"
}
],
"metadata": [
{
"key": "text",
"value": {}
}
],
"name": "My Favorite Entity",
"ownersV2": {
"individuals": [
{
"description": "Product manager",
"email": "text"
}
],
"teams": [
{
"description": "This is my team",
"id": "en2da8159dbeefb974",
"inheritance": "APPEND",
"isArchived": true,
"name": "My Favorite Team",
"provider": "ACTIVE_DIRECTORY",
"tag": "my-favorite-team-entity"
}
]
},
"ownership": {
"emails": [
{
"description": "text",
"email": "text",
"inheritance": "APPEND"
}
],
"groups": [
{
"description": "text",
"groupName": "cortexapps/engineering",
"inheritance": "APPEND",
"provider": "ACTIVE_DIRECTORY"
}
]
},
"slackChannels": [
{
"description": "This is the engineering channel",
"name": "engineering",
"notificationsEnabled": true
}
],
"tag": "my-favorite-entity",
"type": "service"
}The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.
Retrieve most recent GitOps log for entity
Entity GitOps log not found
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
GET /api/v1/catalog/{tagOrId}/gitops-logs HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
[
{
"commit": "text",
"dateCreated": "2025-09-16T17:40:14.737Z",
"fileName": ".cortex/catalog/brain-backend.yaml",
"repository": {
"provider": "GITHUB",
"repositoryName": "cortexapps/catalog"
}
}
]Retrieve entity descriptor
The descriptor does not include objects (e.g. custom data, dependencies, etc) defined via the API
The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.
When true, returns the YAML representation of the descriptor
Successfully found entity descriptor
Entity not found
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
GET /api/v1/catalog/{tagOrId}/openapi HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
textThe tag (x-cortex-tag) or unique, auto-generated identifier for the entity.
All entity Scorecard scores
Entity not found
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
GET /api/v1/catalog/{tagOrId}/scorecards HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
[
{
"ladderLevels": [
{
"level": {
"name": "Bronze",
"number": 1
}
}
],
"score": 1,
"scorePercentage": 1,
"scorecardName": "text",
"totalPossibleScore": 1
}
]Create a catalog entity using a descriptor YAML. If the YAML refers to an entity that already exists (as referenced by the x-cortex-tag), this API will update the existing entity. Note: This overwrites the entity entirely.
When true, this endpoint only validates the descriptor contents and returns any errors or warnings.
Add a comment with validation errors on the pull request with the given ID
Indicates that the entity was accepted and processed successfully
Invalid YAML (major errors or incorrectly formatted YAML)
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
POST /api/v1/open-api HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/openapi;charset=UTF-8
Accept: */*
{
"ok": true,
"violations": [
{
"description": "text",
"endLine": 1,
"paths": [
"text"
],
"pointer": "text",
"ruleLink": "text",
"startLine": 1,
"title": "text",
"violationType": "MUST"
}
]
}The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.
Successfully archived entity
Entity not found
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
PUT /api/v1/catalog/{tagOrId}/archive HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
{
"definition": {},
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
}
],
"parents": [
{
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2025-09-16T17:40:14.737Z",
"links": [
{
"description": "text",
"name": "text",
"type": "text",
"url": "text"
}
],
"metadata": [
{
"key": "text",
"value": {}
}
],
"name": "My Favorite Entity",
"ownersV2": {
"individuals": [
{
"description": "Product manager",
"email": "text"
}
],
"teams": [
{
"description": "This is my team",
"id": "en2da8159dbeefb974",
"inheritance": "APPEND",
"isArchived": true,
"name": "My Favorite Team",
"provider": "ACTIVE_DIRECTORY",
"tag": "my-favorite-team-entity"
}
]
},
"ownership": {
"emails": [
{
"description": "text",
"email": "text",
"inheritance": "APPEND"
}
],
"groups": [
{
"description": "text",
"groupName": "cortexapps/engineering",
"inheritance": "APPEND",
"provider": "ACTIVE_DIRECTORY"
}
]
},
"slackChannels": [
{
"description": "This is the engineering channel",
"name": "engineering",
"notificationsEnabled": true
}
],
"tag": "my-favorite-entity",
"type": "service"
}The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.
Successfully unarchived entity
Entity not found
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
PUT /api/v1/catalog/{tagOrId}/unarchive HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
{
"definition": {},
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
}
],
"parents": [
{
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2025-09-16T17:40:14.737Z",
"links": [
{
"description": "text",
"name": "text",
"type": "text",
"url": "text"
}
],
"metadata": [
{
"key": "text",
"value": {}
}
],
"name": "My Favorite Entity",
"ownersV2": {
"individuals": [
{
"description": "Product manager",
"email": "text"
}
],
"teams": [
{
"description": "This is my team",
"id": "en2da8159dbeefb974",
"inheritance": "APPEND",
"isArchived": true,
"name": "My Favorite Team",
"provider": "ACTIVE_DIRECTORY",
"tag": "my-favorite-team-entity"
}
]
},
"ownership": {
"emails": [
{
"description": "text",
"email": "text",
"inheritance": "APPEND"
}
],
"groups": [
{
"description": "text",
"groupName": "cortexapps/engineering",
"inheritance": "APPEND",
"provider": "ACTIVE_DIRECTORY"
}
]
},
"slackChannels": [
{
"description": "This is the engineering channel",
"name": "engineering",
"notificationsEnabled": true
}
],
"tag": "my-favorite-entity",
"type": "service"
}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.
When true, this endpoint only validates the descriptor contents and returns any errors or warnings.
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.
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.
Default behavior is to upsert the entity, set failIfEntityDoesNotExist=true to fail (404) if the entity specified in x-cortex-tag does not exist.
Indicates that the entity body was accepted, and the referenced x-cortex-tag existed and patched successfully
Indicates that the entity body was accepted, and the referenced x-cortex-tag did not exist and was created successfully
Invalid YAML (major errors or incorrectly formatted YAML)
Specified entity does not exist (when failIfDoesNotExist is set to true)
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
PATCH /api/v1/open-api HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/openapi;charset=UTF-8
Accept: */*
{
"ok": true,
"violations": [
{
"description": "text",
"endLine": 1,
"paths": [
"text"
],
"pointer": "text",
"ruleLink": "text",
"startLine": 1,
"title": "text",
"violationType": "MUST"
}
]
}The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.
Successfully deleted entity
No content
Entity not found
Entity delete is not allowed
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
DELETE /api/v1/catalog/{tagOrId} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
No content
Note: Dangerous operation that will delete all entities that are of the given type
A list of entity types to delete
Successfully deleted entities
No content
Invalid filters
Entity delete is not allowed
The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
DELETE /api/v1/catalog HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*
No content
Last updated
Was this helpful?