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

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

HTTPcURLJavaScriptPython

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

[
  {
    "dateUpdated": "2025-05-16T20:04:23.422Z",
    "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

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

HTTPcURLJavaScriptPython

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

{
  "dateUpdated": "2025-05-16T20:04:23.422Z",
  "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

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

HTTPcURLJavaScriptPython

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-05-16T20:04:23.422Z",
  "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

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

HTTPcURLJavaScriptPython

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

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

HTTPcURLJavaScriptPython

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-05-16T20:04:23.422Z",
      "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

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

HTTPcURLJavaScriptPython

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

No content