API reference

Every endpoint except /healthz and /readyz requires a bearer token issued by Keycloak. The API validates tokens; it never issues them and never stores a password.

TOKEN=$(curl -s -X POST \
  "$KEYCLOAK/realms/dek-hub/protocol/openid-connect/token" \
  -d grant_type=password -d client_id=dek-hub-api \
  -d username=<user> -d password=<password> | jq -r .access_token)

curl -H "Authorization: Bearer $TOKEN" "$API/api/v1/indicators"

Roles come from the token’s realm roles. admin is a superuser: it may call every endpoint, whatever role the endpoint names.

Pagination. Every list endpoint takes ?limit=&offset= and returns {"items": [...], "meta": {...}}. limit is clamped at 200 rather than rejected — walk pages with next_offset until it is null.

Filtering. Each resource accepts a fixed, typed set of filters. No endpoint takes a column or table name from the caller.

Partial updates. PATCH leaves out what you do not send. An explicit null clears a nullable field; omitting the key leaves it untouched. Unknown fields are rejected with 422 rather than ignored, so a typo is visible.

Errors are always RFC 9457 application/problem+json, never a bare string. Branch on the stable type URI rather than on the prose in title or detail.

Documents are checksum-verified. A file’s SHA-256 is recorded on upload and re-checked on download, so a corrupted or substituted file fails rather than being served.

Search degrades, it does not fail. When the index is unavailable the API answers from a narrower query and sets degraded: true on the response. A client that ignores that flag will under-report the collection.

Interactive reference

The interactive reference, with every endpoint and schema, is served by the API itself at /docs, and the OpenAPI document at /openapi.json.