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 messages array is a Chat Completions body. Its tools are put in the Chat Completions shape first: a flat function or custom tool is nested, and a flat grammar is wrapped as grammar: {syntax, definition}.
• Any other body is a Responses API body. Its tools are put in the flat Responses shape, the empty messages and stream_options are removed, and it is read as /v1/responses reads 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 then a trailing -thinking-<effort> is removed and the effort becomes the reasoning effort. The effort is one of minimal, low, medium, high or xhigh, so the full suffix is -thinking-minimal, -thinking-low, -thinking-medium, -thinking-high or -thinking-xhigh. A bare -low or -high is not read. 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

Chat completion, or an SSE stream of chunks ending with data:[DONE] when stream is true

400

The request was refused before dispatch: a body that is not valid JSON or has a field of the wrong type (invalid_json), a body that fails validation (validation_error, with the field names in param), 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).

401

No key was sent (api_key_required), or the key is unknown (invalid_api_key), revoked (api_key_revoked) or expired (api_key_expired).

402

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).

403

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, in upper case, Enterprise platform) 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) or must use its own provider credential (workspace_credential_required). A PII BLOCK is 400 pii_detected instead.

413

The input is over a configured guardrail size limit (input_too_large), such as messages per request, message length or input tokens.

422

The model's answer did not match the configured output schema (schema_validation_failed).

429

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

Retry-After

Seconds to wait before retrying, when known.

500

A configured guardrail plugin failed (guardrail_plugin_error), the key has no id in the gateway's configuration (api_key_misconfigured), or an unexpected error happened in the gateway (internal_error, type gateway_error).

502

Every configured provider on the route (and every fallback) has failed.

503

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). On the Enterprise platform, a gateway that cannot store audit events refuses every call with audit_store_full (type service_unavailable) and a Retry-After: 30 header until it can.