Login to CortexBook a DemoCortex Academycortex.ioCortex Status

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

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
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-28T18:23:26.942Z",
      "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

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
or
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
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-28T18:23:26.942Z",
  "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
get
GET /api/v1/catalog/{tagOrId}/gitops-logs HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

[
  {
    "commit": "text",
    "dateCreated": "2025-06-28T18:23:26.942Z",
    "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
or
objectOptional
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
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.

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
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
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-28T18:23:26.942Z",
  "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
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-28T18:23:26.942Z",
  "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
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
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
delete
DELETE /api/v1/catalog HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

No content

Last updated

Was this helpful?