> For the complete documentation index, see [llms.txt](https://docs.cortex.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/external-docs.md). # 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](/ingesting-data-into-cortex/entities-overview/entities/details.md):
## 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](/ingesting-data-into-cortex/entities-overview/entities/details.md). 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**. ### Adding links via an entity descriptor In the entity descriptor, add a list of `link` objects: ```yaml 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](https://github.com/remarkjs/react-markdown). 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](/ingesting-data-into-cortex/entities-overview/entities/details.md). 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](/ingesting-data-into-cortex/entities-overview/entities/details.md). 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` : ```yaml 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)** ```yaml 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. ```yaml # 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](/ingesting-data-into-cortex/entities-overview/entities.md#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:
FieldTypeDescription
specstringThe OpenAPI JSON or YAML as a string
To convert a YAML or JSON file to a string, you can use `jq`: ```shellscript $(cat my_file.yaml | jq -Rsa) ``` See the [API docs](/api/readme/docs.md) for authentication details. ### Adding AsyncAPI docs Add AsyncAPI specs from an external URL or a path within your git repository, using type `ASYNC_API`: ```yaml 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. ```yaml 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. {% hint style="info" %} You can embed individual charts only, not full dashboards. If you're using Grafana and seeing embed errors, verify that [embedding is enabled](https://grafana.com/docs/grafana/latest/administration/configuration/#allow_embedding) in your Grafana instance. {% endhint %} ## 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](/ingesting-data-into-cortex/integrations/slack/using-the-integration-for-slack-ai-assistant.md#using-the-ai-assistant).