Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

docs/06_API/API_DESIGN.md

@@ -0,0 +1,31 @@
+# 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.