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

AuthorizationstringRequired

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.

Path parameters

tagOrIdstringRequired

Entity identifier - can be a tag or CID

Query parameters

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 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.

application/json

dateUpdatedstring · date-timeRequired

descriptionstringOptional

idinteger · int64Optional

keystringRequired

sourcestring · enumRequiredPossible values:

valueobject · JsonNodeRequired

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/api/v1/catalog/{tagOrId}/custom-data

GET /api/v1/catalog/{tagOrId}/custom-data?pageSize=250&page=0 HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "dateUpdated": "2026-01-01T00:00:00.000Z",
    "description": "text",
    "id": 1,
    "key": "text",
    "source": "YAML",
    "value": {}
  }
]

Retrieve custom data for entity

get

Use this endpoint when attempting to delete custom data where the key contains non-alphanumeric characters. Otherwise, use the standard API under Custom Data.

Authorizations

AuthorizationstringRequired

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.

Query parameters

tagstringRequired

Entity tag (x-cortex-tag), supports non-alphanumeric characters

keystringOptional

When set, returns the entity's value at this key. Otherwise, returns all custom data key/values for the entity.

Responses

200

Successfully retrieved custom data

application/json

dateUpdatedstring · date-timeRequired

descriptionstringOptional

idinteger · int64Optional

keystringRequired

sourcestring · enumRequiredPossible values:

valueobject · JsonNodeRequired

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/api/v1/catalog/custom-data

GET /api/v1/catalog/custom-data?tag=text HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "dateUpdated": "2026-01-01T00:00:00.000Z",
    "description": "text",
    "id": 1,
    "key": "text",
    "source": "YAML",
    "value": {}
  }
]

Retrieve custom data for entity by key

get

Authorizations

AuthorizationstringRequired

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.

Path parameters

tagOrIdstringRequired

Entity identifier - can be a tag or CID

keystringRequired

Responses

200

Successfully retrieved custom data for key

application/json

dateUpdatedstring · date-timeRequired

descriptionstringOptional

idinteger · int64Optional

keystringRequired

sourcestring · enumRequiredPossible values:

valueobject · JsonNodeRequired

404

Custom data not found for given entity and key

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/api/v1/catalog/{tagOrId}/custom-data/{key}

GET /api/v1/catalog/{tagOrId}/custom-data/{key} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "dateUpdated": "2026-01-01T00:00:00.000Z",
  "description": "text",
  "id": 1,
  "key": "text",
  "source": "YAML",
  "value": {}
}

Add custom data for entity

post

Authorizations

AuthorizationstringRequired

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.

Path parameters

tagOrIdstringRequired

Entity identifier - can be a tag or CID

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

valueobject · JsonNodeRequired

Responses

200

Successfully created data

application/json

dateUpdatedstring · date-timeRequired

descriptionstringOptional

idinteger · int64Optional

keystringRequired

sourcestring · enumRequiredPossible values:

valueobject · JsonNodeRequired

400

Invalid custom data request

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

post/api/v1/catalog/{tagOrId}/custom-data

POST /api/v1/catalog/{tagOrId}/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "description": "text",
  "key": "my-key",
  "value": {}
}

{
  "dateUpdated": "2026-01-01T00:00:00.000Z",
  "description": "text",
  "id": 1,
  "key": "text",
  "source": "YAML",
  "value": {}
}

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

AuthorizationstringRequired

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.

Path parameters

uuidstringRequired

Body

object · JsonNodeOptional

Responses

200

OK

No content

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/api/v1/custom-integrations/data/{uuid}

POST /api/v1/custom-integrations/data/{uuid} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content

Add custom data in bulk

put

Add multiple key/values of custom data to multiple entities

Authorizations

AuthorizationstringRequired

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.

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

Responses

200

Successfully created/updated custom data

application/json

400

Invalid custom data request

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/api/v1/catalog/custom-data

PUT /api/v1/catalog/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 215

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

{
  "errors": {
    "ANY_ADDITIONAL_PROPERTY": "NOT_FOUND"
  },
  "values": [
    {
      "dateUpdated": "2026-01-01T00:00:00.000Z",
      "description": "text",
      "id": 1,
      "key": "text",
      "source": "YAML",
      "value": {}
    }
  ]
}

Delete custom data for entity

delete

Authorizations

AuthorizationstringRequired

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.

Path parameters

tagOrIdstringRequired

Entity identifier - can be a tag or CID

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

200

Successfully deleted custom data

No content

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

delete/api/v1/catalog/{tagOrId}/custom-data

DELETE /api/v1/catalog/{tagOrId}/custom-data?key=text HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Delete custom data by key for entity

delete

Use this endpoint when attempting to delete custom data where the key contains non-alphanumeric characters. Otherwise, use the standard API under Custom Data.

Authorizations

AuthorizationstringRequired

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.

Query parameters

tagstringRequired

keystringRequired

forcebooleanOptional

Responses

200

Successfully deleted custom data

No content

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

delete/api/v1/catalog/custom-data

DELETE /api/v1/catalog/custom-data?tag=text&key=text HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content