Chat completion for Cursor
POST/v1/cursor/chat/completions
The chat route for Cursor. Set https://<gateway>/v1/cursor as
Cursor's "Override OpenAI Base URL". The request runs the same checks,
metering and audit as /v1/chat/completions. A key with scopes needs
completions:write.
The body can be a Chat Completions body or a Responses API body:
- A body with a non-empty
messagesarray is a Chat Completions body. Its tools are put in the Chat Completions shape first: a flatfunctionorcustomtool is nested, and a flat grammar is wrapped asgrammar: {syntax, definition}. - Any other body is a Responses API body. Its tools are put in the
flat Responses shape, the empty
messagesandstream_optionsare removed, and it is read as/v1/responsesreads a body. OpenAI and Azure OpenAI are sent it as it came; another provider gets the translation.
Cursor's model-picker variants are read off the model name: a trailing
-fast is removed, and a trailing -thinking-minimal, -low,
-medium, -high or -xhigh is removed and becomes the reasoning
effort. Only this route reads model names this way.
The answer is always in the Chat Completions shape, plain or streamed.
stream_options.include_usage asks for the usage chunk on both body
kinds.
Request
Responses
- 200
- 400
- 401
- 402
- 403
- 413
- 422
- 429
- 500
- 502
- 503
Chat completion, or an SSE stream of chunks ending with data:[DONE] when stream is true
The request was refused before dispatch: an invalid body (invalid_request), no provider for the model (no_provider, no_capable_provider), an unsupported field or capability (unsupported_capability, unsupported_response_format), a request too large for the model's context window (context_window_exceeded), a PII BLOCK action (pii_detected), or the provider refused the request itself (provider_rejected_request).
No key was sent (api_key_required), or the key is unknown (invalid_api_key), revoked (api_key_revoked) or expired (api_key_expired).
A hard budget cap is exhausted (budget_cap_hard), the call would cost more than the per-call ceiling (per_call_cost_exceeded), or, without a licence, the monthly call band is used up (license_token_cap_exceeded, type token_cap_exceeded).
The key's nonempty scope list does not cover the operation (api_key_scope; chat, Responses, completions and the Cursor route need completions:write, embeddings need embeddings:write); a policy rule (policy_denied), guardrail (guardrail_blocked, hallucination_detected, grounding_unavailable), IP rule (ip_access_denied) or data-residency rule (data_residency_violation) refused the call; PII tokenization or redaction was needed but unavailable (pii_tokenize_unavailable, pii_redact_unavailable); or the workspace is suspended (workspace_suspended), over its cap (workspace_cap_exceeded), or must use its own provider credential (workspace_credential_required). A PII BLOCK is 400 pii_detected instead.
The input is over a configured guardrail size limit (input_too_large), such as messages per request, message length or input tokens.
The model's answer did not match the configured output schema (schema_validation_failed).
The key's rate limit is reached (rate_limit_exceeded, with a Retry-After header), priority admission control throttled the request (priority_throttled), or the provider is rate limiting the call (provider_rate_limited, with Retry-After when the provider gave one).
Response Headers
Seconds to wait before retrying, when known.
A configured guardrail plugin failed (guardrail_plugin_error), or the key has no id in the gateway's configuration (api_key_misconfigured).
Every configured provider on the route (and every fallback) has failed.
The provider's circuit breaker is open (provider_circuit_open), no fallback provider can serve what the request needs (failover_capability_mismatch), or the workspace's own provider credential cannot be read (workspace_credential_unavailable).