# API Reference

This page is the canonical reference hub for every HTTP endpoint exposed by the ODD Platform. Each feature area has its own sub-page below with operation IDs, paths, and a back-link to the feature documentation that explains the behaviour. Below the per-feature index sit pointers to the underlying [OpenAPI specifications](#openapi-specifications) and to the [Swagger UI](#interactive-testing-with-swagger-ui) hosted on every running platform — that is the place to interactively test endpoints against your own deployment.

## Per-feature endpoints

* [**Alerts**](/developer-guides/api-reference/alerts.md) — global tab listings, per-entity listings, status mutation, halt-notification configuration, and the inbound AlertManager webhook.
* [**Data Collaboration**](/developer-guides/api-reference/data-collaboration.md) — outbound to the Slack provider, per-entity threads & history, and the inbound Slack Events webhook. Routes are gated by `@ConditionalOnDataCollaboration`.
* [**Directory**](/developer-guides/api-reference/directory.md) — four `GET` calls under `/api/directory` backing the four-level drill-down (data source types → data sources → entity types → entities).
* [**Glossary**](/developer-guides/api-reference/glossary.md) — Business Glossary CRUD + lookup, term-side and resource-side linkage, faceted search, ownership and tags.
* [**Integrations**](/developer-guides/api-reference/integrations.md) — the two `IntegrationController` endpoints behind the Integration Wizard.
* [**Lineage**](/developer-guides/api-reference/lineage.md) — per-entity upstream / downstream graphs and group lineage, with `lineage_depth` and `expanded_entity_ids` query parameters.
* [**Query Examples**](/developer-guides/api-reference/query-examples.md) — CRUD, faceted search, and per-entity / per-term lookup and linking. 16 endpoints across three groups.
* [**Reference Data**](/developer-guides/api-reference/reference-data.md) — Lookup Tables surface (`/api/referencedata/`): Table CRUD, Column CRUD, Row CRUD, search.
* [**Relationships**](/developer-guides/api-reference/relationships.md) — paginated list with type filter (ERD / GRAPH / ALL) plus per-type detail endpoints.

## OpenAPI specifications

The Platform exposes two distinct OpenAPI specifications that serve different aspects:

1. **Ingest specification** — an open standards specification that unifies metadata formats and allows multiple data sources and participants of the data discovery landscape to exchange metadata effectively, transparently, and consistently. It describes the semantics of the data discovery process as we envision it. It is data-source-agnostic by design and intentionally not tied to the specifics of any particular data source or data catalog. Reference: [opendatadiscovery-specification → specification.md](https://github.com/opendatadiscovery/opendatadiscovery-specification/blob/main/specification/specification.md).
2. **Platform specification** — outlines the available endpoints, request methods, response codes, and other necessary details to interact with objects within the ODD Platform. The full OpenAPI Specification for the ODD API can be accessed at [odd-platform → odd-platform-specification/openapi.yaml](https://github.com/opendatadiscovery/odd-platform/blob/main/odd-platform-specification/openapi.yaml).

For background on the OpenAPI standard itself, see the [OpenAPI Resource Guide](https://swagger.io/resources/open-api/).

## Interactive testing with Swagger UI

The Swagger UI hosted on every running ODD Platform is the place to interactively test the endpoints documented above against your own deployment.

**Swagger UI Access**: The Swagger UI can be accessed on your deployed ODD platform at `{platform-base-url}/api/v3/api-docs`. Additionally, a demo version is available at [ODD Platform Demo Swagger UI](https://demo.oddp.io/api/v3/api-docs).\\

<figure><img src="/files/QnNRiWTj1Op2cAuQgRES" alt=""><figcaption><p>Sample list of API Endpoints</p></figcaption></figure>

### Interacting with the API via Swagger UI

**Select a definition**: There are two definitions:

* **ingestion-api:** describes all ingestion endpoints that are used by collectors.
* **platform-api:** describes all endpoints for the ODD platform, that can be used to access ODD resources.

<figure><img src="/files/ehLS5e6rUmXvSVHgv7s2" alt=""><figcaption><p>Select a definition</p></figcaption></figure>

#### **Start a Request**: Navigate to an API endpoint in the Swagger UI and click "Try it out".

<figure><img src="/files/jtqemCzCIHr0ziyKFnGX" alt=""><figcaption><p>Try it out</p></figcaption></figure>

#### **Enter Required Information**: Ensure all mandatory fields (marked with an asterisk \*) are completed.

<figure><img src="/files/ddv2OpJIzTDLqXqWeeEG" alt=""><figcaption><p>Filling required fields</p></figcaption></figure>

#### **Send the Request**: Click the “Execute” button to submit the request.

<figure><img src="/files/KCzPw4LnFWfURDbhp4pa" alt=""><figcaption><p>Executing API Request</p></figcaption></figure>

### Responses in Swagger UI

* **Response Body**: The API response will be shown in the "Response body" section.
* **Response Codes and Examples**: Examples of response objects for each response code can be found in the "Responses" section.

<figure><img src="/files/KCzPw4LnFWfURDbhp4pa" alt=""><figcaption><p>API Response Example</p></figcaption></figure>

### Further information

Learn more about how to use Swagger UI with the [Swagger UI documentation](https://swagger.io/tools/swagger-ui/).


---

# 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.opendatadiscovery.org/developer-guides/api-reference.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.