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 entities permission.
Archive entities: Your API key must have the Archive entities permission.
Delete entities: Your API key must have Delete entities permission.

Operations

Last updated 2 months ago

Was this helpful?

List entities

get

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.

Authorizations

Query parameters

groupsstring[]Optional

Filter based on groups, which correspond to the x-cortex-groups field in the Catalog Descriptor. Accepts a comma-delimited list of groups

Default: []

ownersstring[]Optional

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

Default: []

hierarchyDepthstringOptional

Depth of the parent / children hierarchy nodes. Can be 'full' or a valid integer

Default: full

gitRepositoriesstring[]Optional

Supports only GitHub repositories in the org/repo format

Default: []Example: cortexapps%2Fbackend,cortexapps%2Ffrontend

includeHierarchyFieldsstring[]Optional

List of sub fields to include for hierarchies. Only supports 'groups'

Example: groups

typesstring[]Optional

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.

Default: []Example: service,rds,s3,domain

querystringOptional

Filter based on a search query. This will search across entity properties. If provided, results will be sorted by relevance.

Default: ""

includeArchivedbooleanOptional

Whether to include archived entities in the response

Default: false

includeMetadatabooleanOptional

Whether to include custom data for each entity in the response

Default: false

includeLinksbooleanOptional

Whether to include links for each entity in the response

Default: false

includeSlackChannelsbooleanOptional

Whether to include Slack channels for each entity in the response

includeOwnersbooleanOptional

Whether to include ownership information for each entity in the response

Default: false

includeNestedFieldsstring[]Optional

List of sub fields to include for different types

Example: team:members

pageSizeinteger · int32Required

Number of results to return per page, between 1 and 1000. Default 250.

Default: 250

pageinteger · int32Required

Page number to return, 0-indexed. Default 0.

Default: 0

Responses

200

Successfully found entities

application/json

400

Invalid filters

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

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-06-09T09:40:47.382Z",
      "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
}

List entity descriptors

get

List entity descriptors

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

Authorizations

Query parameters

yamlbooleanOptional

When true, returns the YAML representation of the descriptors

typesstring[]Optional

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.

Example: service,rds,s3,domain

pageSizeinteger · int32Required

Number of entities to return per page

pageinteger · int32Required

Page number to return, 0 indexed

Responses

200

Successfully retrieved entity descriptors

application/json

Responseone of

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

GET /api/v1/catalog/descriptors HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

{
  "descriptors": [
    "text"
  ],
  "page": 1,
  "total": 1,
  "totalPages": 1
}

Retrieve entity details

get

Authorizations

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Query parameters

hierarchyDepthstringOptional

Depth of the parent / children hierarchy nodes. Can be 'full' or a valid integer

Default: full

includeHierarchyFieldsstring[]Optional

List of sub fields to include for hierarchies. Only supports 'groups'

Example: groups

Responses

200

Successfully found entity

application/json

404

Entity not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

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-06-09T09:40:47.382Z",
  "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"
}

Retrieve most recent GitOps log for entity

get

Authorizations

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Responses

200

Retrieve most recent GitOps log for entity

application/json

404

Entity GitOps log not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

GET /api/v1/catalog/{tagOrId}/gitops-logs HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

[
  {
    "commit": "text",
    "dateCreated": "2025-06-09T09:40:47.382Z",
    "fileName": ".cortex/catalog/brain-backend.yaml",
    "repository": {
      "provider": "GITHUB",
      "repositoryName": "cortexapps/catalog"
    }
  }
]

Retrieve entity descriptor

get

Retrieve entity descriptor

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

Authorizations

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Query parameters

yamlbooleanOptional

When true, returns the YAML representation of the descriptor

Responses

200

Successfully found entity descriptor

application/json

Responseone of

stringOptional

objectOptional

404

Entity not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

GET /api/v1/catalog/{tagOrId}/openapi HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

text

Retrieve entity Scorecard scores

get

Authorizations

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Responses

200

All entity Scorecard scores

application/json

404

Entity not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

get

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 or update entity

post

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

Authorizations

Query parameters

dryRunbooleanOptional

When true, this endpoint only validates the descriptor contents and returns any errors or warnings.

githubPullRequestinteger · int32Optional

Add a comment with validation errors on the pull request with the given ID

Body

anyOptional

Responses

200

Indicates that the entity was accepted and processed successfully

application/json

400

Invalid YAML (major errors or incorrectly formatted YAML)

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

post

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"
    }
  ]
}

Archive an entity

put

Authorizations

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Responses

200

Successfully archived entity

application/json

404

Entity not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

put

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-06-09T09:40:47.382Z",
  "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"
}

Unarchive an entity

put

Authorizations

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Responses

200

Successfully unarchived entity

application/json

404

Entity not found

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

put

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-06-09T09:40:47.382Z",
  "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"
}

Create or patch entity

patch

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.

Authorizations

Query parameters

dryRunbooleanOptional

When true, this endpoint only validates the descriptor contents and returns any errors or warnings.

deleteMarkerValuestringOptional

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.

appendArraysbooleanOptional

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.

failIfEntityDoesNotExistbooleanOptional

Default behavior is to upsert the entity, set failIfEntityDoesNotExist=true to fail (404) if the entity specified in x-cortex-tag does not exist.

Body

anyOptional

Responses

200

Indicates that the entity body was accepted, and the referenced `x-cortex-tag` existed and patched successfully

application/json

201

Indicates that the entity body was accepted, and the referenced `x-cortex-tag` did not exist and was created successfully

application/json

400

Invalid YAML (major errors or incorrectly formatted YAML)

application/json

404

Specified entity does not exist (when failIfDoesNotExist is set to true)

application/json

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

patch

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"
    }
  ]
}

Delete entity

delete

Authorizations

Path parameters

tagOrIdstringRequired

The tag (x-cortex-tag) or unique, auto-generated identifier for the entity.

Responses

200

Successfully deleted entity

404

Entity not found

application/json

405

Entity delete is not allowed

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

delete

DELETE /api/v1/catalog/{tagOrId} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

No content

Delete entities by type

delete

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

Authorizations

Query parameters

typesstring[]Required

A list of entity types to delete

Example: service,rds,s3,domain

Responses

200

Successfully deleted entities

400

Invalid filters

application/json

405

Entity delete is not allowed

429

The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.

application/problem+json

delete

DELETE /api/v1/catalog HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

No content