Catalog Entities
Required permissions
Operations
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.
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. 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.
[]Depth of the parent / children hierarchy nodes. Can be 'full' or a valid integer
fullFilter 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.
[]Example: cortexapps%2Fbackend,gitlab:my-group%2Fmy-projectList 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
List of all catalog entities, including services, resources, and domains. Use the "type" field to determine what type each entity is.
Current page number, 0-indexed
Total number of results
Total number of pages
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?pageSize=250&page=0 HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"entities": [
{
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": "[Circular Reference]",
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"tag": "text",
"type": "text"
}
],
"parents": [
{
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": "[Circular Reference]",
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2026-01-01T00:00:00.000Z",
"links": [
{
"description": "text",
"name": "text",
"type": "text",
"url": "text"
}
],
"members": [
{
"description": "Product manager",
"email": "aditya.bansal@cortex.io",
"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
}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.
Relevance search text. Plain words work; AND/OR/NOT supported.
Restrict to entity types, e.g. service, domain, team, resource.
Owner team tags. Returns entities owned by these teams, including their sub-teams.
Domain tags. Returns entities in these domains, including their sub-domains.
Catalog slug. Scopes the search to that catalog's entities.
0-indexed page number.
0Results per page, 1-100.
25falseOK
Relevance-ranked catalog search results.
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/search HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"pagination": {
"hasMore": true,
"page": 1,
"pageSize": 1,
"total": 1,
"totalPages": 1
},
"results": [
{
"cid": "en2da8159dbeefb974",
"description": "text",
"groups": [
"text"
],
"name": "text",
"ownerEmails": [
"text"
],
"owningTeamTags": [
"text"
],
"status": "ACTIVE",
"tag": "payments-api",
"type": "service"
}
]
}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.
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
Whether to include archived entities in the response
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?pageSize=1&page=1 HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"descriptors": [
"text"
],
"page": 1,
"total": 1,
"totalPages": 1
}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.
Entity identifier - can be a tag or CID
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
Description of the entity visible in the Service, Resource, or Domain Catalog. Markdown is supported.
Corresponds to the x-cortex-groups field in the Catalog Descriptor
Unique, immutable, 18-character auto-generated identifier for the entity.
en2da8159dbeefb974Last updated ISO timestamp
Human-readable name for the entity
My Favorite EntityUnique identifier for the entity. Corresponds to the x-cortex-tag field in the entity descriptor.
my-favorite-entityType of the entity. Corresponds to the x-cortex-type field in the entity descriptor or 'service' for services.
serviceEntity 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 YOUR_SECRET_TOKEN
Accept: */*
{
"definition": {},
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": {
"children": {
"children": "[Circular Reference]",
"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"
},
"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",
"parents": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": "[Circular Reference]",
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2026-01-01T00:00:00.000Z",
"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"
}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.
Entity identifier - can be a tag or CID
Retrieve most recent GitOps log for entity
Date when the GitOps log was created
Relative path of the cortex.yaml file
.cortex/catalog/brain-backend.yamlEntity 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 YOUR_SECRET_TOKEN
Accept: */*
[
{
"commit": "text",
"dateCreated": "2026-01-01T00:00:00.000Z",
"fileName": ".cortex/catalog/brain-backend.yaml",
"repository": {
"provider": "AZURE_DEVOPS",
"repositoryName": "cortexapps/catalog"
}
}
]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.
Entity identifier - can be a tag or CID
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 YOUR_SECRET_TOKEN
Accept: */*
textAll 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.
Entity identifier - can be a tag or CID
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 YOUR_SECRET_TOKEN
Accept: */*
[
{
"ladderLevels": [
{
"level": {
"name": "Bronze",
"number": 1
}
}
],
"score": 1,
"scorePercentage": 1,
"scorecardId": 1,
"scorecardName": "text",
"totalPossibleScore": 1
}
]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.
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
Mode of operation: UPSERT (default) creates or updates existing entity, CREATE fails if entity already exists.
Maximum time (milliseconds) to wait for asynchronous property updates. Default is zero.
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 YOUR_SECRET_TOKEN
Content-Type: application/openapi;charset=UTF-8
Accept: */*
Content-Length: 6
"text"{
"ok": true,
"violations": [
{
"description": "text",
"endLine": 1,
"paths": [
"text"
],
"pointer": "text",
"ruleLink": "text",
"startLine": 1,
"title": "text",
"violationType": "MUST"
}
]
}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.
Entity identifier - can be a tag or CID
Successfully archived entity
Description of the entity visible in the Service, Resource, or Domain Catalog. Markdown is supported.
Corresponds to the x-cortex-groups field in the Catalog Descriptor
Unique, immutable, 18-character auto-generated identifier for the entity.
en2da8159dbeefb974Last updated ISO timestamp
Human-readable name for the entity
My Favorite EntityUnique identifier for the entity. Corresponds to the x-cortex-tag field in the entity descriptor.
my-favorite-entityType of the entity. Corresponds to the x-cortex-type field in the entity descriptor or 'service' for services.
serviceEntity 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 YOUR_SECRET_TOKEN
Accept: */*
{
"definition": {},
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": {
"children": {
"children": "[Circular Reference]",
"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"
},
"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",
"parents": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": "[Circular Reference]",
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2026-01-01T00:00:00.000Z",
"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"
}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.
Entity identifier - can be a tag or CID
Successfully unarchived entity
Description of the entity visible in the Service, Resource, or Domain Catalog. Markdown is supported.
Corresponds to the x-cortex-groups field in the Catalog Descriptor
Unique, immutable, 18-character auto-generated identifier for the entity.
en2da8159dbeefb974Last updated ISO timestamp
Human-readable name for the entity
My Favorite EntityUnique identifier for the entity. Corresponds to the x-cortex-tag field in the entity descriptor.
my-favorite-entityType of the entity. Corresponds to the x-cortex-type field in the entity descriptor or 'service' for services.
serviceEntity 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 YOUR_SECRET_TOKEN
Accept: */*
{
"definition": {},
"description": "text",
"git": {
"alias": "text",
"basepath": "text",
"provider": "github",
"repository": "text",
"repositoryUrl": "text"
},
"groups": [
"text"
],
"hierarchy": {
"children": [
{
"children": {
"children": {
"children": "[Circular Reference]",
"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"
},
"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",
"parents": {
"definition": {},
"description": "text",
"groups": [
"text"
],
"id": "text",
"name": "text",
"parents": "[Circular Reference]",
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
},
"tag": "text",
"type": "text"
}
]
},
"id": "en2da8159dbeefb974",
"isArchived": true,
"lastUpdated": "2026-01-01T00:00:00.000Z",
"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"
}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.
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.
Maximum time (milliseconds) to wait for asynchronous property updates. Default is zero.
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 YOUR_SECRET_TOKEN
Content-Type: application/openapi;charset=UTF-8
Accept: */*
Content-Length: 6
"text"{
"ok": true,
"violations": [
{
"description": "text",
"endLine": 1,
"paths": [
"text"
],
"pointer": "text",
"ruleLink": "text",
"startLine": 1,
"title": "text",
"violationType": "MUST"
}
]
}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.
Entity identifier - can be a tag or CID
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 YOUR_SECRET_TOKEN
Accept: */*
No content
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.
A list of entity types or IDs 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 YOUR_SECRET_TOKEN
Accept: */*
No content
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.
Entity identifier - can be a tag or CID
Number of results to return per page, between 1 and 1000. Default 250.
250Page number to return, 0-indexed. Default 0.
0Successfully retrieved Kubernetes resource details
Current page number, 0-indexed
Total number of results
Total number of pages
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}/k8s?pageSize=250&page=0 HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"page": 1,
"resources": [
{
"cluster": "text",
"details": {},
"lastUpdated": "2026-01-01T00:00:00.000Z",
"name": "text",
"namespace": "text",
"type": "DEPLOYMENT"
}
],
"total": 1,
"totalPages": 1
}Last updated
Was this helpful?