Login to CortexBook a DemoCortex Academycortex.ioCortex Status

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 · 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
get
GET /api/v1/catalog/{tagOrId}/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

[
  {
    "dateUpdated": "2025-06-28T19:24:16.414Z",
    "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
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
get
GET /api/v1/catalog/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

[
  {
    "dateUpdated": "2025-06-28T19:24:16.414Z",
    "description": "text",
    "id": 1,
    "key": "text",
    "source": "YAML",
    "value": {}
  }
]

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
200
Successfully retrieved custom data for key
application/json
get
GET /api/v1/catalog/{tagOrId}/custom-data/{key} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

{
  "dateUpdated": "2025-06-28T19:24:16.414Z",
  "description": "text",
  "id": 1,
  "key": "text",
  "source": "YAML",
  "value": {}
}

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
Responses
200
Successfully created data
application/json
post
POST /api/v1/catalog/{tagOrId}/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "description": "text",
  "key": "my-key",
  "value": {
    "nested": {
      "objects": "are ok"
    }
  }
}
{
  "dateUpdated": "2025-06-28T19:24:16.414Z",
  "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
Path parameters
uuidstringRequired
Body
objectOptional
Responses
200
OK
post
POST /api/v1/custom-integrations/data/{uuid} HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
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
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
put
PUT /api/v1/catalog/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
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": "2025-06-28T19:24:16.414Z",
      "description": "text",
      "id": 1,
      "key": "text",
      "source": "YAML",
      "value": {}
    }
  ]
}

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
200
Successfully deleted custom data
delete
DELETE /api/v1/catalog/{tagOrId}/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
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
Query parameters
tagstringRequired
keystringRequired
forcebooleanOptional
Responses
200
Successfully deleted custom data
delete
DELETE /api/v1/catalog/custom-data HTTP/1.1
Host: api.getcortexapp.com
Authorization: Bearer JWT
Accept: */*

No content

Last updated

Was this helpful?