# Defining dependencies

In Cortex, you have the ability to define outgoing dependencies on other entities. Cortex can also automatically [discover dependencies](#discovery) for some integrations. Having dependencies defined powers the ability to [notify owners](#automated-dependency-notifications) when a dependency deprecates its API or makes backwards incompatible changes, and the ability to visualize dependencies in a [relationship graph](#visualize-dependencies-in-the-relationship-graph).

Incoming dependencies are inferred based on the outgoing dependency definitions.

### Visualize dependencies in the relationship graph

In Cortex, you can visualize dependencies using the relationship graph at **Tools > Relationship graphs**. See the [Relationship graph documentation](/ingesting-data-into-cortex/entities-overview/entities/relationship-graph.md) for more information.

### Automated dependency notifications

{% hint style="info" %}
This feature is available in beta. Please reach out to your Cortex Customer Success Manager for access.
{% endhint %}

When a dependency deprecates its API or makes backwards incompatible changes, Cortex surfaces these issues via these methods:

* Breaking API changes are listed in your Cortex workspace under [**Settings > Breaking API changes**](https://app.getcortexapp.com/admin/settings/breaking-api-changes).
* Cortex attempts to automatically make comments on PRs containing breaking OpenAPI changes that have downstream dependencies that Cortex knows about.
* If a breaking change is merged to the default branch, Cortex alerts dependency owners via Slack that a breaking change was merged.

## Discovery

Cortex can automatically discover dependencies from your integrations:

* [AWS](/ingesting-data-into-cortex/integrations/aws.md)
* [Azure Resources](/ingesting-data-into-cortex/integrations/azureresources.md)
* [Datadog](/ingesting-data-into-cortex/integrations/datadog.md)
* [Dynatrace](/ingesting-data-into-cortex/integrations/dynatrace.md)
* [Google Cloud](/ingesting-data-into-cortex/integrations/google.md)
* [New Relic](/ingesting-data-into-cortex/integrations/newrelic.md)

## How to define dependencies

You can define dependencies manually via an entity's YAML descriptor, via the Cortex UI (if UI editing is enabled), or via the API.

Your user or API key need the `Edit entities` permission.

{% tabs %}
{% tab title="Cortex UI" %}
**Define dependencies in the Cortex UI**

1. Navigate to the entity where you need to define a dependency.
2. In the upper right corner of the entity details page, click **Configure entity**.
3. Click the **Hierarchy** tab.
4. In the **Dependencies** block, click **+Add entity**.\
   ![Add dependencies to an entity](/files/Od9EEZiDs9hIBY71CvkG)
5. In the dropdown menu, choose an entity.
6. Optionally, select an endpoint.
   * In order for an endpoint to populate in this dropdown, it must first be defined as a path in the entity's YAML file. See ["Set an endpoint for a dependency"](#set-an-endpoint-for-a-dependency) below.
7. Click **Add**.

**Set an endpoint for a dependency**

Before you can select an endpoint from the dropdown when manually defining a dependency, that endpoint must be defined as a path in the entity's YAML file. See the example below:

```yaml
openapi: 3.0.1
info:
  title: Endpoint Example Service
  description: "This is an example"
  x-cortex-tag: endpoint-example-service
  x-cortex-type: service
paths:
  /hello/world:
    get:
      description: Some description
      requestBody:
        description: optional
      responses:
        "200":
          description: optional
      deprecated: false
  /another/path:
    put:
      deprecated: false
```

In the UI, the paths will appear in the **Endpoint** dropdown:\
![The paths appear in the Endpoint dropdown](/files/RoK5KdlTOFS9411CsLrm)
{% endtab %}

{% tab title="Entity descriptor" %}
**Define dependencies in the entity descriptor**

The `x-cortex-dependency` field allows you to define a list of outgoing dependencies. A dependency should be directed towards an outgoing service or resource, or more granularly, to a specific endpoint of that entity.

```yaml
info:
  x-cortex-dependency:
    - tag: braavos
      method: GET
      path: /2.0/users/
      description: ensure user has payment information configured
      metadata:
        tags:
          - billing
          - identity
        prod: true
```

| Field           | Description                                                                         | Optional?                       |
| --------------- | ----------------------------------------------------------------------------------- | ------------------------------- |
| **tag**         | The `tag` of the entity this entity depends on, i.e. the callee. See `x-cortex-tag` | No                              |
| **method**      | HTTP method *if* depending on a specific endpoint                                   | Required if `path` is present   |
| **path**        | The actual endpoint this dependency refers to                                       | Required if `method` is present |
| **description** | A description of the dependency.                                                    | Yes                             |
| **metadata**    | JSON metadata tags for the relationship. Supports arbitrary objects.                | Yes                             |
| {% endtab %}    |                                                                                     |                                 |

{% tab title="API" %}
**Define dependencies via the API**

See the [API docs](/api/readme/dependencies.md) for authentication details.

{% hint style="warning" %}
YAML is the source of truth. If a dependency has already been set through the `cortex.yaml`, the API will return an error.
{% endhint %}

Endpoints are optional. A dependency optionally references an endpoint (`method` and `path`) of the callee, and this must already be defined in the callee's `cortex.yaml` within the `paths` field. If no endpoint is referenced it is assumed that the caller depends on **all** endpoints of the callee.

For all requests `method` or `path` are optional, however if one is present the other must also be present.

When interacting with an existing dependency, the `method` and `path` must be specified correctly to identify it.

<table><thead><tr><th>Field</th><th width="351">Description</th><th>Optional?</th></tr></thead><tbody><tr><td><strong>callerTag</strong></td><td>The <code>tag</code> of the caller.</td><td>No</td></tr><tr><td><strong>calleeTag</strong></td><td>The <code>tag</code> the caller depends on.</td><td>No</td></tr><tr><td><strong>method</strong></td><td>HTTP method <em>if</em> depending on a specific endpoint</td><td>Required if <code>path</code> is present</td></tr><tr><td><strong>path</strong></td><td>The actual endpoint (as defined in the OpenAPI file) the caller depends on</td><td>Required if <code>method</code> is present</td></tr><tr><td><strong>description</strong></td><td>A description of the dependency.</td><td>Yes</td></tr><tr><td><strong>metadata</strong></td><td>JSON metadata tags for the relationship. Supports arbitrary objects.</td><td>Yes</td></tr></tbody></table>

```json
{
  "callerTag": "my-service",
  "calleeTag": "braavos",
  "path": "/2.0/users/",
  "method": "GET",
  "description": "ensure user has payment information configured",
  "metadata": {
    "tags": ["billing", "identity"],
    "prod": true
  }
}
```

**Create a dependency**

`POST /api/v1/catalog//dependencies/?method=&path=`

```json
{
  "description": "ensure user has payment information configured",
  "metadata": 
}
```

**Retrieve a dependency**

`GET /api/v1/catalog//dependencies/?method=&path=`

**Update a dependency**

`PUT /api/v1/catalog//dependencies/?method=&path=`

{% hint style="warning" %}
PUT replaces entire object. The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as `null`.
{% endhint %}

```json
{
  "description": "ensure user has payment information configured",
  "metadata": 
}
```

**Delete a dependency**

`DELETE /api/v1/catalog//dependencies/?method=&path=`

**Bulk create or update dependencies**

`PUT /api/v1/catalog/dependencies`

:::caution PUT replaces entire object The request body is considered a modified version of the already existing entity. Leaving a field out of the JSON will be interpreted as `null`. :::

```json
{
  "values": {
    "my-service": [
      {
        "tag": "braavos",
        "path": "/2.0/users/",
        "method": "GET",
        "description": "ensure user has payment information configured",
        "metadata": 
      }
    ],
    "my-other-service": [
      {
        "tag": "my-service",
        "path": "/1.0/widget/",
        "method": "GET",
        "description": "get widget",
        "metadata": 
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Sync dependencies

Cortex syncs AWS dependencies every day at 8:00 a.m. UTC. All other dependencies sync at 12:00 a.m. UTC.

You must have the `Enable entity dependency discovery` permission to manually sync dependencies.

If you need to sync dependencies manually:

1. Navigate to **Tools > Relationship graphs**.
2. In the upper right corner of the page, click the menu icon, then click **Sync dependencies**.\
   ![](/files/oRNSrQmLhBxgzXa8Mpii)

## Troubleshooting and FAQ

#### What if I have multiple dependency sources?

When leveraging multiple dependency sources (such as Datadog and a catalog entity's YAML), all the sources will be merged together and deduplicated.

For example, if an entity YAML indicates `X->Y` and Datadog indicates `X->Y` and `X->Z`, we will have two edges presented (`X->Y` and `X->Z`).


---

# Agent Instructions: 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:

```
GET https://docs.cortex.io/ingesting-data-into-cortex/entities-overview/entities/adding-entities/dependencies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.