Skip to main content
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. You can also delete custom data from an entity in Cortex or via API. 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 Cortex documentation.
The simplest way to add custom data is to define an object under x-cortex-custom-metadata:
FieldDescriptionRequired
keyKey or title for the custom data. Anything defined before the : serves as the key.✓
valueValue 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):
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:
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.

​
Deleting custom data

You can delete custom data that’s no longer accurate, for example a value that points to a deployment branch your team stopped using. When you delete a key, Cortex re-evaluates the entity’s Scorecards so that rules based on that key reflect the change.

​
Deleting custom data in Cortex

To delete custom data, you need permission to edit the entity. This includes users with the Edit and Create Entities permission and, if your workspace uses team ownership entity editing, the entity’s owners.
  1. Go to the entity’s details page.
  2. In the left entity sidebar, select Custom data & metrics.
  3. On the Custom data & metrics page, locate the key you want to remove, then click the trash icon. The Delete custom data window opens.
  4. Click Delete.
Each deletion is recorded in your workspace’s audit logs.
Custom data defined in the entity descriptor (tagged YAML) can’t be deleted from this page. To remove it, delete the key from the entity’s YAML. If an automated process sends a key through the API or a webhook, update that process too, so the key isn’t added back.

​
Deleting custom data via API

To delete custom data programmatically, send a DELETE request to /api/v1/catalog/{tag}/custom-data with the key query parameter. See Delete custom data for entity for details.
The Cortex MCP can’t delete custom data. To protect your data from accidental removal, Cortex doesn’t make any delete endpoints available through the MCP. Learn more in What the Cortex MCP can’t do.

​
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.
The 'Custom data' option selected in the Integrations drop-down menu.
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.
Last modified on October 22, 2026