RAGcore-Public/docs/06_API/API_DESIGN.md

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.