> For the complete documentation index, see [llms.txt](https://docs.opendatadiscovery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opendatadiscovery.org/developer-guides/api-reference/relationships.md).

# Relationships

`RelationshipController` exposes three endpoints. The same payloads are surfaced on the source and target dataset's detail pages — when a dataset participates in any relationships, those are listed under the dataset's relationships cluster. For the cardinality model (`ONE_TO_EXACTLY_ONE` / `ONE_TO_ZERO_OR_ONE` / `ONE_TO_ONE_OR_MORE` / `ONE_TO_ZERO_ONE_OR_MORE`), the per-adapter ingestion coverage, and the ERD vs graph relationship distinction, see the [Relationships](/features/data-modelling/relationships.md) page.

| Method + Path                                                         | Operation                  | What                                                                                                                                                                                                                          |
| --------------------------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/relationships?page=N&size=M&type=ERD\|GRAPH\|ALL&query=...` | `getRelationships`         | Paginated list with optional type filter and free-text query. The `query` matches the relationship's own name (case-insensitive substring) — **not** the source or target dataset name. Returns `DataEntityRelationshipList`. |
| `GET /api/relationships/erd/{relationship_id}`                        | `getERDRelationshipById`   | Full ERD relationship details (source / target / cardinality / owner).                                                                                                                                                        |
| `GET /api/relationships/graph/{relationship_id}`                      | `getGraphRelationshipById` | Full graph relationship details (source / target node, edge metadata).                                                                                                                                                        |

{% hint style="warning" %}
**The `{relationship_id}` path parameter is the relationships-class data entity id, not the row id of the relationship itself** — supplying the relationship's own primary key returns **HTTP 404**. Always round-trip through the `id` returned by `GET /api/relationships`, which is the value both detail endpoints expect. The full explanation is on the [Relationships feature page → Known operator caveats](/features/data-modelling/relationships.md#known-operator-caveats).
{% endhint %}

{% hint style="warning" %}
**The list endpoint carries no per-resource permission — any authenticated caller enumerates every visible relationship.** As of 0.28.0 it applies the catalog's default visibility rules (soft-deleted, hollow, and excluded-from-search relationship entities are hidden, matching `GET /api/dataentities`); on 0.27.x and earlier it was a full enumeration of the relationship class with no visibility filtering at all. It still does not filter by owner, namespace, or tenant — do not treat it as an access-filtered surface. See the [Relationships feature page → Known operator caveats](/features/data-modelling/relationships.md#known-operator-caveats) for the visibility and authorization detail.
{% endhint %}

## See also

* [API Reference hub](/developer-guides/api-reference.md) — the full per-feature index.
* [Relationships](/features/data-modelling/relationships.md) — feature description, cardinality model, per-adapter ingestion coverage, ERD vs graph distinction.


---

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

```
GET https://docs.opendatadiscovery.org/developer-guides/api-reference/relationships.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.