> 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](/ingesting-data-into-cortex/integrations/slack.md) configured, you can look up an entity's documentation links without leaving Slack using the [AI Assistant](/get-started/cortex-ai-assistant.md): * `/cortex links ` lists all documentation links for an entity * `/cortex links ` lists links of a specific type (e.g. `openapi`, `documentation`) Replace `` with the entity's tag or ID. **Examples** ``` /cortex links en29f044598b112345 /cortex links openapi plugin-extension ``` {% hint style="info" %} The `links` command surfaces docs defined under `x-cortex-link`. It does not return charts defined under `x-cortex-dashboards`. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/external-docs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.