> 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.md). # 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). * [**GenAI**](/developer-guides/api-reference/genai.md) — the single `POST /api/genai/ask` endpoint that forwards natural-language questions to a configured external AI service. Gated by `genai.enabled`. * [**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. These sub-pages cover the feature surfaces operators reach for most often; they do not document every operation the platform exposes. The full OpenAPI specification carries more endpoint groups than have a sub-page here (for example, the data-set, data-source, owner, policy, role, tag, and search families), so the complete, always-current endpoint list is the [OpenAPI specification](#openapi-specifications) and the [Swagger UI](#interactive-testing-with-swagger-ui) on your own deployment rather than this index. ## Identity and introspection Three endpoint families sit outside the per-feature sub-pages above because they back the platform's auth + introspection + permission machinery rather than a specific feature surface. Third-party SDK consumers building SPA-equivalent client logic need to call them; the per-feature sub-pages do not enumerate them today. ### `GET /api/identity/whoami` Returns the caller's identity and the full set of permissions resolved for that identity. The SPA dispatches this on bootstrap to determine which affordances to show. Response shape (success): ```json { "identity": { "username": "alice@example.com", "permissions": ["DATA_ENTITY_DESCRIPTION_UPDATE", "DATA_ENTITY_TAGS_UPDATE", "..."] }, "owner": { "id": 42, "name": "Alice Example" } } ``` Under `auth.type=DISABLED`, the endpoint returns the synthetic admin payload `{"identity": {"username": "admin", "permissions": []}}` to any anonymous caller — the DISABLED-mode security framing is documented at [DISABLED authentication](/configuration-and-deployment/enable-security/authentication/disabled-authentication.md). Under any of the three real authentication modes — `LOGIN_FORM`, `OAUTH2`, `LDAP` — the response is the real identity and the real permission set. (A request authenticated by a service-to-service token resolves the same way, but service-to-service tokens are a separate mechanism layered on top of `auth.type`, not a fourth value of it; `auth.type` itself is only ever `DISABLED`, `LOGIN_FORM`, `OAUTH2`, or `LDAP`.) ### `GET /api/appInfo` Returns deployment-level introspection: the platform's build version and the configured authentication mode. Used by the SPA on bootstrap to render the auth-mode-dependent surface (the Owner-association card on the catalog overview, the login-form redirect target, the appropriate sign-in affordance). Response shape: ```json { "projectVersion": "1.x.y", "authType": "LOGIN_FORM" } ``` The `authType` value is one of the literal strings the platform's auth resolver carries — `DISABLED`, `LOGIN_FORM`, `OAUTH2`, `LDAP`. The endpoint has no permission gate; under DISABLED it is anonymously reachable along with the rest of the platform's API surface. ## Permission read surface — two-endpoint orchestration The platform's permission machinery exposes the caller's permissions through **two** endpoints, each scoped to a different class of resource. SDK code reading the OpenAPI spec's `PermissionResourceType` enum will see four values (`DATA_ENTITY`, `TERM`, `QUERY_EXAMPLE`, `MANAGEMENT`) and naturally build a four-way switch — but only three of those four are valid against the contextual endpoint; the fourth lives on the non-contextual endpoint. | Permission class | Endpoint | `PermissionResourceType` values | | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | -------------------------------------- | | Contextual — permissions scoped to a specific resource id | `GET /api/resource/{type}/{id}/permissions` | `DATA_ENTITY`, `TERM`, `QUERY_EXAMPLE` | | Non-contextual — management-scope permissions (Policy / Role CRUD, Lookup Table CRUD, Tag CRUD, Owner Association, etc.) | `GET /api/identity/whoami` (the `identity.permissions` array) | `MANAGEMENT` | {% hint style="warning" %} **Calling `GET /api/resource/MANAGEMENT/0/permissions` returns HTTP 400 with the message "Resource type MANAGEMENT does not have context".** The OpenAPI spec lists `MANAGEMENT` in the `PermissionResourceType` enum (so the symbol is generated into client SDKs), but the runtime endpoint rejects management-scope reads — they live on `whoami`. SDK code that builds a four-way switch over the enum needs to route the `MANAGEMENT` arm through `whoami.identity.permissions` instead of `/api/resource/{type}/{id}/permissions`. The other three values — `DATA_ENTITY`, `TERM`, `QUERY_EXAMPLE` — are the valid contextual types; there is no `NAMESPACE` resource type. The spec-vs-runtime drift on `PermissionResourceType` is on the platform-side roadmap (tightening the enum or splitting it into two enums); until then, treat the two-endpoint orchestration as the authoritative client contract. {% endhint %} For the catalog of permission keys themselves (what each permission gates, which surface it applies to, the operator caveats per permission), see [Permissions](/configuration-and-deployment/enable-security/authorization/permissions.md). ## Ingestion endpoint response contract `POST /ingestion/entities` is the load-bearing call every collector makes for each metadata batch. The endpoint returns **HTTP 200** on success (the OpenAPI spec declares 201; the spec-vs-runtime drift is tracked separately and does not affect collector retry logic — collectors should accept any 2xx). Three client-side error conditions currently surface as HTTP 5xx rather than structured 4xx responses — duplicate ODDRN inside one batch, unknown `data_source_oddrn`, and payloads exceeding the configured codec limit. Collector authors writing retry-with-backoff must treat these as client errors that look like server errors. See [Integrations → Ingestion error contract](/integrations/integrations.md#ingestion-error-contract) for the per-condition table, the recommended pre-flight pattern, the per-data-source serialisation caveat under contention, and the destructive-path observability gap. ## 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).\\ {% hint style="info" %} **Fixed in 0.28.0.** Between the 2026-04 Spring Framework 6.2 upgrade and 0.28.0, the Swagger UI shell loaded but the API definition did not — the OpenAPI document request hung, because the then-pinned `springdoc-openapi` 2.2.0 was binary-incompatible with Spring Framework 6.2 (`NoSuchMethodError` on a removed `ControllerAdviceBean` constructor). 0.28.0 bumps `springdoc-openapi` to the Spring-Boot-3.4-compatible line (2.8.17): the interactive Swagger UI loads both definitions again, and the raw OpenAPI JSON is served at `{platform-base-url}/api/v3/swagger-ui.html` (per-definition documents at `/platform-api` and `/ingestion-api`). Deployments on 0.27.x and earlier remain affected — there, explore the API via the [OpenAPI specifications](#openapi-specifications) above and the per-feature pages on this site instead. {% endhint %} {% hint style="warning" %} **The Swagger UI's reachability depends on the deployment's authentication mode.** The path `/api/v3/api-docs` is **not** on the platform's ingestion-only whitelist; it inherits the platform's general API-surface filter chain, which differs per auth mode. The matrix: **What this means.** A separation-of-duties-conscious organisation expecting "Swagger UI is admin-only" cannot assume that posture — under every supported auth mode, any signed-in user (or any anonymous caller under DISABLED) reads the full OpenAPI spec, including endpoint paths, request schemas, and the full enumeration of `Permission` enum values. This is the "reconnaissance via spec" risk class. **Mitigation today.** If admin-only Swagger UI access is a deployment requirement, gate the path at a reverse-proxy layer in front of the platform (allow `/api/v3/api-docs` only from a specific operator-defined identity claim or IP range). The platform does not currently expose an `auth.swagger.enabled` toggle that would let operators opt out of public spec discoverability without a reverse-proxy rule; the upstream code-side fix is on the roadmap. {% endhint %} | Auth mode | Swagger UI reachability | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `DISABLED` | **Anonymously reachable** — the platform's DISABLED auth configuration permits every request, including Swagger UI and the full OpenAPI surface (about 200 operations). | | `LOGIN_FORM` | Reachable to **any authenticated session** — no per-route permission gate; the path is not enumerated in the platform's security rules. | | `OAUTH2` | Reachable to **any authenticated session** — same shape as LOGIN\_FORM. | | `LDAP` | Reachable to **any authenticated session** — same shape as LOGIN\_FORM. |

Sample list of API Endpoints

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

Select a definition

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

Try it out

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

Filling required fields

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

Executing API Request

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

API Response Example

### Further information Learn more about how to use Swagger UI with the [Swagger UI documentation](https://swagger.io/tools/swagger-ui/). --- # 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.md?ask= ``` 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.