openapi: 3.0.3 info: title: Reflection API version: 0.1.0 description: |- Reflection's hosted inference API. The `/openai/v1` routes are OpenAI-compatible: chat completions and the models that serve them. Responses, except CORS preflights, include an `x-request-id` the server assigns independently of client-supplied IDs. Once a request is authenticated and admitted for rate limiting, its response, including an error response, carries `x-ratelimit-` headers reporting the organization's remaining request capacity, and for chat completions its token capacity. Headers ending in `-day` report the UTC calendar day; the others report a per-minute limit. Token capacity counts the input estimated at admission, not the completion's final usage. Reset durations measure full replenishment without further traffic, not when a rejected request may be retried; use `Retry-After` for that. The headers are omitted when capacity cannot be reported. Every response to an authenticated request, including an error response, carries `reflection-data-retention`, the data retention the request was served under: `zero` when none of its prompt, response or other content is stored once it completes, though in-memory caches may hold it until they evict it, `standard` when its content may be kept under standard retention, or `contributor` when its content may be kept as under standard retention and may also be used to train Reflection's models, under contributor terms the organization accepted. A request whose retention cannot be determined is reported as `zero`. More values may be added; read one you do not know as promising nothing about what is kept. servers: - url: https://api.reflection.ai description: The Reflection API. tags: - name: Models description: List and retrieve the models you can use with the API. - name: Chat description: Generate a model response for a conversation. security: - apiKey: [] - playgroundCredential: [] paths: /openai/v1/models: get: operationId: listModels tags: - Models summary: List models description: Lists the models available to you, with basic information about each one such as its limits and reasoning settings. The list can differ between organizations and plans. responses: '200': description: The available models. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' content: application/json: schema: $ref: '#/components/schemas/ModelList' examples: Available models: summary: Available models value: object: list data: - id: Beam-1.0-501B-A23B object: model created: 1791158400 owned_by: reflection shutdown_date: null context_length: 1048576 max_output_tokens: 131072 default_parameters: max_tokens: 32768 reasoning: supported_efforts: - max - xhigh - high - medium - low default_effort: max mandatory: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' /openai/v1/models/{model}: get: operationId: retrieveModel tags: - Models summary: Retrieve a model description: Retrieves one model by its identifier, with the same information the models list returns for it. parameters: - in: path name: model required: true description: The identifier of the model, as returned in the models list. An identifier that contains `/` may be sent as written. schema: type: string example: Beam-1.0-501B-A23B responses: '200': description: The model. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' content: application/json: schema: $ref: '#/components/schemas/Model' examples: Model: summary: Model value: id: Beam-1.0-501B-A23B object: model created: 1791158400 owned_by: reflection shutdown_date: null context_length: 1048576 max_output_tokens: 131072 default_parameters: max_tokens: 32768 reasoning: supported_efforts: - max - xhigh - high - medium - low default_effort: max mandatory: true '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/ModelNotFound' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' /openai/v1/chat/completions: post: operationId: generateChatCompletion tags: - Chat summary: Create a chat completion description: |- Creates a model response for the given chat conversation. Learn more in the [text generation guide](/text-generation). Returns a chat completion object or, if the request is streamed, a sequence of server-sent events; chat completion chunks arrive as `data:` lines, and a completed stream ends with `data: [DONE]`. x-mint: content: | ## Streaming responses With `stream: true`, the response is a sequence of server-sent events instead of one JSON object. Each event is a `data:` line holding a `chat.completion.chunk`. Read the generated text from `choices[0].delta.content` on each chunk, not from `message`, and concatenate the pieces in order. The final chunk for each choice carries a `finish_reason`. With `stream_options.include_usage`, one more chunk with empty `choices` reports `usage` for the whole request. A completed stream ends with `data: [DONE]`. ## Errors during streaming The HTTP status is sent before generation starts, so a failure after that cannot change it. Instead, an event whose data is an `error` object, in the same shape as an error response body, reports the failure. The request may be retried. A stream that ends without `data: [DONE]`, with or without an error event, did not complete: treat the text received as partial. Lines that begin with `:`, such as `: keepalive`, are comments that keep an idle connection open; ignore them. x-codeSamples: - lang: python label: Python source: | import os from openai import OpenAI client = OpenAI( base_url="https://api.reflection.ai/openai/v1", api_key=os.environ["REFLECTION_API_KEY"], ) completion = client.chat.completions.create( model="Beam-1.0-501B-A23B", messages=[ {"role": "system", "content": "Answer in one sentence."}, {"role": "user", "content": "Why is the sky blue?"}, ], ) print(completion.choices[0].message.content) - lang: python label: Python (streaming) source: | import os from openai import OpenAI client = OpenAI( base_url="https://api.reflection.ai/openai/v1", api_key=os.environ["REFLECTION_API_KEY"], ) stream = client.chat.completions.create( model="Beam-1.0-501B-A23B", messages=[ {"role": "system", "content": "Answer in one sentence."}, {"role": "user", "content": "Why is the sky blue?"}, ], stream=True, stream_options={"include_usage": True}, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="", flush=True) if chunk.usage: print(f"\n{chunk.usage.total_tokens} tokens") - lang: typescript label: TypeScript source: | import OpenAI from "openai"; const client = new OpenAI({ baseURL: "https://api.reflection.ai/openai/v1", apiKey: process.env.REFLECTION_API_KEY, }); const completion = await client.chat.completions.create({ model: "Beam-1.0-501B-A23B", messages: [ { role: "system", content: "Answer in one sentence." }, { role: "user", content: "Why is the sky blue?" }, ], }); console.log(completion.choices[0].message.content); - lang: bash label: cURL (streaming) source: | curl -N https://api.reflection.ai/openai/v1/chat/completions \ -H "Authorization: Bearer $REFLECTION_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "Beam-1.0-501B-A23B", "messages": [ {"role": "system", "content": "Answer in one sentence."}, {"role": "user", "content": "Why is the sky blue?"} ], "stream": true, "stream_options": {"include_usage": true} }' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ChatCompletionRequest' examples: Basic request: summary: Basic request value: model: Beam-1.0-501B-A23B messages: - role: system content: Answer in one sentence. - role: user content: Why is the sky blue? Streaming request: summary: Streaming request value: model: Beam-1.0-501B-A23B messages: - role: system content: Answer in one sentence. - role: user content: Why is the sky blue? stream: true stream_options: include_usage: true Function calling: summary: Function calling value: model: Beam-1.0-501B-A23B messages: - role: user content: What's the weather in Paris right now? tools: - type: function function: name: get_weather description: Get the current weather for a city. parameters: type: object properties: city: type: string description: The city name. required: - city additionalProperties: false tool_choice: auto Function calling, returning the result: summary: Function calling, returning the result value: model: Beam-1.0-501B-A23B messages: - role: user content: What's the weather in Paris right now? - role: assistant content: null reasoning_content: The user wants the current weather in Paris, so call get_weather. tool_calls: - id: call-7f3a9c2e-5b1d-4e8a-9c36-2f0d8b4a71e5 type: function function: name: get_weather arguments: '{"city": "Paris"}' - role: tool tool_call_id: call-7f3a9c2e-5b1d-4e8a-9c36-2f0d8b4a71e5 content: '{"temperature_c": 18, "conditions": "light rain"}' tools: - type: function function: name: get_weather description: Get the current weather for a city. parameters: type: object properties: city: type: string description: The city name. required: - city additionalProperties: false Structured output: summary: Structured output value: model: Beam-1.0-501B-A23B messages: - role: user content: 'Extract the event: Team offsite on March 3 in Lisbon for the platform group.' response_format: type: json_schema json_schema: name: event strict: true schema: type: object properties: name: type: string date: type: string city: type: string required: - name - date - city additionalProperties: false responses: '200': description: A chat completion, or a stream of chat completion chunks when `stream` is true. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ChatCompletionResponse' examples: Chat completion: summary: Chat completion value: id: chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f object: chat.completion created: 1791198000 model: Beam-1.0-501B-A23B choices: - index: 0 message: role: assistant content: Air molecules scatter short blue wavelengths of sunlight far more than longer red ones, so blue light reaches your eyes from every part of the sky. refusal: null reasoning_content: The user wants a one-sentence explanation of Rayleigh scattering. logprobs: null finish_reason: stop usage: prompt_tokens: 23 completion_tokens: 45 total_tokens: 68 completion_tokens_details: reasoning_tokens: 14 Function call: summary: Function call value: id: chatcmpl-9b2e7d41-c0a3-4f6e-8a15-d3b7c6f02e19 object: chat.completion created: 1791198060 model: Beam-1.0-501B-A23B choices: - index: 0 message: role: assistant content: null refusal: null reasoning_content: The user wants the current weather in Paris, so call get_weather. tool_calls: - id: call-7f3a9c2e-5b1d-4e8a-9c36-2f0d8b4a71e5 type: function function: name: get_weather arguments: '{"city": "Paris"}' logprobs: null finish_reason: tool_calls usage: prompt_tokens: 96 completion_tokens: 35 total_tokens: 131 completion_tokens_details: reasoning_tokens: 14 Structured output: summary: Structured output value: id: chatcmpl-2d6f0a8b-3e91-4c7b-9f54-a1e8c3d7b260 object: chat.completion created: 1791198120 model: Beam-1.0-501B-A23B choices: - index: 0 message: role: assistant content: '{"name": "Team offsite", "date": "March 3", "city": "Lisbon"}' refusal: null logprobs: null finish_reason: stop usage: prompt_tokens: 41 completion_tokens: 19 total_tokens: 60 text/event-stream: schema: $ref: '#/components/schemas/ChatCompletionChunk' examples: Streaming: summary: A streamed response value: |+ data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}],"created":1791198000,"model":"Beam-1.0-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"wGMmHWX"} data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"reasoning_content":"The user wants a one-sentence explanation of Rayleigh scattering."},"finish_reason":null}],"created":1791198000,"model":"Beam-1.0-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"lC"} data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"content":"Air molecules scatter short blue wavelengths of sunlight far more"},"finish_reason":null}],"created":1791198000,"model":"Beam-1.0-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"cVmEhIa5zitB"} data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"content":" than longer red ones, so blue light reaches your eyes from every"},"finish_reason":null}],"created":1791198000,"model":"Beam-1.0-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"6WhBZTNBLlol"} data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{"content":" part of the sky."},"finish_reason":null}],"created":1791198000,"model":"Beam-1.0-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"cGv4yGc4Dx-S3LMCyfoevWzBWsxtzk7cCIthcSCHxpJ4yLTophhyxeC6O2Fa"} data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"created":1791198000,"model":"Beam-1.0-501B-A23B","object":"chat.completion.chunk","usage":null,"obfuscation":"kxtEv0FWmRsjv6IHiQoowTE2U-ZgKvc_EmkfM2CwbV3xz_mxCobC3dFUgFzknbzBzZunVlqbQG1jCUa4YFxVcRt"} data: {"id":"chatcmpl-4cfa1b54-d28b-4be5-b095-5c6c52b2d27f","choices":[],"created":1791198000,"model":"Beam-1.0-501B-A23B","object":"chat.completion.chunk","usage":{"prompt_tokens":23,"completion_tokens":45,"total_tokens":68,"completion_tokens_details":{"reasoning_tokens":14}},"obfuscation":"QkHVHPHgk3xZMnPQqH_DnJv"} data: [DONE] '400': description: The request is invalid, and `error.param` names the parameter at fault. Correct the request before retrying. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Value out of range: summary: Value out of range value: error: message: 'Invalid value for ''temperature'': number must be at most 2.' type: invalid_request_error param: temperature code: invalid_value Unrecognized parameter: summary: Unrecognized parameter value: error: message: 'Unrecognized request argument supplied: ignore_eos.' type: invalid_request_error param: ignore_eos code: unsupported_parameter Context window exceeded: summary: Context window exceeded value: error: message: This model's maximum context length is 1048576 tokens. However, your messages resulted in 1048600 tokens. Please reduce the length of the messages. type: invalid_request_error param: messages code: context_length_exceeded Prompt and output limit exceed the context window: summary: Prompt and output limit exceed the context window value: error: message: This model configuration accepts at most 1048576 combined input and output tokens. However, your request has 49 input tokens and asks for 1048576 output tokens (1048625 tokens total). Please reduce the input length or requested output length. type: invalid_request_error param: messages code: context_length_exceeded '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/ChatForbidden' '404': $ref: '#/components/responses/ChatModelNotFound' '409': $ref: '#/components/responses/ChatBillingConflict' '413': description: The request body is too large. Reduce its size before retrying. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Request body too large: summary: Request body too large value: error: message: The request body exceeds the maximum size. type: invalid_request_error param: null code: request_too_large '415': description: The request body is not declared as JSON. Set the `Content-Type` header to `application/json` before retrying. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Unsupported media type: summary: Unsupported media type value: error: message: 'Unsupported Content-Type. Send the request body as JSON with the header Content-Type: application/json.' type: invalid_request_error param: null code: unsupported_media_type '429': $ref: '#/components/responses/ChatTooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '502': description: The inference service failed to produce a response. The request may be retried. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Inference service unavailable: summary: Inference service unavailable value: error: message: The inference service is temporarily unavailable type: upstream_unavailable_error param: null code: null Inference service credentials rejected: summary: Inference service credentials rejected value: error: message: The inference service rejected the platform's credentials. Your API key or session was not the cause. type: upstream_unavailable_error param: null code: upstream_credentials_rejected '503': $ref: '#/components/responses/ChatServiceUnavailable' components: securitySchemes: playgroundCredential: type: http scheme: bearer bearerFormat: Reflection Playground credential description: A short-lived, project-scoped credential that the Reflection Playground issues to itself while you use it. It is not meant for direct use; send an API key instead. apiKey: type: http scheme: bearer bearerFormat: Reflection API key description: A Reflection API key, sent in the `Authorization` header as `Bearer `. Create a key for your project from the [Reflection platform](https://platform.reflection.ai/api-keys). headers: x-request-id: description: A unique identifier the server assigns to this request. Include it when contacting support. A request ID you send is not reused. schema: type: string format: uuid example: 7c9e6679-7425-40de-944b-e07fc1f90ae7 reflection-data-retention: description: 'The data retention the request was served under: `standard`, `zero` or `contributor`.' schema: type: string enum: - standard - zero - contributor example: zero x-ratelimit-limit-requests: description: The most requests the organization may use per minute. schema: type: integer format: int64 minimum: 0 example: 600 x-ratelimit-remaining-requests: description: The requests left in the per-minute capacity, rounded down. Reflects this request when it was admitted; a rejected request uses none. schema: type: integer format: int64 minimum: 0 example: 599 x-ratelimit-reset-requests: description: The time until the per-minute capacity is fully replenished if no further requests are used, as seconds with up to millisecond precision and an `s` suffix. Not a retry delay; see `Retry-After`. schema: type: string example: 0.1s x-ratelimit-limit-requests-day: description: The most requests the organization may use per UTC calendar day. schema: type: integer format: int64 minimum: 0 example: 100000 x-ratelimit-remaining-requests-day: description: The requests left in today's UTC calendar-day capacity, rounded down. Reflects this request when it was admitted; a rejected request uses none. schema: type: integer format: int64 minimum: 0 example: 99412 x-ratelimit-reset-requests-day: description: The time until the next UTC midnight, when the daily count resets, as seconds with up to millisecond precision and an `s` suffix. Not a retry delay; see `Retry-After`. schema: type: string example: 43200s x-ratelimit-limit-tokens: description: The most tokens the organization may use per minute. Sent only on chat completions. schema: type: integer format: int64 minimum: 0 example: 2000000 x-ratelimit-remaining-tokens: description: The tokens left in the per-minute capacity, rounded down. Reflects this request when it was admitted; a rejected request uses none. Counts the input tokens estimated at admission, not final usage. Sent only on chat completions. schema: type: integer format: int64 minimum: 0 example: 1987650 x-ratelimit-reset-tokens: description: The time until the per-minute capacity is fully replenished if no further tokens are used, as seconds with up to millisecond precision and an `s` suffix. Not a retry delay; see `Retry-After`. Sent only on chat completions. schema: type: string example: 0.371s x-ratelimit-limit-tokens-day: description: The most tokens the organization may use per UTC calendar day. Sent only on chat completions. schema: type: integer format: int64 minimum: 0 example: 200000000 x-ratelimit-remaining-tokens-day: description: The tokens left in today's UTC calendar-day capacity, rounded down. Reflects this request when it was admitted; a rejected request uses none. Counts the input tokens estimated at admission, not final usage. Sent only on chat completions. schema: type: integer format: int64 minimum: 0 example: 187340215 x-ratelimit-reset-tokens-day: description: The time until the next UTC midnight, when the daily count resets, as seconds with up to millisecond precision and an `s` suffix. Not a retry delay; see `Retry-After`. Sent only on chat completions. schema: type: string example: 43200s examples: NotOrganizationMember: summary: Not an organization member value: error: message: You are not an active member of the credential's organization. type: permission_error param: null code: organization_membership_required PlatformAccessRequired: summary: Waiting for platform access value: error: message: Your account is waiting for platform access. type: permission_error param: null code: platform_access_required RegistrationUnfinished: summary: Registration unfinished value: error: message: Complete registration before using the Playground. type: permission_error param: null code: onboarding_pending CredentialNotInPlan: summary: Credential not in plan value: error: message: Your organization's plan does not include access with this kind of credential. type: permission_error param: null code: plan_access_denied AccountRestricted: summary: Account restricted value: error: message: This account is restricted from using the API. type: permission_error param: null code: account_restricted UnknownModel: summary: Unknown model value: error: message: The model [reflection-large] you requested is unavailable. type: invalid_request_error param: model code: model_not_found RequestRateLimit: summary: Request rate limit value: error: message: 'Your organization has reached its request limit. Retry after the indicated delay. View your usage and billing here: https://platform.reflection.ai/billing' type: rate_limit_error param: null code: rate_limit_exceeded TokenRateLimit: summary: Token rate limit value: error: message: 'Your organization has reached its token limit. Retry after the indicated delay. View your usage and billing here: https://platform.reflection.ai/billing' type: rate_limit_error param: null code: rate_limit_exceeded DailyRequestLimit: summary: Daily request limit value: error: message: 'Your organization has reached its daily request limit. It resets at 00:00 UTC. View your usage and billing here: https://platform.reflection.ai/billing' type: rate_limit_error param: null code: rate_limit_exceeded DailyTokenLimit: summary: Daily token limit value: error: message: 'Your organization has reached its daily token limit. It resets at 00:00 UTC. View your usage and billing here: https://platform.reflection.ai/billing' type: rate_limit_error param: null code: rate_limit_exceeded RateLimitingUnavailable: summary: Rate limiting unavailable value: error: message: Rate limiting is temporarily unavailable. Retry the request. type: api_error param: null code: rate_limit_unavailable ModelAvailabilityUnavailable: summary: Model availability check unavailable value: error: message: Model availability is temporarily unavailable. type: api_error param: null code: model_availability_unavailable InferenceCapacityExhausted: summary: Inference capacity exhausted value: error: message: Inference capacity is temporarily unavailable. Retry after the indicated delay. type: api_error param: null code: infrastructure_rate_limit_exceeded responses: Unauthorized: description: The credential is missing, malformed, or not valid. Correct the credential before retrying. headers: x-request-id: $ref: '#/components/headers/x-request-id' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Invalid API key: summary: Invalid API key value: error: message: Incorrect API key provided. The key may have been revoked or expired. type: authentication_error param: null code: invalid_api_key Missing credential: summary: Missing credential value: error: message: Provide an API key or Playground credential in the Authorization header. type: authentication_error param: null code: missing_credentials Malformed Authorization header: summary: Malformed Authorization header value: error: message: The Authorization header must be of the form 'Bearer '. type: authentication_error param: null code: invalid_authorization_header Expired Playground credential: summary: Expired Playground credential value: error: message: The Playground credential is unknown or expired. Retry from the Playground. type: authentication_error param: null code: invalid_playground_credential Forbidden: description: 'The credential is valid, but the request is not allowed: the account awaits platform access or has not finished registration, the caller is not an active organization member, an access restriction applies, or the plan excludes this kind of credential. Retry only after the cause is resolved.' headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Credential not in plan: $ref: '#/components/examples/CredentialNotInPlan' Waiting for platform access: $ref: '#/components/examples/PlatformAccessRequired' Registration unfinished: $ref: '#/components/examples/RegistrationUnfinished' Not an organization member: $ref: '#/components/examples/NotOrganizationMember' Account restricted: $ref: '#/components/examples/AccountRestricted' ChatForbidden: description: 'The credential is valid, but the request is not allowed: the account awaits platform access or has not finished registration, the caller is not an active organization member, an access restriction or suspension applies, the plan excludes this kind of credential, or the organization must verify a card before using API keys. Retry only after the cause is resolved.' headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Card verification required: summary: Card verification required value: error: message: Verify a credit card in Billing before using API keys. type: permission_error param: null code: payment_method_required Credential not in plan: $ref: '#/components/examples/CredentialNotInPlan' Waiting for platform access: $ref: '#/components/examples/PlatformAccessRequired' Registration unfinished: $ref: '#/components/examples/RegistrationUnfinished' Not an organization member: $ref: '#/components/examples/NotOrganizationMember' Account restricted: $ref: '#/components/examples/AccountRestricted' API access suspended: summary: API access suspended value: error: message: API access is suspended for this organization. Contact support. type: permission_error param: null code: billing_access_suspended PaymentRequired: description: 'Your organization has no credit left: `insufficient_credits` means it has no remaining credits, and `prepaid_balance_exhausted` means its prepaid balance is used up. Retry only once credit is available, such as after adding credit or topping up in [Billing](https://platform.reflection.ai/billing).' headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: No remaining credits: summary: No remaining credits value: error: message: API access is inactive because this organization has no remaining credits. type: permission_error param: null code: insufficient_credits Prepaid balance used up: summary: Prepaid balance used up value: error: message: This organization's prepaid balance is used up. Top up in Billing to resume API requests. type: permission_error param: null code: prepaid_balance_exhausted ChatBillingConflict: description: 'Your organization''s billing is not ready to serve requests. `tier_switch_pending` means its billing tier is changing: wait for the number of seconds in `Retry-After`, then retry. `billing_setup_required` means its billing setup is incomplete: retry only after finishing setup in Billing.' headers: Retry-After: description: The minimum number of seconds to wait before retrying. Sent with `tier_switch_pending`. schema: type: integer minimum: 1 x-should-retry: description: '`false` when no retry can succeed until billing setup is finished; sent with `billing_setup_required`. Browsers may read it.' schema: type: string enum: - 'false' x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Tier switch in progress: summary: Tier switch in progress value: error: message: This organization's billing tier is changing. Retry after the indicated delay. type: permission_error param: null code: tier_switch_pending Billing setup incomplete: summary: Billing setup incomplete value: error: message: This organization's billing setup is incomplete. Finish setup in Billing to resume API requests. type: permission_error param: null code: billing_setup_required ModelNotFound: description: The requested model does not exist or is not available to you. Choose a model from the models list before retrying. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Unknown model: $ref: '#/components/examples/UnknownModel' ChatModelNotFound: description: The requested model does not exist or is not available to you. Choose a model from the models list before retrying. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Unknown model: $ref: '#/components/examples/UnknownModel' TooManyRequests: description: 'The request was rejected because a rate limit was exceeded. Wait for the number of seconds in `Retry-After`, when present, then retry. A spent daily request limit also sends `x-should-retry: false`: it resets at 00:00 UTC.' headers: Retry-After: description: The minimum number of seconds to wait before retrying. Omitted when no retry delay is known. schema: type: integer minimum: 1 x-should-retry: description: '`false` when the organization''s daily request limit is spent. Do not retry automatically: `Retry-After` then gives the seconds until it resets at 00:00 UTC. Browsers may read it.' schema: type: string enum: - 'false' x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Request rate limit: $ref: '#/components/examples/RequestRateLimit' Daily request limit: $ref: '#/components/examples/DailyRequestLimit' ChatTooManyRequests: description: 'A rate limit was exceeded: your organization''s requests or tokens per period, or the requests it or an API key may run at once, with code `rate_limit_exceeded`; or its plan''s daily token allowance, with code `daily_allowance_exhausted`. Wait for the seconds in `Retry-After`, when present, then retry. `x-should-retry: false` marks a daily limit, which renews at 00:00 UTC.' headers: Retry-After: description: The minimum number of seconds to wait before retrying. Omitted when no retry delay is known. schema: type: integer minimum: 1 x-should-retry: description: '`false` when the organization''s daily request limit, daily token limit, or daily token allowance is spent. Do not retry automatically: `Retry-After` then gives the seconds until it renews at 00:00 UTC. Browsers may read it.' schema: type: string enum: - 'false' x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Request rate limit: $ref: '#/components/examples/RequestRateLimit' Token rate limit: $ref: '#/components/examples/TokenRateLimit' Daily request limit: $ref: '#/components/examples/DailyRequestLimit' Daily token limit: $ref: '#/components/examples/DailyTokenLimit' Daily allowance: summary: Daily allowance value: error: message: 'Your organization has used its daily output token allowance. It renews at 00:00 UTC (2026-10-05T00:00:00Z). View your usage and billing here: https://platform.reflection.ai/billing' type: rate_limit_error param: null code: daily_allowance_exhausted Plan requests in flight: summary: Plan requests in flight value: error: message: Your organization has reached its concurrent request limit. Retry after the indicated delay. type: rate_limit_error param: null code: rate_limit_exceeded Concurrent request limit: summary: Concurrent request limit value: error: message: Your organization or API key has reached its concurrent request limit. type: rate_limit_error param: null code: rate_limit_exceeded ServiceUnavailable: description: The service is temporarily unavailable. The request may be retried, after the number of seconds in `Retry-After` when present. headers: Retry-After: description: The minimum number of seconds to wait before retrying. Sent when a check the request depends on cannot answer; omitted with `model_availability_unavailable`. schema: type: integer minimum: 1 x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Rate limiting unavailable: $ref: '#/components/examples/RateLimitingUnavailable' Model availability check unavailable: $ref: '#/components/examples/ModelAvailabilityUnavailable' ChatServiceUnavailable: description: 'The service is temporarily unavailable. The request may be retried, after the number of seconds in `Retry-After` when present, unless `x-should-retry` is `false`. `billing_setup_incomplete` means billing setup for your organization failed and Reflection has been alerted: retrying does not help and no action is needed.' headers: Retry-After: description: The minimum number of seconds to wait before retrying. Sent when inference capacity is temporarily exhausted, a chat completion returned an empty response, billing setup is in progress, or a check the request depends on cannot answer; omitted with `model_availability_unavailable`. schema: type: integer minimum: 1 x-should-retry: description: '`true` when a chat completion returned an empty response, which a retry is likely to resolve. `false` with `billing_setup_incomplete`, when no retry can succeed until billing setup is finished. Browsers may read it.' schema: type: string enum: - 'true' - 'false' x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' x-ratelimit-limit-requests: $ref: '#/components/headers/x-ratelimit-limit-requests' x-ratelimit-remaining-requests: $ref: '#/components/headers/x-ratelimit-remaining-requests' x-ratelimit-reset-requests: $ref: '#/components/headers/x-ratelimit-reset-requests' x-ratelimit-limit-requests-day: $ref: '#/components/headers/x-ratelimit-limit-requests-day' x-ratelimit-remaining-requests-day: $ref: '#/components/headers/x-ratelimit-remaining-requests-day' x-ratelimit-reset-requests-day: $ref: '#/components/headers/x-ratelimit-reset-requests-day' x-ratelimit-limit-tokens: $ref: '#/components/headers/x-ratelimit-limit-tokens' x-ratelimit-remaining-tokens: $ref: '#/components/headers/x-ratelimit-remaining-tokens' x-ratelimit-reset-tokens: $ref: '#/components/headers/x-ratelimit-reset-tokens' x-ratelimit-limit-tokens-day: $ref: '#/components/headers/x-ratelimit-limit-tokens-day' x-ratelimit-remaining-tokens-day: $ref: '#/components/headers/x-ratelimit-remaining-tokens-day' x-ratelimit-reset-tokens-day: $ref: '#/components/headers/x-ratelimit-reset-tokens-day' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Rate limiting unavailable: $ref: '#/components/examples/RateLimitingUnavailable' Model availability check unavailable: $ref: '#/components/examples/ModelAvailabilityUnavailable' Inference capacity exhausted: $ref: '#/components/examples/InferenceCapacityExhausted' Billing setup in progress: summary: Billing setup in progress value: error: message: Billing setup is still in progress. Retry after the indicated delay. type: api_error param: null code: billing_provisioning_pending Billing setup incomplete: summary: Billing setup incomplete value: error: message: Billing setup for this organization needs attention. Reflection has been alerted; no action is needed. type: api_error param: null code: billing_setup_incomplete Inference capacity unavailable: summary: Inference capacity unavailable value: error: message: Inference capacity is temporarily unavailable. Retry after the indicated delay. type: api_error param: null code: inference_capacity_unavailable Model temporarily unavailable: summary: Model temporarily unavailable value: error: message: The requested model is temporarily unavailable. The request may be retried. type: api_error param: null code: model_unavailable Empty response: summary: Empty chat completion value: error: message: The inference service returned an empty response. The request may be retried. type: upstream_unavailable_error param: null code: upstream_empty_response Inference service overloaded: summary: Inference service overloaded value: error: message: The inference service is temporarily unavailable type: upstream_unavailable_error param: null code: overloaded InternalServerError: description: The request failed because of an error on Reflection's side. The request may be retried. headers: x-request-id: $ref: '#/components/headers/x-request-id' reflection-data-retention: $ref: '#/components/headers/reflection-data-retention' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Internal error: summary: Internal error value: error: message: Unable to prepare inference request. type: api_error param: null code: internal_error schemas: ModelList: type: object required: - object - data properties: object: type: string enum: - list description: The object type, which is always `list`. data: type: array description: The available models. items: $ref: '#/components/schemas/Model' Model: type: object description: Describes a model offering that can be used with the API. required: - id - object - created - owned_by - shutdown_date properties: id: type: string description: The model identifier, which can be referenced in the API endpoints. object: type: string enum: - model description: The object type, which is always `model`. created: type: integer format: int64 description: The Unix timestamp (in seconds) when the model was published, or 0 if its publication time is not announced. owned_by: type: string description: The organization serving the model, which is always `reflection`. shutdown_date: type: string nullable: true description: The date when the model will shut down, or null if not announced. context_length: type: integer format: int64 minimum: 1 description: The largest request the model supports, in tokens, counting the prompt and the generated output together. Omitted if not announced. max_output_tokens: type: integer format: int64 minimum: 1 description: The most tokens the model supports generating in response to one request. Omitted if not announced. default_parameters: $ref: '#/components/schemas/ModelDefaultParameters' reasoning: $ref: '#/components/schemas/ModelReasoning' max_top_logprobs: type: integer minimum: 0 maximum: 20 description: The largest `top_logprobs` a chat completion request for this model accepts. Omitted if the model does not return log probabilities, in which case `logprobs` cannot be true. ModelDefaultParameters: type: object description: The sampling and output settings the model applies to your organization's chat completion requests; they can differ between organizations. A setting a request can send applies only when the request omits it or sets it to null. Settings not listed use the model's own defaults. Omitted if the model sets none. properties: temperature: type: number minimum: 0 maximum: 2 description: The `temperature` applied when a request omits it or sets it to null. top_p: type: number minimum: 0 maximum: 1 description: The `top_p` applied when a request omits it or sets it to null. frequency_penalty: type: number minimum: -2 maximum: 2 description: The `frequency_penalty` applied when a request omits it or sets it to null. presence_penalty: type: number minimum: -2 maximum: 2 description: The `presence_penalty` applied when a request omits it or sets it to null. max_tokens: type: integer minimum: 1 description: The output budget, reasoning tokens included, applied when a request sets neither `max_tokens` nor `max_completion_tokens`, or sets them to null. Without it, the model's own limits apply. A request with `logprobs` true receives at most 8,192. top_k: type: integer minimum: 1 description: How many of the most likely tokens the model samples from. Applied to every request; a chat completion request cannot set it. min_p: type: number minimum: 0 maximum: 1 description: The smallest probability, relative to the most likely token, that a token needs to be sampled. Applied to every request; a chat completion request cannot set it. repetition_penalty: type: number exclusiveMinimum: true minimum: 0 maximum: 2 description: 'How strongly the model avoids repeating tokens: 1 applies no penalty, and higher values penalize repetition more. Applied to every request; a chat completion request cannot set it.' ModelReasoning: type: object description: The model's reasoning-effort configuration. Omitted if the model does not announce its supported efforts. required: - supported_efforts - mandatory properties: supported_efforts: type: array minItems: 1 description: The `reasoning_effort` values the model accepts, highest effort first. A chat completion request for this model accepts no other value. items: type: string enum: - max - xhigh - high - medium - low default_effort: type: string enum: - max - xhigh - high - medium - low description: The effort applied to your organization's requests that omit `reasoning_effort` or set it to null; it can differ between organizations. Omitted if the model chooses its own. mandatory: type: boolean description: Whether reasoning is always on. When true, no `reasoning_effort` value disables reasoning. ChatCompletionRequest: type: object additionalProperties: true required: - model - messages properties: model: type: string minLength: 1 description: ID of the model to use. Use [List models](/models) to see the models available to you. messages: type: array minItems: 1 description: A list of messages comprising the conversation so far. items: $ref: '#/components/schemas/ChatCompletionMessage' stream: type: boolean nullable: true default: false description: Whether to stream the model response data to the client as it is generated using server-sent events. See the [streaming guide](/streaming) for how to handle the streamed events. stream_options: $ref: '#/components/schemas/ChatCompletionStreamOptions' temperature: type: number minimum: 0 maximum: 2 nullable: true description: The sampling temperature, from 0 to 2. Higher values such as 0.8 make the output more varied; lower values such as 0.2 make it more focused and consistent. Adjust this or `top_p`, not both. When omitted or null, the model's `default_parameters.temperature` from the models endpoints applies, if it lists one. top_p: type: number minimum: 0 maximum: 1 nullable: true description: The nucleus sampling threshold, from 0 to 1. The model samples only from the most likely tokens whose probabilities add up to `top_p`, so 0.1 limits it to the top 10% of probability mass. Adjust this or `temperature`, not both. When omitted or null, the model's `default_parameters.top_p` from the models endpoints applies, if it lists one. max_tokens: type: integer minimum: 1 nullable: true deprecated: true description: |- The maximum number of tokens that can be generated in the chat completion, including reasoning tokens. Deprecated in favor of `max_completion_tokens`. The two cannot be set together. If both are omitted or null, the model's `default_parameters.max_tokens` applies, unreduced for the prompt. Your plan's per-request output limit applies if lower. At most 8,192 when `logprobs` is true. max_completion_tokens: type: integer minimum: 1 nullable: true description: Maximum generated tokens, including visible output and [reasoning tokens](/reasoning). The prompt plus this value should fit within `context_length`. Cannot be set together with `max_tokens`. If both are omitted or null, the model's `default_parameters.max_tokens` applies, unreduced for the prompt. Your plan's per-request output limit applies if lower. At most 8,192 when `logprobs` is true. stop: $ref: '#/components/schemas/ChatCompletionStop' seed: type: integer format: int64 nullable: true x-reflection-ignored: true description: A seed for sampling, meant to make repeated requests with the same `seed` and parameters return the same result. **Accepted but has no effect:** sampling is not seeded, so results can differ. x-mint: post: - No effect reasoning_effort: $ref: '#/components/schemas/ChatCompletionReasoningEffort' tools: type: array nullable: true maxItems: 128 description: 'A list of tools the model may call, each a `function` tool with a `name`, an optional `description` and JSON Schema `parameters`. A call the model makes is returned in `message.tool_calls` with `finish_reason: tool_calls`.' items: type: object additionalProperties: true required: - type - function properties: type: type: string enum: - function description: The kind of tool, which is always `function`. function: type: object additionalProperties: true required: - name properties: name: type: string minLength: 1 maxLength: 64 description: 'The function''s name, as the model will call it: 1 to 64 ASCII letters, digits, underscores or hyphens.' strict: type: boolean nullable: true description: 'Whether to enable strict schema adherence when generating the call. When `true`, `parameters` must be an object schema whose objects set `additionalProperties: false` and require every property, and whose arrays set `items`. **Not supported:** `allOf`, `oneOf`, `not`, `if`/`then`/`else`, `contains`/`minContains`/`maxContains`, `uniqueItems`, `unevaluatedItems`/`unevaluatedProperties`, `propertyNames`, `minProperties`/`maxProperties`, `dependentRequired`/`dependentSchemas`, `patternProperties`, `multipleOf` or `exclusiveMinimum`/`exclusiveMaximum`. Some keyword combinations, `pattern` constructs and `format` values are also refused.' description: 'The function definition: `name`, optional `description` and `strict`, and JSON Schema `parameters`. When `strict` is true, `parameters` may have at most 10 nested object levels, 5,000 properties, 1,000 `enum` values and 120,000 characters of names and string literals, `$ref` only to the root or a root definition, and `minimum` without `maximum` only as 0, or as 1 on an integer.' tool_choice: $ref: '#/components/schemas/ChatCompletionToolChoice' parallel_tool_calls: type: boolean nullable: true description: Whether to enable parallel function calling during tool use. Allowed only when `tools` is supplied. n: type: integer nullable: true enum: - 1 x-reflection-default-only: '1' description: How many chat completion choices to generate for each input message. **Only `1` is supported.** x-mint: post: - Only 1 logprobs: type: boolean nullable: true default: false x-reflection-model-capability: max_top_logprobs description: Whether to return, in `choices[].logprobs`, the log probability of each output token in `content`. When `true`, the output budget, reasoning tokens included, is at most 8,192 tokens, and a larger limit is rejected. A model that does not list `max_top_logprobs` on the models endpoints accepts only `false` or `null`. top_logprobs: type: integer minimum: 0 maximum: 20 nullable: true x-reflection-model-capability: max_top_logprobs description: The maximum number of most likely tokens, from 0 to 20, to return at each token position, each with its log probability. When omitted or null, none are returned. A model accepts at most the `max_top_logprobs` it lists. A non-null value is allowed only when `logprobs` is true. frequency_penalty: type: number minimum: -2 maximum: 2 nullable: true description: How much to penalize a token for each time it has already appeared, from -2 to 2. Positive values reduce verbatim repetition; negative values encourage it. When omitted or null, the model's `default_parameters.frequency_penalty` from the models endpoints applies, if it lists one. presence_penalty: type: number minimum: -2 maximum: 2 nullable: true description: How much to penalize a token that has already appeared at least once, from -2 to 2. Positive values steer the model toward new words and topics; negative values keep it on them. When omitted or null, the model's `default_parameters.presence_penalty` from the models endpoints applies, if it lists one. logit_bias: type: object nullable: true maxProperties: 0 x-reflection-default-only: an empty object description: Modifies the likelihood of specified tokens appearing in the completion. **Not supported:** only an empty object is accepted. x-mint: post: - Only an empty object response_format: $ref: '#/components/schemas/ChatCompletionResponseFormat' service_tier: type: string nullable: true enum: - auto - default x-reflection-default-only: auto or default description: Specifies the processing type used for serving the request. **Only `auto` and `default` are supported.** Both select standard processing. x-mint: post: - Only auto or default store: type: boolean nullable: true enum: - false x-reflection-default-only: 'false' description: Whether to store the output of this chat completion request so it can be retrieved later. **Only `false` is supported.** x-mint: post: - Only false modalities: type: array nullable: true minItems: 1 maxItems: 1 items: type: string enum: - text x-reflection-default-only: '["text"]' description: Output types that you would like the model to generate. **Only `["text"]` is supported.** x-mint: post: - Only ["text"] verbosity: type: string nullable: true enum: - medium x-reflection-default-only: medium description: Constrains the verbosity of the model's response. **Only `medium` is supported.** x-mint: post: - Only medium metadata: type: object nullable: true maxProperties: 16 x-reflection-ignored: true description: Up to 16 key-value pairs to attach to the request, each value a string of at most 512 characters. **Accepted but has no effect:** the pairs are not stored or returned. additionalProperties: true x-mint: post: - No effect safety_identifier: type: string nullable: true maxLength: 128 description: A stable identifier for the end user of your application, of at most 128 characters. Requests are attributed to it when detecting and handling misuse. The model never sees it. Send a hash of a username or email address rather than the value itself. prompt_cache_key: type: string nullable: true x-reflection-ignored: true description: A key shared by requests with a common prompt prefix, to improve cache hit rates. **Accepted but has no effect:** requests are not routed or cached by it. It is recorded with the request for internal usage analytics. x-mint: post: - No effect prompt_cache_options: type: object nullable: true additionalProperties: false x-reflection-ignored: true description: Options for prompt caching. **Accepted but has no effect:** caching does not change with them. properties: mode: type: string enum: - implicit - explicit description: 'How cache breakpoints are chosen: `implicit` adds one automatically, and `explicit` uses only those set on content parts.' ttl: type: string enum: - 30m description: The minimum lifetime of a cache entry, which is always `30m`. x-mint: post: - No effect prompt_cache_retention: type: string nullable: true deprecated: true enum: - in_memory - 24h x-reflection-ignored: true description: The retention policy for the prompt cache. Deprecated in favor of `prompt_cache_options`. **Accepted but has no effect:** cache retention does not change. x-mint: post: - No effect user: type: string nullable: true deprecated: true x-reflection-ignored: true description: A stable identifier for your end user. Deprecated in favor of `safety_identifier` and `prompt_cache_key`. **Accepted but has no effect:** responses do not depend on it. It is recorded with the request for internal usage analytics. x-mint: post: - No effect description: Parameters not listed here are not supported. ChatCompletionStreamOptions: type: object nullable: true additionalProperties: false description: 'Options for streaming response. Only set this when you set `stream: true`.' properties: include_usage: type: boolean default: false description: 'Whether to stream an additional chunk before the `data: [DONE]` message. The `usage` field on this chunk shows the token usage statistics for the entire request, and the `choices` field will always be an empty array.' include_obfuscation: type: boolean default: true description: Whether streamed events have their payloads and timings normalized in a manner that mitigates specific side-channel attacks. When enabled, each event carries an `obfuscation` property that pads events to a fixed length with random characters. Setting to `false` may slightly increase the rate at which chunks are received. Obfuscation should only be disabled in environments where traffic is not observable. ChatCompletionMessage: type: object additionalProperties: false description: A message in the conversation. `content` is required except on an assistant turn, where it may be null or absent when the turn produced only reasoning or tool calls, as a prior completion may have returned. On a `user` message, `content` must contain text other than whitespace. required: - role properties: role: type: string enum: - developer - system - user - assistant - tool description: The role of the message's author. `system` and `developer` messages apply only at the start of `messages`; one that follows a message of another role is accepted but ignored. content: $ref: '#/components/schemas/ChatCompletionMessageContent' name: type: string description: An optional name for the participant, distinguishing participants with the same role. On a `tool` message, the name of the tool that produced the result. tool_calls: type: array nullable: true description: The tool calls of a prior assistant turn, as returned in that completion's `message.tool_calls`. Accepted only on assistant messages. Each call needs a distinct `id`, and the messages that directly follow the turn must be `tool` messages answering every call exactly once, in any order, before any other message. items: $ref: '#/components/schemas/ChatCompletionMessageToolCall' tool_call_id: type: string nullable: true minLength: 1 description: The `id` of the tool call this message answers. Required on, and accepted only on, `tool` messages. The call must belong to the assistant message this `tool` message follows, directly or after that message's other results, and must not already be answered. reasoning_content: type: string nullable: true description: The reasoning of a prior assistant turn, as returned in that completion's `message.reasoning_content`. Required on assistant messages, as a string containing text other than whitespace, and accepted only on them. refusal: type: string nullable: true description: The refusal of a prior assistant turn, as returned in that completion's `message.refusal`. Accepted only on assistant messages. ChatCompletionMessageToolCall: type: object additionalProperties: true description: A tool call made in a prior assistant turn. required: - type - id - function properties: type: type: string enum: - function description: The kind of tool call, which is always `function`. id: type: string minLength: 1 description: The ID of the tool call, which the `tool` message answering it gives as its `tool_call_id`. function: type: object additionalProperties: true required: - name - arguments properties: name: type: string description: The name of the function the model called. arguments: type: string description: The arguments the model generated for the call, as a JSON string. description: The function the model called. ChatCompletionMessageContent: nullable: true description: The contents of the message, either a string or a non-empty array of text parts, or null on an assistant message only. oneOf: - type: string - type: array minItems: 1 description: An array of text parts, concatenated in order into the text the model receives. items: $ref: '#/components/schemas/ChatCompletionContentPartText' ChatCompletionContentPartText: type: object description: A text part of a message. additionalProperties: false required: - type - text properties: type: type: string enum: - text description: The type of the content part, which is always `text`. text: type: string description: The text content. prompt_cache_breakpoint: type: object nullable: true additionalProperties: false required: - mode x-reflection-ignored: true description: Marks the end of a reusable prompt prefix. **Accepted but has no effect:** the breakpoint does not change which prefixes are cached. properties: mode: type: string enum: - explicit description: The breakpoint mode, which is always `explicit`. x-mint: post: - No effect ChatCompletionResponse: type: object description: Represents a chat completion response returned by the model, based on the provided input. required: - id - object - created - model - choices - usage properties: id: type: string description: A unique identifier for the chat completion. object: type: string enum: - chat.completion description: The object type, which is always `chat.completion`. created: type: integer format: int64 description: The Unix timestamp (in seconds) of when the chat completion was created. model: type: string description: The model used for the chat completion. choices: type: array description: A list of chat completion choices. items: $ref: '#/components/schemas/ChatCompletionChoice' usage: $ref: '#/components/schemas/CompletionUsage' ChatCompletionLogprobs: type: object additionalProperties: true description: Log probabilities of a choice's output tokens. properties: content: type: array nullable: true description: Scores for the tokens of the message's `content`, in order. Reasoning tokens are never scored. items: $ref: '#/components/schemas/ChatCompletionTokenLogprob' refusal: type: array nullable: true description: Scores for the tokens of the message's `refusal`, in order. items: $ref: '#/components/schemas/ChatCompletionTokenLogprob' ChatCompletionTokenLogprob: type: object additionalProperties: true description: One output token and its log probability. required: - token - logprob - bytes - top_logprobs properties: token: type: string description: The token. logprob: type: number description: The log probability of the token, at most 0. bytes: type: array nullable: true description: The token's UTF-8 bytes, which may join with an adjacent token's to form one character. Null if the token has no byte representation. items: type: integer top_logprobs: type: array description: Up to `top_logprobs` of the most likely tokens at this position, each with its log probability. Empty when `top_logprobs` was omitted, null or 0. items: $ref: '#/components/schemas/ChatCompletionTopLogprob' ChatCompletionTopLogprob: type: object additionalProperties: true description: One of the most likely tokens at a position. required: - token - logprob - bytes properties: token: type: string description: The token. logprob: type: number description: The log probability of the token, at most 0. bytes: type: array nullable: true description: The token's UTF-8 bytes. Null if the token has no byte representation. items: type: integer CompletionUsage: type: object description: Usage statistics for the completion request. required: - prompt_tokens - completion_tokens - total_tokens properties: prompt_tokens: type: integer minimum: 0 description: Number of tokens in the prompt. completion_tokens: type: integer minimum: 0 description: Number of tokens in the generated completion. total_tokens: type: integer minimum: 0 description: Total number of tokens used in the request (prompt + completion). prompt_tokens_details: $ref: '#/components/schemas/PromptTokensDetails' completion_tokens_details: $ref: '#/components/schemas/CompletionTokensDetails' PromptTokensDetails: type: object description: Breakdown of tokens used in the prompt. May be omitted when no prompt tokens were cached. properties: cached_tokens: type: integer minimum: 0 description: Cached tokens present in the prompt. CompletionTokensDetails: type: object description: Breakdown of tokens used in a completion. properties: reasoning_tokens: type: integer minimum: 0 description: Tokens generated by the model for reasoning. They count toward the request's token limit but are not returned as `content`. ChatCompletionChoice: type: object description: One of the completions generated for the request. required: - index - message - finish_reason - logprobs properties: index: type: integer description: The index of the choice in the list of choices. message: $ref: '#/components/schemas/AssistantMessage' logprobs: nullable: true description: Log probabilities of the output tokens in `message.content`. Always null when `logprobs` was not requested, and can be null when it was. allOf: - $ref: '#/components/schemas/ChatCompletionLogprobs' finish_reason: type: string nullable: true enum: - stop - length - tool_calls - content_filter description: The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point, `length` if the maximum number of tokens specified in the request was reached, `content_filter` if content was omitted due to a content filter, or `tool_calls` if the model called a tool. ChatCompletionChunk: type: object description: 'Represents a streamed chunk of a chat completion response returned by the model, based on the provided input. A completed stream ends with a `data: [DONE]` message. `service_tier` and `system_fingerprint` never appear on a chunk.' required: - id - object - created - model - choices properties: id: type: string description: A unique identifier for the chat completion. Each chunk has the same ID. object: type: string enum: - chat.completion.chunk description: The object type, which is always `chat.completion.chunk`. created: type: integer format: int64 description: The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp. model: type: string description: The model used for the chat completion. choices: type: array description: A list of chat completion choices. Empty on the final usage chunk when `stream_options.include_usage` is true. items: $ref: '#/components/schemas/ChatCompletionChunkChoice' usage: nullable: true description: Token usage statistics for the entire request. Present only on the final chunk, and only when `stream_options.include_usage` is true; null or absent otherwise. allOf: - $ref: '#/components/schemas/CompletionUsage' obfuscation: type: string description: Random filler that pads the event to the stream's fixed length, hiding the lengths of the tokens it carries; a larger event is padded in 64-byte steps, revealing its length to within 64 bytes. The value carries no information and must be ignored, and may be empty. Absent only when `include_obfuscation` was false. ChatCompletionChunkChoice: type: object description: One choice's portion of a streamed chunk. required: - index - delta - finish_reason properties: index: type: integer description: The index of the choice in the list of choices. delta: $ref: '#/components/schemas/ChatCompletionDelta' logprobs: nullable: true description: Log probabilities of the output tokens in this chunk's `delta.content`. Absent or null when `logprobs` was not requested or the chunk carries no scored content. allOf: - $ref: '#/components/schemas/ChatCompletionLogprobs' finish_reason: type: string nullable: true enum: - stop - length - tool_calls - content_filter x-enum-varnames: - ChatCompletionChunkFinishReasonStop - ChatCompletionChunkFinishReasonLength - ChatCompletionChunkFinishReasonToolCalls - ChatCompletionChunkFinishReasonContentFilter description: The reason the model stopped generating tokens, or null until the choice is finished. This will be `stop` if the model hit a natural stop point, `length` if the requested maximum number of tokens was reached, `content_filter` if content was omitted due to a content filter, or `tool_calls` if the model called a tool. ChatCompletionDelta: type: object description: A chat completion delta generated by streamed model responses. properties: role: type: string enum: - assistant description: The role of the author of this message. content: type: string nullable: true description: The contents of the chunk message. reasoning_content: type: string nullable: true description: The reasoning contents carried by this chunk, reported separately from `content`. tool_calls: type: array description: 'Tool-call fragments carried by this chunk: each has an `index` and, over successive chunks, the call''s `id`, `type`, function `name` and `arguments` pieces.' items: type: object additionalProperties: true AssistantMessage: type: object description: A chat completion message generated by the model. required: - role - content - refusal properties: role: type: string enum: - assistant description: The role of the author of this message. content: type: string nullable: true description: The contents of the message. Null when the model made only tool calls, or when the token limit was reached before any visible output was generated. refusal: type: string nullable: true description: The refusal message generated by the model. reasoning_content: type: string nullable: true description: The reasoning the model produced before the final answer, reported separately from `content`. Its tokens are counted in `usage.completion_tokens_details.reasoning_tokens`. tool_calls: type: array nullable: true description: 'The tool calls the model made: each has an `id`, `type: function`, and a `function` with `name` and JSON `arguments`. Present when `finish_reason` is `tool_calls`.' items: type: object additionalProperties: true ChatCompletionReasoningEffort: type: string nullable: true minLength: 1 maxLength: 64 description: 'Constrains effort on reasoning: a level name of 1 to 64 characters, such as `low`, `medium`, `high`, `xhigh`, or `max`. A model that lists `reasoning.supported_efforts` accepts only those values. When omitted or null, the default that [retrieving the model](/models) reports in `reasoning.default_effort` applies; if it reports none, the model chooses its own effort. See the [reasoning guide](/reasoning).' ChatCompletionStop: nullable: true x-reflection-ignored: true description: 'Sequences at which to stop generating further tokens: a non-empty string, or an array of 1 to 4 non-empty strings. **Accepted but has no effect:** generation does not stop at these sequences.' oneOf: - type: string minLength: 1 - type: array minItems: 1 maxItems: 4 items: type: string minLength: 1 x-mint: post: - No effect ChatCompletionToolChoice: nullable: true description: 'Controls which (if any) tool is called by the model: `none`, `auto`, `required`, or an object naming one function the model must call. Allowed only when `tools` is supplied.' oneOf: - type: string enum: - none - auto - required - type: object additionalProperties: false required: - type - function properties: type: type: string enum: - function description: The kind of tool to force, which is always `function`. function: type: object additionalProperties: false required: - name properties: name: type: string minLength: 1 description: The name of the function the model must call. description: The function the model must call. ChatCompletionResponseFormat: description: 'An object specifying the format that the model must output, selected by its `type`: plain `text`, a valid JSON object (`json_object`), or JSON matching the schema in `json_schema` (`json_schema`).' oneOf: - $ref: '#/components/schemas/ChatCompletionResponseFormatText' - $ref: '#/components/schemas/ChatCompletionResponseFormatJsonObject' - $ref: '#/components/schemas/ChatCompletionResponseFormatJsonSchema' discriminator: propertyName: type mapping: text: '#/components/schemas/ChatCompletionResponseFormatText' json_object: '#/components/schemas/ChatCompletionResponseFormatJsonObject' json_schema: '#/components/schemas/ChatCompletionResponseFormatJsonSchema' ChatCompletionResponseFormatText: type: object additionalProperties: false required: - type description: Plain text output. properties: type: type: string enum: - text description: The type of response format, which is always `text`. ChatCompletionResponseFormatJsonObject: type: object additionalProperties: false required: - type description: Output that is a valid JSON object, with no schema applied. properties: type: type: string enum: - json_object description: The type of response format, which is always `json_object`. ChatCompletionResponseFormatJsonSchema: type: object additionalProperties: false required: - type - json_schema description: Output that is JSON matching the supplied schema. properties: type: type: string enum: - json_schema description: The type of response format, which is always `json_schema`. json_schema: type: object additionalProperties: true required: - name - schema properties: name: type: string minLength: 1 maxLength: 64 description: 'The name of the response format: 1 to 64 ASCII letters, digits, underscores or hyphens.' schema: type: object additionalProperties: true description: The JSON Schema the output must satisfy. When `strict` is true, it may have at most 10 nested object levels, 5,000 properties, 1,000 `enum` values and 120,000 characters of names and string literals, `$ref` only to the root or a root definition, and `minimum` without `maximum` only as 0, or as 1 on an integer. strict: type: boolean nullable: true description: 'Whether to enable strict schema adherence when generating the output. When `true`, `schema` must be an object schema whose objects set `additionalProperties: false` and require every property, and whose arrays set `items`. **Not supported:** `allOf`, `oneOf`, `not`, `if`/`then`/`else`, `contains`/`minContains`/`maxContains`, `uniqueItems`, `unevaluatedItems`/`unevaluatedProperties`, `propertyNames`, `minProperties`/`maxProperties`, `dependentRequired`/`dependentSchemas`, `patternProperties`, `multipleOf` or `exclusiveMinimum`/`exclusiveMaximum`. Some keyword combinations, `pattern` constructs and `format` values are also refused.' description: 'The schema definition for `json_schema`: a `name`, an optional `description`, the JSON `schema`, and an optional `strict` flag.' ErrorResponse: type: object description: The body returned with every error status. required: - error properties: error: $ref: '#/components/schemas/Error' Error: type: object description: An error returned by the API. required: - message - type - param - code properties: message: type: string description: A human-readable description of the error. type: type: string description: The error category, such as `invalid_request_error`. param: type: string nullable: true description: The request parameter the error relates to, or null. code: type: string nullable: true description: A machine-readable error code, or null.