Adding custom data

Custom data extends Cortex's out-of-the-box metadata by letting you attach additional attributes to entities. It can be used in CQL queries and Scorecard rules.

Custom data can be defined manually in the entity descriptor, added programmatically via API, or sent through a custom webhook integration.

Custom data vs. custom metrics

Cortex also offers custom metrics for Eng Intelligence. Note the following differences between custom data and custom metrics:

• Custom data - Used for static or slowly changing metadata (e.g. deployment environments, compliance statuses). Best for enriching entity details, reporting, and Scorecard rules. Note that new values overwrite previous ones for the same key, so it's not suited for time-sensitive tracking. Refer to the use cases below.

• Custom metrics - Used for time series or trending data (e.g. incident counts, SLOs). Designed for analytics; use them in dashboards, entity pages, and Scorecards. See Custom metrics for more information.

Defining custom data

There are a few ways to add custom data to an entity:

• In the entity descriptor - Best for low-volume, human-maintained data; requires updating the entity's YAML when the data changes.

• Via REST API (POST) - Best for data from automated processes like CI/CD pipelines.

• Via webhook - Useful when you don't have access to the Cortex tag or can't add authentication headers, as it requires neither.

Defining custom data in the entity descriptor

Learn more about entity YAML descriptors in the Managing entities documentation.

The simplest way to add custom data is to define an object under x-cortex-custom-metadata:

x-cortex-custom-metadata:
  team-owner: platform-engineering
  deployment-env: production
  compliance-status:
    value: SOC2
    description: Certified under SOC2 Type II as of 2024.
  pagerduty-enabled: true

Field	Description	Required
key	Key or title for the custom data. Anything defined before the : serves as the key.	✓
value	Value for the custom data. Anything defined after the : is the value.	✓

Custom data supports any type: scalars (strings, numbers, booleans), objects, and lists. Once added, key-value pairs appear on the entity's custom data page, tagged as YAML.

Adding descriptions

To include a description alongside a value, use the explicit value + description syntax. Note that when a description is present, value must be explicitly defined (rather than inlined):

x-cortex-custom-metadata:
  supported-regions:
    value: 3
    description: us-east-1, eu-west-1, ap-southeast-1
  on-call-rotations:
    value: 2
    description: Primary and secondary on-call rotations are active for this service.

Field	Description	Required
key	Key or title for the custom data. Anything defined before the : serves as the key.	✓
value	Value for the key; should be defined explicitly with value:.	✓
description	Description of the custom data	✓

Descriptions are always optional, but if you want to add one, the value key is required.

Defining custom data via API

You can pipe custom data directly into Cortex by POSTing to /api/v1/catalog/{tag}/custom-data, where {tag} is the entity's x-cortex-tag. The request body requires JSON. See the Custom data API docs for authentication details and required fields.

Key precedence and overwriting

If a key is already defined in the entity descriptor, the API does not overwrite it. Instead, it returns the existing value with YAML as the source. To explicitly overwrite a YAML-defined value, use the force=true query parameter. That said, if you find yourself relying on force=true, it's worth updating or removing the field from the YAML to keep a clear source of truth.

Custom data added via API displays with an API tag.

Bulk upload

To upload multiple keys for one or more entities at once, PUT to /api/v1/catalog/custom-data:

{
  "values": {
    "payments-service": [
      {
        "key": "deployment-env",
        "value": "production",
        "description": "The environment this service is currently deployed to."
      }
    ],
    "user-auth-service": [
      {
        "key": "compliance-status",
        "value": {
          "certified": "SOC2",
          "last-audit": "2025-03-15",
          "reviewed-by": "security-team"
        }
      }
    ]
  }
}

Each tag can include multiple key-value objects, following the same shape as the single upload API.

Defining custom data via webhook

Refer to Custom webhook integrations

Data source hierarchy

When the same key is defined from multiple sources, Cortex resolves conflicts in the following order:

1. Entity descriptor (YAML) - The source of truth. Keys defined here cannot be overridden by the API or webhooks by default. Use force=true to override them via API, but note that the forced value will be overwritten the next time the entity descriptor is re-processed.

2. API and webhooks - Treated equally; either can override the other.

Use cases

Custom data is flexible by design. Below are two of the most common ways teams put it to work.

Cataloging

Cortex catalogs surface a lot out of the box—ownership, integration data, and more—but you may have internal fields that don't map to any integration. Custom data fills that gap. Common examples include:

• Which AWS zones is this deployed in?

• What databases does this entity consume?

• When was the last successful CI run?

If the answers fit a fixed list, consider using groups instead. They display on an entity's details page and work well as catalog filters. Custom data is better suited for flexible or freeform values.

Once defined, custom data can be queried with the Query builder, explored via CQL reports, viewed directly on an entity's details page, or added as a column in Data Explorer's table view.

Scorecards

Custom data integrates directly with Scorecards. When adding a rule, select Custom data from the Integrations drop-down menu. Cortex automatically surfaces variables based on the custom data you've defined.

For more advanced use cases, push JSON payloads via the custom data API and process them in a Scorecard using jq, or pass them as input to a custom OPA policy rule.