# API Design

## Principes

- Prefix `/v1` voor productresources; health blijft onversioned.
- JSON en RFC 9457-style problem details voor fouten.
- Opaque UUID identifiers.
- Idempotency-Key vereist voor create/upload/sync requests die clients kunnen herhalen.
- Cursorpagination, stabiele sortering en begrensde page sizes.
- Timestamps in RFC 3339 UTC.
- Geen raw SQL, Qdrantfilter, providerprompt of onbeperkte modelparameters in publieke requests.

## Kernresources

- workspaces/applications/service accounts;
- knowledge spaces en grants;
- sources/sync runs;
- documents/versions;
- jobs;
- search/context/answers;
- citations/feedback;
- profiles/evaluation runs;
- audit events.

## Async operations

Upload, sync, reindex en evaluatie leveren `202 Accepted` met job ID en status URL. Jobstatus bevat typed state, progress en sanitized failure.

## Streaming

Answers kunnen Server-Sent Events gebruiken met events `metadata`, `delta`, `citation`, `complete`, `error`. Citations en answerabilitymetadata worden vóór of uiterlijk met complete geleverd.