Custom Data

Use these operations to interact with custom data in Cortex.

Required permissions

Edit entities: Your API key must have the Edit entities permission.

Operations

List custom data for entity

get

Authorizations

Path parameters

tagOrIdstringrequired

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

Query parameters

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/json

application/problem+json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

429

200

[
  {
    "dateUpdated": "2025-03-29T00:32:36.906Z",
    "description": "text",
    "id": 1,
    "key": "text",
    "source": "YAML",
    "value": {}
  }
]

Successfully retrieved custom data. If using pagination, we do not return page, total, or totalPages in the response. An empty array is returned once you reach the end.

Retrieve custom data for entity by key

get

Authorizations

Path parameters

tagOrIdstringrequired

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

keystringrequired

Responses

application/json

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

429

200

{
  "dateUpdated": "2025-03-29T00:32:36.906Z",
  "description": "text",
  "id": 1,
  "key": "text",
  "source": "YAML",
  "value": {}
}

Successfully retrieved custom data for key

Add custom data for entity

post

Authorizations

Path parameters

tagOrIdstringrequired

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

Query parameters

forcebooleanoptional

When true, overrides values that were defined in the catalog descriptor. Will be overwritten the next time the catalog descriptor is processed.

Body

descriptionstringoptional

keystringrequired

Custom data key for the entity

Example: my-key

valueobjectrequired

Value for the key; can be any valid JSON type

Example: {"nested":{"objects":"are ok"}}

Responses

application/json

application/json

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.getcortexapp.com/api/v1/catalog/{tagOrId}/custom-data' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "text",
    "key": "my-key",
    "value": {
      "nested": {
        "objects": "are ok"
      }
    }
  }'

200

400

404

429

200

{
  "dateUpdated": "2025-03-29T00:32:36.906Z",
  "description": "text",
  "id": 1,
  "key": "text",
  "source": "YAML",
  "value": {}
}

Successfully created data

Add custom data via webhook

post

Refer to the Webhook section of the Custom Data docs for more information. This API is preconfigured in your workspace settings under Custom Integrations. The UUID corresponds to a custom data key, as well as a jq command that maps the data in this payload to an entity in your workspace.

Authorizations

Path parameters

uuidstringrequired

Body

objectoptional

Responses

application/problem+json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.getcortexapp.com/api/v1/custom-integrations/data/{uuid}' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{}'

200

429

200

No body

OK

Add custom data in bulk

put

Add multiple key/values of custom data to multiple entities

Authorizations

Query parameters

forcebooleanoptional

When true, overrides values that were defined in the catalog descriptor. Will be overwritten the next time the catalog descriptor is processed.

Body

valuesobjectrequired

Map of entity tag -> custom data key/values

Example: {"another-service-tag":[{"key":"different-key","value":{"nested":"object"}},{"key":"my-cool-key","value":"Hello again"}],"service-x":[{"key":"my-key","value":100},{"key":"my-second-key","value":"Hello"}]}

Responses

application/json

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url 'https://api.getcortexapp.com/api/v1/catalog/custom-data' \
  --header 'Authorization: Bearer JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "values": {
      "another-service-tag": [
        {
          "key": "different-key",
          "value": {
            "nested": "object"
          }
        },
        {
          "key": "my-cool-key",
          "value": "Hello again"
        }
      ],
      "service-x": [
        {
          "key": "my-key",
          "value": 100
        },
        {
          "key": "my-second-key",
          "value": "Hello"
        }
      ]
    }
  }'

200

400

429

200

{
  "errors": {
    "ANY_ADDITIONAL_PROPERTY": "NOT_FOUND"
  },
  "values": [
    {
      "dateUpdated": "2025-03-29T00:32:36.906Z",
      "description": "text",
      "id": 1,
      "key": "text",
      "source": "YAML",
      "value": {}
    }
  ]
}

Successfully created/updated custom data

Delete custom data for entity

delete

Authorizations

Path parameters

tagOrIdstringrequired

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

Query parameters

keystringrequired

forcebooleanoptional

When true, overrides values that were defined in the catalog descriptor. Will be overwritten the next time the catalog descriptor is processed.

Responses

application/json

application/problem+json

cURL

JavaScript

Python

HTTP

cURL

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

200

404

429

200

No body

Successfully deleted custom data