Skip to main content
Version: 0.0.0-dev

TEMS Local Indexer — Indexing API

The Indexing API is the entry point of the TEMS Local Indexer — the EBU-managed service that runs the three-stage RQ pipeline (preprocessing → embedding → storing) on TemsCore content and pushes the enriched result to the configured remote DBs (the Source Explorer's PEACH being the canonical one).

The local-indexer is published as a TEMS Contract 1 EDC offering. A consumer acquires the offering through the Federated Catalogue, their EDC connector mints an EDR for the transfer, and they invoke this API from their data plane (or directly, EDR-native). This page documents the API contract once you have a valid bearer ; the acquisition flow itself is handled by your TEMS dashboard / Catalogue UI, not by the indexer.

Authentication​

All protected endpoints require a bearer JWT on the Authorization header. Two bearer shapes are recognised and routed by the unverified iss claim :

KC OAuth2​

A bearer signed by the EBU Keycloak edc realm — issuer https://ebu.home.dndm.ch/auth/realms/edc, audience local-indexer-api. The JWT's scope claim selects the sub-mode :

  • proxy (scope index:proxy) — the consumer's EDC data plane proxies the call. It validates the upstream EDR, mints a KC JWT via client_credentials, and forwards two headers :

    Authorization: Bearer <kc-jwt>
    X-Dataspace-Identity: <consumer-did>

    The indexer reads the consumer DID from X-Dataspace-Identity for the audit trail. Missing the header on this path → 400 Bad Request with detail = "X-Dataspace-Identity header is required when authenticating via OAuth2 with the 'index:proxy' scope".

  • internal (scope index:internal) — an EBU-controlled service (cron, batch job) calling the indexer directly. The JWT subject (KC azp = client_id) lands in the audit identity. No X-Dataspace-Identity required.

EDR-native​

A bearer signed by the consumer's EDC connector (dataspace EDR), presented to the indexer without going through a data plane. The indexer verifies the EDR and extracts the consumer DID from the aud claim.

Errors​

StatusWhen
401 UnauthorizedMissing / malformed bearer, bad signature, wrong issuer, wrong audience, expired, unknown iss. Body : {"detail": "<reason>"}.
400 Bad RequestKC proxy sub-mode without X-Dataspace-Identity header.
422 Unprocessable EntityBody shape doesn't match TemsCorePayload (FastAPI/Pydantic validation).
500 Internal Server ErrorPipeline failed to enqueue (Redis down, etc.). Logged with full stack ; client gets a generic message.

Both Authorization: Bearer <token> (RFC 6750 §2.1) and the EDC convention of a raw JWT in Authorization: <token> (no prefix) are accepted ; the data plane forwards whichever shape the consumer sent.

Body — TemsCore payload​

POST /index accepts a raw TemsCore document with mediaWork (the work descriptor) + articles (the version variants, including the canonical version referenced by mediaWork.hasCanonicalVersion).

Callers do NOT need to compute embeddings — the indexer does that as part of the pipeline before forwarding the enriched result to the configured remote DBs.

Response​

POST /index returns immediately with a jobId ; the actual pipeline work is asynchronous (RQ workers). Poll GET /status/{jobId} to track each stage independently.

Authentication​

OAuth2 JWT from the EBU Keycloak edc realm. Mint via the client_credentials grant against one of the indexer's two KC clients :

  • local-indexer-data-plane (scope index:proxy) — used by the consumer's EDC data plane when proxying acquired calls.
  • local-indexer-internal (scope index:internal) — used by EBU-controlled internal callers (cron, batch).

Token endpoint : https://ebu.home.dndm.ch/auth/realms/edc/protocol/openid-connect/token.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT