Skip to main content
Documentation lives in too many places—wikis, git repos, API spec tools, dashboards. Cortex pulls it together on the entity that owns it, so the people working with a service don’t have to go looking. You can attach four kinds of documentation to an entity:
  • Links - Any URL—e.g. runbooks, tech specs, dashboards, health checks—or custom types you define
  • Git-driven markdown - Markdown files from your repo, embedded automatically
  • API specs - OpenAPI/Swagger or AsyncAPI specs, rendered in a built-in API explorer
  • Dashboard charts - Embedded charts from Datadog, Grafana, New Relic, or other sources
Attached documentation appears in the Links & docs section of an entity’s details page:

​
Prerequisites

Before editing an entity via the UI, make sure that UI editing is enabled.
  1. Navigate to the entity’s details page.
  2. In the upper-right corner, click Configure entity.
  3. In the entity’s left sidebar, click Links.
    The Links page in the Cortex UI.
  4. Click +Add.
  5. In the Link side panel, do the following:
    • From the Type drop-down menu, select the type of link.
      • To create a new type of link, enter the name into the Search items field, then click Add new [link type name]. The link type is created and applied to the entity.
    • Under Name, enter a name for the link.
    • Under URL, enter the URL.
    • Under Description, enter a description of the link.
  6. Click Add.
In the entity descriptor, add a list of link objects:
name, type, and url are required. The type value is freeform. Common examples include dashboard, documentation, healthcheck, logs, metrics, and runbook.

​
Adding git-driven Markdown docs to an entity

Cortex automatically detects and embeds markdown files from the docs folder of your linked repository, or from the root directory. When relevant files are found, they appear under Links & docs in the entity’s left sidebar. Markdown is rendered using the React markdown library. No configuration is required as this happens automatically when a repository is associated with the entity.

​
Adding API specs to an entity

Cortex renders OpenAPI/Swagger and AsyncAPI specs in a built-in API explorer on the entity details page. From the API explorer, you can also authorize your API and run queries directly. To access the API explorer:
  1. Navigate to the entity’s details page.
  2. In the left entity sidebar, click API explorer.
    The API Explorer in Cortex.

​
Adding OpenAPI docs

​
From an external URL

Add the spec URL to the entity descriptor with type OPENAPI :

​
From your git repo (relative path)

​
From another git repo

You can reference specs in repos not associated with the entity, using the format provider:org/repo:path/to/file. To target a specific branch, use provider:org/repo:branch:path/to/file. If branch is omitted, the repo’s default branch is used.

​
Via the Cortex API

Send your OpenAPI JSON or YAML to the endpoint POST /api/v1/catalog/documentation/openapi, using your entity’s Cortex tag. One API doc per entity can be uploaded. It will appear automatically as an API doc entry in the API explorer dropdown. The request body is JSON with a single field: To convert a YAML or JSON file to a string, you can use jq:
See the API docs for authentication details.

​
Adding AsyncAPI docs

Add AsyncAPI specs from an external URL or a path within your git repository, using type ASYNC_API:

​
Adding embedded dashboards to an entity

Cortex supports embedding individual charts from Datadog, Grafana, New Relic, or any other source that provides an iframe embed URL. Embedded charts appear on the Dashboard page in the entity’s left sidebar.
  • type is optional. Accepted values are datadog, grafana, and newrelic.
    • Content from sources other than Datadog, Grafana, or New Relic is supported. Omit the type field, and ensure the URL is publicly accessible or supports cross-platform authentication. For example, content accessible via VPN displays in Cortex when you’re on the VPN.
  • url is the src value from the iframe embed generated by your dashboard tool, not the dashboard’s browser URL.
  • The URL must be publicly accessible, or accessible via the same VPN your browser is on.
You can embed individual charts only, not full dashboards. If you’re using Grafana and seeing embed errors, verify that embedding is enabled in your Grafana instance.

​
Accessing docs via Slack

If you have the Slack integration configured, you can look up an entity’s documentation links without leaving Slack. Mention @Cortex in a channel or direct message and ask a question like “Where are the docs for payments-api?”. For setup and usage details, refer to Using the AI assistant.
Last modified on September 21, 2026