API reference: overview

The DataFlow AI Platform exposes a microservice REST API fronted by a single API Gateway. Every client request enters through the gateway, which authenticates the JWT, applies per-route rate limiting, attaches a correlation ID, and transparently proxies the call to the backend service that owns the route prefix.

Base URLs

All client traffic should target the gateway. Backend services are also reachable directly in local development for debugging.

Every backend service also publishes the production server https://api.dataflow.polkomtel.pl/api/v1 — that is, the path you reach through the gateway. Every functional endpoint is prefixed with /api/v1.

Services and ports

The platform is built from five OpenAPI-specified services plus three proxied-only services. All specs declare openapi: 3.1.0 and info.version: 1.0.0.

Gateway routing

The gateway maps each route prefix to a backend service. Most gateway paths are $ref-mounted re-exports of the backend specs; the gateway also defines six first-class operations of its own (health, copilot, migration, CDC).

Gateway-owned operations

These six operations are defined directly by the gateway rather than re-exported from a backend spec.

// GET /health  →  200 OK
{
  "status": "UP",
  "gateway": "dataflow-api-gateway"
}

Versioning

The platform uses path-based versioning. The current and only version is v1, embedded in every functional route as /api/v1/....

• All five OpenAPI specs declare info.version: 1.0.0.
• The gateway GET /health endpoint is unversioned — it carries no /api/v1 prefix.
• A new major version, if introduced, would appear as a new path segment (/api/v2/...); v1 routes remain stable.

Authentication

The platform authenticates with Keycloak OIDC + JWT Bearer tokens.

• Security schemes. The gateway declares two schemes — oidcAuth (openIdConnect) and bearerAuth (http / bearer / JWT). Backend services declare only bearerAuth.
• OIDC discovery: https://auth.dataflow.polkomtel.pl/realms/dataflow/.well-known/openid-configuration
• Realm: dataflow
• Client IDs: dataflow-ui (public, Authorization Code + PKCE) and dataflow-api (confidential, Client Credentials).
• Header: Authorization: Bearer <token>

Required JWT claims

Every authenticated request must carry a token with the following claims.

GET /api/v1/pipelines HTTP/1.1
Host: api.dataflow.polkomtel.pl
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...

Exceptions

• GET /health (gateway) is unauthenticated — its OpenAPI security is [].
• Webhook endpoints (orchestrator trigger, Git webhooks) authenticate with HMAC signature headers — X-Webhook-Signature, X-Hub-Signature-256, X-Gitlab-Token — instead of a JWT.

Error format

Every service returns a uniform ErrorResponse body on failure.

{
  "error": "NOT_FOUND",
  "message": "Pipeline not found: f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "timestamp": "2025-12-15T14:30:00Z"
}

HTTP status codes

Gateway-specific errors

The gateway extends ErrorResponse for its own failure modes.

// 429 Too Many Requests
{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded for /api/v1/pipelines",
  "retryAfter": 42,
  "timestamp": "2025-12-15T14:30:00Z"
}

Rate limiting and correlation headers

The gateway applies these headers to every proxied response.

Rate limits are enforced per route. When the window is exhausted the gateway responds 429 with a retryAfter value (seconds). Always log the X-Request-Id on the client side — it is the single correlation key for support and tracing across all services.

Pagination

There is no platform-wide pagination contract. Three distinct patterns are used across the services; there is no cursor-based pagination anywhere.

1. Page/size offset pagination

Used by Admin (/admin/users, /admin/audit) and the GDPR DSAR list. Query params page (default 0) and size (default 20). The response wraps the items with total, page, and size.

// GET /api/v1/admin/users?page=0&size=20  →  200 OK
{
  "items": [ /* UserResponse[] */ ],
  "total": 134,
  "page": 0,
  "size": 20
}

2. limit-capped lists

Most "list / history / recent" endpoints accept a limit query param (defaults vary — 10, 50, 100). There is no cursor; the response is a bare array.

GET /api/v1/quality/results?pipelineId=...&limit=50

3. Time-window filters

Alert and event history endpoints filter by time rather than page number, using sinceSeconds, from, and to.

GET /api/v1/monitor/alerts/history?sinceSeconds=86400

Endpoint group index

The full API is documented across three reference pages. Use this index to find the right group.

Endpoint counts

Proxied-only services (copilot, migration, CDC, connector-sdk) are surfaced through the gateway but are not formally specified beyond the six gateway stub operations.