Adding external documentation

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:

Adding links to an entity

Adding links via the Cortex UI

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.

   
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.

Adding links via an entity descriptor

In the entity descriptor, add a list of link objects:

x-cortex-link:
  - name: Checkout Service Runbook
    type: runbook
    url: https://wiki.example.com/runbooks/checkout-service
    description: Steps for diagnosing and resolving incidents in the checkout service

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.

   

Adding OpenAPI docs

From an external URL

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

x-cortex-link:
  - name: Payment Service API Spec
    type: OPENAPI
    url: https://api.example.com/specs/payment-service.yaml

From your git repo (relative path)

x-cortex-link:
  - name: Payment Service API Spec
    type: OPENAPI
    url: ./docs/payment-service-spec.yaml

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.

# GitHub
x-cortex-link:
  - name: Payment Service API Spec
    type: OPENAPI
    url: github:acme-corp/api-specs:services/payment-service/openapi.yaml

# GitLab
  - name: Payment Service API Spec
    type: OPENAPI
    url: gitlab:acme-corp/api-specs:services/payment-service/openapi.yaml

# Azure DevOps
  - name: Payment Service API Spec
    type: OPENAPI
    url: azuredevops:acme-corp/api-specs:services/payment-service/openapi.yaml

# Bitbucket
  - name: Payment Service API Spec
    type: OPENAPI
    url: bitbucket:acme-corp/api-specs:services/payment-service/openapi.yaml

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:

Field	Type	Description
spec	string	The OpenAPI JSON or YAML as a string

To convert a YAML or JSON file to a string, you can use jq:

$(cat my_file.yaml | jq -Rsa)

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:

x-cortex-link:
  - name: Order Events API Spec
    type: ASYNC_API
    url: ./docs/order-events-spec.yml

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.

x-cortex-dashboards:
  embeds:
    - type: datadog
      url: https://app.datadoghq.com/graph/embed?token=abc123&height=300&width=600

• 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.