Create a chat completion
POST/api/v1/chat/completions
OpenAI Chat Completions-compatible endpoint. Mirrors OpenAI's POST /v1/chat/completions path so an OpenAI SDK can target it by base URL alone.
Names exactly one target. With ai_provider_id the completion is stateless: the provider's secret is decrypted and the appropriate Vercel AI SDK provider is called, with no server-side model fallback. With chat_id the stored chat supplies the provider (or the project's default_model_route_id), model and instructions.
System content travels only in instructions — a role: "system" entry in messages is refused with 400 SYSTEM_MESSAGE_NOT_ALLOWED. With chat_id, a request instructions replaces the chat's stored one for this call only; the stored value applies when the request carries none, and the two are never merged.
Messages may use document_id instead of content with either target. Chats hold no message history — send the full messages array every time.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 502
Chat completion result (JSON or SSE stream)
Bad Request — messages is missing or empty; a role: "system" entry appears in messages; neither ai_provider_id nor chat_id was given, or both were; or chat_id names a chat that does not exist.
Unauthorized — missing or invalid bearer token
Forbidden — the caller lacks chats:CreateChatCompletion on the project the call belongs to: the chat's project for chat_id, the AI provider's project for ai_provider_id.
AI provider not found
Upstream AI provider error (AI_PROVIDER_ERROR) — the provider rejected the completion (an unavailable model, a refused credential) or could not be reached. The message names the provider's own status and message, so an unavailable model is distinguishable from a fault in the runtime itself. Streaming requests report this in a terminal SSE frame instead, since their status line is already on the wire.