Catalog Entities

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[] · default: []optional

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

ownersstring[] · default: []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

hierarchyDepthstring · default: "full"optional

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

gitRepositoriesstring[] · default: []optional

Supports only GitHub repositories in the org/repo format

Example: cortexapps%2Fbackend,cortexapps%2Ffrontend

includeHierarchyFieldsstring[]optional

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

Example: groups

typesstring[] · default: []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

querystring · default: ""optional

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

includeArchivedboolean · default: falseoptional

Whether to include archived entities in the response

includeMetadataboolean · default: falseoptional

Whether to include custom data for each entity in the response

includeLinksboolean · default: falseoptional

Whether to include links for each entity in the response

includeSlackChannelsbooleanoptional

Whether to include Slack channels for each entity in the response

includeOwnersboolean · default: falseoptional

Whether to include ownership information for each entity in the response

includeNestedFieldsstring[]optional

List of sub fields to include for different types

Example: team:members

pageSizeinteger · int32 · default: 250required

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

pageinteger · int32 · default: 0required

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

Responses

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.getcortexapp.com/api/v1/catalog?pageSize=1&page=1' \
  --header 'Authorization: Bearer JWT'

200

400

429

{
  "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-03-29T01:06:53.114Z",
      "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
}

Successfully found entities

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

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.getcortexapp.com/api/v1/catalog/descriptors?pageSize=1&page=1' \
  --header 'Authorization: Bearer JWT'

200

429

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

Successfully retrieved entity descriptors

Retrieve entity details

get

Authorizations

Path parameters

tagOrIdstringrequired

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

Query parameters

hierarchyDepthstring · default: "full"optional

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

includeHierarchyFieldsstring[]optional

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

Example: groups

Responses

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}' \
  --header 'Authorization: Bearer JWT'

200

404

429

{
  "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-03-29T01:06:53.114Z",
  "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": [
      {
        "channel": "text",
        "description": "text",
        "inheritance": "APPEND",
        "notificationsEnabled": true
      }
    ]
  },
  "slackChannels": [
    {
      "description": "This is the engineering channel",
      "name": "engineering",
      "notificationsEnabled": true
    }
  ],
  "tag": "my-favorite-entity",
  "type": "service"
}

Successfully found entity

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

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}/gitops-logs' \
  --header 'Authorization: Bearer JWT'

200

404

429

[
  {
    "commit": "text",
    "dateCreated": "2025-03-29T01:06:53.114Z",
    "fileName": ".cortex/catalog/brain-backend.yaml",
    "repository": {
      "provider": "GITHUB",
      "repositoryName": "cortexapps/catalog"
    }
  }
]

Retrieve most recent GitOps log for entity

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

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}/openapi' \
  --header 'Authorization: Bearer JWT'

200

404

429

text

Successfully found entity descriptor

Retrieve entity Scorecard scores

get

Authorizations

Path parameters

tagOrIdstringrequired

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

Responses

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}/scorecards' \
  --header 'Authorization: Bearer JWT'

200

404

429

[
  {
    "ladderLevels": [
      {
        "level": {
          "name": "Bronze",
          "number": 1
        }
      }
    ],
    "score": 1,
    "scorePercentage": 1,
    "scorecardName": "text",
    "totalPossibleScore": 1
  }
]

All entity Scorecard scores

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

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.getcortexapp.com/api/v1/open-api' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/openapi;charset=UTF-8'

200

400

429

{
  "ok": true,
  "violations": [
    {
      "description": "text",
      "endLine": 1,
      "paths": [
        "text"
      ],
      "pointer": "text",
      "ruleLink": "text",
      "startLine": 1,
      "title": "text",
      "violationType": "MUST"
    }
  ]
}

Indicates that the entity was accepted and processed successfully

Archive an entity

put

Authorizations

Path parameters

tagOrIdstringrequired

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

Responses

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}/archive' \
  --header 'Authorization: Bearer JWT'

200

404

429

{
  "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-03-29T01:06:53.114Z",
  "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": [
      {
        "channel": "text",
        "description": "text",
        "inheritance": "APPEND",
        "notificationsEnabled": true
      }
    ]
  },
  "slackChannels": [
    {
      "description": "This is the engineering channel",
      "name": "engineering",
      "notificationsEnabled": true
    }
  ],
  "tag": "my-favorite-entity",
  "type": "service"
}

Successfully archived entity

Unarchive an entity

put

Authorizations

Path parameters

tagOrIdstringrequired

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

Responses

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}/unarchive' \
  --header 'Authorization: Bearer JWT'

200

404

429

{
  "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-03-29T01:06:53.114Z",
  "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": [
      {
        "channel": "text",
        "description": "text",
        "inheritance": "APPEND",
        "notificationsEnabled": true
      }
    ]
  },
  "slackChannels": [
    {
      "description": "This is the engineering channel",
      "name": "engineering",
      "notificationsEnabled": true
    }
  ],
  "tag": "my-favorite-entity",
  "type": "service"
}

Successfully unarchived entity

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

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://api.getcortexapp.com/api/v1/open-api' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/openapi;charset=UTF-8'

200

201

400

404

429

{
  "ok": true,
  "violations": [
    {
      "description": "text",
      "endLine": 1,
      "paths": [
        "text"
      ],
      "pointer": "text",
      "ruleLink": "text",
      "startLine": 1,
      "title": "text",
      "violationType": "MUST"
    }
  ]
}

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

Delete entity

delete

Authorizations

Path parameters

tagOrIdstringrequired

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

Responses

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}' \
  --header 'Authorization: Bearer JWT'

200

404

405

429

No body

Successfully deleted entity

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

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.getcortexapp.com/api/v1/catalog?types=text' \
  --header 'Authorization: Bearer JWT'

200

400

405

429

No body

Successfully deleted entities

Catalog Entities

Required permissions

Operations

Required permissions

Operations

List entities

List entity descriptors

Retrieve entity details

Retrieve most recent GitOps log for entity

Retrieve entity descriptor

Retrieve entity Scorecard scores

Create or update entity

Archive an entity

Unarchive an entity

Create or patch entity

Delete entity

Delete entities by type