API Reference

Canonical reference for the ODD Platform HTTP API — hub page with per-feature sub-pages plus the OpenAPI specifications and Swagger UI walkthrough that span the whole API.

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 and to the Swagger UI hosted on every running platform — that is the place to interactively test endpoints against your own deployment.

Per-feature endpoints

• Alerts — global tab listings, per-entity listings, status mutation, halt-notification configuration, and the inbound AlertManager webhook.

• Data Collaboration — outbound to the Slack provider, per-entity threads & history, and the inbound Slack Events webhook. Routes are gated by @ConditionalOnDataCollaboration.

• Directory — four GET calls under /api/directory backing the four-level drill-down (data source types → data sources → entity types → entities).

• GenAI — the single POST /api/genai/ask endpoint that forwards natural-language questions to a configured external AI service. Gated by genai.enabled.

• Glossary — Business Glossary CRUD + lookup, term-side and resource-side linkage, faceted search, ownership and tags.

• Integrations — the two IntegrationController endpoints behind the Integration Wizard.

• Lineage — per-entity upstream / downstream graphs and group lineage, with lineage_depth and expanded_entity_ids query parameters.

• Query Examples — CRUD, faceted search, and per-entity / per-term lookup and linking. 16 endpoints across three groups.

• Reference Data — Lookup Tables surface (/api/referencedata/): Table CRUD, Column CRUD, Row CRUD, search.

• Relationships — 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 and the 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):

{
  "identity": {
    "username": "[e-mail]",
    "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": [<every Permission value>]}} to any anonymous caller — the DISABLED-mode security framing is documented at DISABLED authentication. 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:

{
  "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

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.

For the catalog of permission keys themselves (what each permission gates, which surface it applies to, the operator caveats per permission), see Permissions.

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

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.

For background on the OpenAPI standard itself, see the OpenAPI Resource Guide.

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

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 above and the per-feature pages on this site instead.

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.

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.