Skip to main content

API Surfaces

The backend is API-first. HTTP clients such as frontend applications, dashboards, and batch-upload tools integrate through the documented HTTP and SSE APIs. Kafka/DMS partner backends are intended to integrate through a separate partner ingestion event surface, but live handoff is blocked pending doc.uploaded contract reconciliation. Neither client type embeds document processing, retrieval, memory, or answer-generation logic.

HTTP wire contracts, request and response shapes, streaming event order, authentication headers, status codes, and error payloads live in the API reference. Partner event contracts live beside them:

This page defines the architectural boundary only.

Current boundary​

The current platform exposes HTTP/SSE APIs and implements a separate Kafka/DMS partner ingestion surface whose producer contract is not yet compatible. HTTP data routes require the configured API-key header. /healthz, /openapi.json, and non-production /docs and /docs/oauth2-redirect are exempt. Principal-bearing data routes can also rely on trusted identity headers when verified authentication is enabled. Infrastructure must strip caller-supplied identity headers and inject trusted claims before traffic reaches the API. Browser clients must not embed a shared API key or allow users to forge trusted identity; use a same-origin backend-for-frontend or gateway injection layer.

The HTTP/SSE surface covers health and discovery, query/search, conversation memory, ingestion, document lifecycle, and answer streaming. The partner event code covers Kafka/DMS ingestion handoff and stage-status publication once its contract is reconciled. Treat the API reference as authoritative for every HTTP field, endpoint, stream event, partner event, and error case.

Frontend responsibility​

Frontend clients own presentation, user interaction, upload forms, polling or stream consumption, and safe display of citations and errors. The backend owns retrieval, ingestion, memory persistence, citation construction, policy guarding, and model orchestration. Trusted identity headers and RBAC/ABAC retrieval enforcement are configuration-gated. When verified authentication is off, retrieval access filtering is allow-all.

Clients should discover the current OpenAPI document from /openapi.json in the target environment. Swagger UI is available at /docs outside production for interactive exploration.

Entitlements and roadmap​

Today, OCR, embeddings, retrieval, memory, and generation are wired together for the Aceh RAG + OCR platform. They are not exposed as independently selectable API products, and one application cannot currently subscribe only to OCR while another subscribes to OCR plus retrieval and generation.

A future service-gateway entitlement layer can add per-application identity, à-la-carte capability access, quotas, usage metering, and uniform governance over the same API-first foundation. On Huawei Cloud, that would extend the APIG gateway already in the stack rather than changing the frontend integration contract described in the API reference.