Use your company API address
Retvest client applications connect to the API address supplied for their Deploy environment. retvest.com serves this website; it is not a shared public model endpoint. Match API documentation to the version delivered for your pilot.
Authentication follows the operation
- Interactive access: permitted user sessions and the organisation’s sign-in requirements.
- Automation: scoped Retvest API keys on operations that accept them.
- Work Run review: session-owned administrative operations with the required authority.
Do not substitute a bearer API key for a session-only route. Supply credentials through the SDK’s designated fields and retain the server’s access boundaries.
Document questions and streaming
The documented query paths are POST /rag/query and POST /rag/query/stream. The streaming response uses text/event-stream, with source/citation events, answer tokens and a terminal success or error event. Use the precise event names and order in your delivered contract; the client and server versions must agree. Source information precedes answer tokens. Treat interruption or an error event as an incomplete task.
Represent stream state in your application
- Waiting
- The request has started but a complete answer is not available.
- Receiving
- Source information and answer fragments may be displayed as partial work.
- Complete
- The contract’s success terminal event closes the stream.
- Incomplete or failed
- An error, malformed event or disconnect prevents a complete result. Keep the partial state visible instead of presenting it as success.
A successful HTTP response alone does not establish that a streamed answer completed. Parse complete SSE frames and let the matching client enforce its event protocol.
Work Run correction paths
The source reference defines the following correction interface. These are contract examples, not a public API service; the deployment’s matching schema controls request fields and access.
GET /admin/work-runs/{work_run_id}/corrections
Read correction history.
GET /admin/work-runs/{work_run_id}/corrections/audit
Read permitted correction audit metadata.
POST /admin/work-runs/{work_run_id}/corrections
Submit a correction for review.
Protect review decisions
Apply, reject and retry-request actions use expected-version and idempotency information. A stale version requires a fresh read and an informed decision. Do not automatically repeat an ambiguous review write.
Separate transport failures from business outcomes
An authentication or permission failure needs the correct access, not a blind retry. A stale review version needs a fresh read. A rate or temporary service limit may include a retry hint. A timeout after submitting a write requires reconciliation because the server may have accepted it.
Use the typed errors and public problem fields from the delivered client. Keep the user-facing explanation separate from diagnostic metadata, and avoid returning a raw server body into a public page.
Keep useful support metadata
Record the request ID, status, public error code and applicable retry hint. Avoid sending credentials, raw documents, prompts or generated answers in a support report. The full matching schema and artifact versions belong in your pilot’s developer handover.