> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guarded Responses

> Guarded Responses API: guardrails and output moderation applied to every request.

> [card] [Guide: Responses](https://docs.gloo.com/api-guides/responses.md)
>
> Request and response format, values, reasoning, and images.

> [card] [Error Reference: Guarded Responses](https://docs.gloo.com/api-reference/general/errors.md#responses)
>
> Common errors: guardrail block, unsupported model, unsupported sampling parameter, context window exceeded, provider timeout, provider unavailable.


## OpenAPI

````yaml post /ai/v2/guarded/responses
openapi: 3.1.0
info:
  title: AI API
  description: |-
    Optimized for high-speed inference and scalability by Gloo AI

    [Swagger UI](./docs) | [ReDoc UI](./redoc)
  version: 1.0.0
servers:
  - url: https://platform.ai.gloo.com
security:
  - bearerAuth: []
tags:
  - name: Content Controls
  - name: Data Engine
  - name: Ingestion & Enrichment
  - name: answers
  - name: chat
  - name: completions
  - name: content
  - name: core
  - name: data
  - name: get-models
  - name: ingestion
  - name: sotc
  - name: v1
  - name: v2
  - name: decisions
paths:
  /ai/v2/guarded/responses:
    post:
      tags:
        - v2
      summary: Responses API V2 (guarded)
      description: >-
        Generate Responses API outputs through Gloo's guarded pipeline
        (guardrails, output moderation, and values-alignment).
      operationId: post-v2-responses
      parameters:
        - in: header
          name: X-Cache-TTL
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Cache-Ttl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V2ResponsesRequest'
            examples:
              minimal:
                summary: Minimal Example
                description: >-
                  The smallest valid guarded request: a model, an input prompt,
                  and a tradition.
                value:
                  model: gloo-openai-gpt-6-luna
                  input: Hello
                  tradition: mainline
              full:
                summary: Full Example
                description: >-
                  A guarded request with a tradition, instructions, an output
                  limit, reasoning effort, and a non-streaming response.
                value:
                  model: gloo-openai-gpt-6-luna
                  input: Hello
                  tradition: mainline
                  instructions: You are a helpful assistant.
                  max_output_tokens: 1024
                  reasoning:
                    effort: minimal
                  stream: false
      responses:
        '200':
          description: >-
            Successful Responses API result. If `stream` is false or omitted,
            the response is JSON. If `stream=true`, the response is a named
            Server-Sent Events stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesApiResponse'
            text/event-stream:
              schema:
                description: >-
                  JSON payloads sent in named Server-Sent Events. The event name
                  is provided in the preceding `event:` line.
                anyOf:
                  - $ref: '#/components/schemas/ResponsesStreamOutputItemEvent'
                  - $ref: '#/components/schemas/ResponsesStreamContentPartEvent'
                  - $ref: '#/components/schemas/ResponsesStreamTextDeltaEvent'
                  - $ref: >-
                      #/components/schemas/ResponsesStreamFunctionArgumentsDeltaEvent
                  - $ref: >-
                      #/components/schemas/ResponsesStreamReasoningSummaryPartEvent
                  - $ref: >-
                      #/components/schemas/ResponsesStreamReasoningSummaryTextDeltaEvent
                  - $ref: >-
                      #/components/schemas/ResponsesStreamReasoningSummaryTextDoneEvent
                  - $ref: >-
                      #/components/schemas/ResponsesStreamReasoningTextDeltaEvent
                  - $ref: '#/components/schemas/ResponsesStreamReasoningTextDoneEvent'
                  - $ref: '#/components/schemas/ResponsesStreamCompletedEvent'
                  - $ref: '#/components/schemas/ResponsesStreamIncompleteEvent'
              x-event-payload-schemas:
                - '#/components/schemas/ResponsesStreamOutputItemEvent'
                - '#/components/schemas/ResponsesStreamContentPartEvent'
                - '#/components/schemas/ResponsesStreamTextDeltaEvent'
                - >-
                  #/components/schemas/ResponsesStreamFunctionArgumentsDeltaEvent
                - '#/components/schemas/ResponsesStreamCompletedEvent'
                - '#/components/schemas/ResponsesStreamIncompleteEvent'
              examples:
                text_delta:
                  summary: response.output_text.delta event payload
                  value:
                    delta: Hello
                    output_index: 0
                    content_index: 0
                reasoning_summary_delta:
                  summary: response.reasoning_summary_text.delta event payload
                  value:
                    type: response.reasoning_summary_text.delta
                    item_id: rs_123
                    output_index: 0
                    summary_index: 0
                    delta: The user wants a two-sentence summary
                completed:
                  summary: response.completed event payload
                  value:
                    id: resp_123
                    object: response
                    status: completed
                    usage:
                      input_tokens: 8
                      output_tokens: 7
                      total_tokens: 15
                completed_with_reasoning_carryover:
                  summary: >-
                    response.completed event payload for a request whose input
                    contained reasoning items
                  value:
                    id: resp_123
                    object: response
                    status: completed
                    usage:
                      input_tokens: 8
                      output_tokens: 7
                      total_tokens: 15
                    reasoning_carryover:
                      received: 2
                      carried: 0
                      dropped:
                        - id: rs_123
                          reason: not_gloo_state
                        - id: rs_456
                          reason: not_gloo_state
                      not_sealed: null
          headers:
            X-Gloo-Reasoning-Carryover:
              description: >-
                Returned on streams when the request's `input` contained
                `reasoning` items or the request asked for `include:
                ["reasoning.encrypted_content"]`. Counts of what happened to
                them, for example `received=1, carried=0, dropped=1,
                paired_removed=1` (`paired_removed` only when non-zero). The
                full `reasoning_carryover` object is a top-level field of the
                final `response.completed` or `response.incomplete` event; a
                stream that fails before either ends without it.
              schema:
                type: string
            X-Ignored-Params:
              description: >-
                Returned on streams when parameters were ignored: a
                comma-separated list of parameter names, without values (for
                example `top_p`). Non-streamed responses report the same in
                `ignored_params`.
              schema:
                type: string
        '400':
          description: >-
            Bad Request - Invalid routing configuration or missing required
            fields
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - detail
                    properties:
                      detail:
                        description: Plain validation or routing error detail.
                    additionalProperties: false
                  - $ref: '#/components/schemas/AiErrorResponse'
              examples:
                routing_configuration:
                  summary: Invalid routing configuration
                  value:
                    detail: >-
                      Exactly one routing mechanism (auto_routing, model, or
                      model_family) must be specified.
                invalid_request:
                  summary: Invalid request
                  value:
                    detail: No user message found in the request.
                    error:
                      message: No user message found in the request.
                      type: invalid_request_error
                      code: 1001
                      name: INVALID_REQUEST
                      category: client_error
                      description: The request is malformed or contains invalid parameters.
                      fault: client
                      retryable: false
                      trace_id: trace-id
                context_length_exceeded:
                  summary: Context window exceeded
                  value:
                    detail:
                      message: Input exceeds the model context window.
                      type: context_window_exceeded
                      code: context_length_exceeded
                      model: gloo-anthropic-claude-sonnet-4.6
                      max_input_tokens: 1000000
                      suggestion: >-
                        Use a model with larger context window such as
                        gloo-anthropic-claude-sonnet-4.6 (1M tokens)
                    error:
                      message: Input exceeds the model context window.
                      type: invalid_request_error
                      code: 1002
                      name: CONTEXT_LENGTH_EXCEEDED
                      category: client_error
                      description: >-
                        The total token count of the request exceeds the model's
                        context window.
                      fault: client
                      retryable: false
                      trace_id: trace-id
                      model: gloo-anthropic-claude-sonnet-4.6
                      max_input_tokens: 1000000
                      suggestion: >-
                        Use a model with larger context window such as
                        gloo-anthropic-claude-sonnet-4.6 (1M tokens)
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Invalid API key.
        '402':
          description: >-
            Payment Required - Prepaid credit, Gloo Code allowance, or plan
            entitlement refuses the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiErrorResponse'
              example:
                detail:
                  message: >-
                    Wallet credit balance is exhausted. Add credits to your
                    account to continue.
                  code: INSUFFICIENT_CREDIT
                error:
                  message: >-
                    Wallet credit balance is exhausted. Add credits to your
                    account to continue.
                  type: billing_error
                  code: 1006
                  name: INSUFFICIENT_CREDIT
                  category: client_error
                  description: The account's prepaid wallet credit balance is exhausted.
                  fault: client
                  retryable: false
                  trace_id: trace-id
        '403':
          description: Forbidden - Request blocked by policy or authorization
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
              example:
                detail:
                  message: Your request was rejected as it violates content policies.
                  type: content_policy_violation
                  code: content_policy_violation
                  retryable: false
        '408':
          description: Request Timeout - Provider did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiErrorResponse'
              example:
                detail: The provider did not respond in time. Please try again.
                error:
                  message: The provider did not respond in time. Please try again.
                  type: timeout_error
                  code: 2001
                  name: PROVIDER_TIMEOUT
                  category: provider_error
                  description: >-
                    The upstream model provider did not respond within the
                    allowed time window.
                  fault: provider
                  retryable: true
                  trace_id: trace-id
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Too Many Requests - Spending limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiErrorResponse'
              example:
                detail:
                  message: Spending limit reached
                  code: SPENDING_LIMIT_EXCEEDED
                error:
                  message: Spending limit reached
                  type: billing_error
                  code: 1005
                  name: SPENDING_LIMIT_EXCEEDED
                  category: client_error
                  description: The account's spending limit has been reached.
                  fault: client
                  retryable: false
                  trace_id: trace-id
        '500':
          description: >-
            Internal Server Error - an unexpected provider failure (`2013 /
            PROVIDER_INFERENCE_ERROR`, retryable) or an unexpected Gloo failure
            (`3001 / INTERNAL_ERROR`, not retryable).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiErrorResponse'
              example:
                detail: >-
                  An unexpected error occurred during model inference. Please
                  try again.
                error:
                  message: >-
                    An unexpected error occurred during model inference. Please
                    try again.
                  type: internal_error
                  code: 2013
                  name: PROVIDER_INFERENCE_ERROR
                  category: provider_error
                  description: >-
                    An unexpected error occurred during model inference at the
                    upstream provider.
                  fault: provider
                  retryable: true
                  trace_id: trace-id
        '503':
          description: >-
            Service Unavailable - the model provider is unavailable (`2002 /
            PROVIDER_UNAVAILABLE`, retry with backoff), or a temporary problem
            on Gloo's side (`3003 / SERVICE_UNAVAILABLE`, retryable): wait for
            the `Retry-After` header (usually 30 seconds), then retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiErrorResponse'
              example:
                detail: The provider is currently unavailable. Please try again later.
                error:
                  message: >-
                    The provider is currently unavailable. Please try again
                    later.
                  type: service_unavailable_error
                  code: 2002
                  name: PROVIDER_UNAVAILABLE
                  category: provider_error
                  description: The upstream model provider is temporarily unavailable.
                  fault: provider
                  retryable: true
                  trace_id: trace-id
components:
  schemas:
    V2ResponsesRequest:
      properties:
        model:
          title: Model
          type: string
        input:
          anyOf:
            - type: string
            - items:
                additionalProperties: true
                type: object
              type: array
          description: String prompt or array of input items
          title: Input
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
        max_output_tokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Output Tokens
          description: >-
            Maximum output, in tokens. On a reasoning model it holds the
            reasoning as well as the answer, and it is sent as you set it, so
            leave room for both. With no value, most reasoning models get their
            full output allowance (up to 65,536). A response that reached the
            limit has `status: "incomplete"`. See [Set your output limit for
            reasoning
            models](/api-guides/reasoning#set-your-output-limit-for-reasoning-models).
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        top_p:
          anyOf:
            - type: number
            - type: 'null'
          title: Top P
        frequency_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Frequency Penalty
        presence_penalty:
          anyOf:
            - type: number
            - type: 'null'
          title: Presence Penalty
        stop:
          anyOf:
            - {}
            - type: 'null'
          title: Stop
        tools:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Tools
          description: >-
            Tool definitions, such as custom `function` tools. OpenAI's hosted
            `image_generation` tool draws images on the OpenAI GPT-5 and GPT-6
            models that support it. Its optional `model` picks the image model:
            `gpt-image-2` (the default when `model` is omitted),
            `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst`. `gpt-image-1.5`,
            `chatgpt-image-latest` and `gpt-image-1-mini` still work and retire
            on December 1, 2026. `gpt-image-1` was retired on October 23, 2026:
            a tool that names it runs on `gpt-image-2`, and the response carries
            the `X-Gloo-Model-Redirected-From`, `Deprecation` and `Sunset`
            headers. An image model that doesn't exist returns `400`. See [Image
            models](/api-guides/direct-responses#image-models).
        tool_choice:
          anyOf:
            - {}
            - type: 'null'
          title: Tool Choice
        stream:
          default: false
          title: Stream
          type: boolean
        reasoning:
          anyOf:
            - $ref: '#/components/schemas/ResponsesReasoningConfig'
            - type: 'null'
          title: Reasoning
          description: >-
            Reasoning controls: `effort` sets how much a reasoning model thinks;
            `summary` (`auto`, `concise`, `detailed`) asks for the reasoning,
            returned as a reasoning item in output[] and, on a stream, as
            reasoning events before the answer. An effort the model does not run
            as sent is listed in `ignored_params` as `reasoning.effort=<value>`.
            See the Reasoning guide (/api-guides/reasoning).
        response_format:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Response Format
        text:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Text
          description: >-
            Text options, as on OpenAI's Responses API. `text.format` requests
            structured output — `{"type": "json_schema", "name": ..., "schema":
            {...}, "strict": true}`, `{"type": "json_object"}`, or `{"type":
            "text"}`. If `response_format` is also supplied it takes precedence.
            Other keys, such as `verbosity`, are accepted and ignored.
        parallel_tool_calls:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Parallel Tool Calls
        prompt_cache_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Prompt Cache Key
        image_generation:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Image generation options (quality, size) mapped onto OpenAI's
            image_generation tool; ignored by providers without quality
            controls.
          title: Image Generation
        tradition:
          anyOf:
            - type: string
            - type: 'null'
          title: Tradition
          description: >-
            Optional tradition for guardrail static responses and
            personalization (catholic, evangelical, mainline,
            not_faith_specific). Invalid values are ignored gracefully.
      additionalProperties: true
      type: object
      required:
        - model
        - input
      title: V2ResponsesRequest
      description: >-
        Responses API request for the guarded v2 endpoint. `model` is required

        (pinned-model routing only — no model_family/auto_routing on this
        shape).
    ResponsesApiResponse:
      type: object
      title: Responses API Response
      description: A non-streaming Responses API result.
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
          const: response
          default: response
        created_at:
          type: integer
          description: Unix timestamp when the response was created.
        model:
          type: string
        status:
          type: string
          enum:
            - completed
            - failed
            - in_progress
            - incomplete
        output:
          type: array
          description: >-
            Items generated by the model, such as assistant messages, images,
            function calls, or reasoning summaries.
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
        instructions:
          type: string
        max_output_tokens:
          type: integer
        metadata:
          type: object
          additionalProperties:
            type: string
        parallel_tool_calls:
          type: boolean
        prompt_cache_key:
          type: string
        reasoning:
          additionalProperties: true
          type: object
        temperature:
          type: number
        text:
          additionalProperties: true
          type: object
        tool_choice: {}
        tools:
          items:
            additionalProperties: true
            type: object
          type: array
        top_p:
          type: number
        ignored_params:
          $ref: '#/components/schemas/ResponsesIgnoredParams'
        reasoning_carryover:
          $ref: '#/components/schemas/ResponsesReasoningCarryover'
      required:
        - id
        - object
        - created_at
        - model
        - status
        - output
      example:
        id: resp_123
        object: response
        created_at: 1716912000
        model: gloo-openai-gpt-5.5
        status: completed
        output:
          - type: reasoning
            id: rs_123
            summary:
              - type: summary_text
                text: The user is greeting me, so a short friendly reply fits.
          - type: message
            id: msg_123
            role: assistant
            status: completed
            content:
              - type: output_text
                text: Hello! How can I help?
        usage:
          input_tokens: 8
          output_tokens: 7
          total_tokens: 15
        reasoning:
          effort: medium
          summary: auto
    ResponsesStreamOutputItemEvent:
      type: object
      title: Output Item Event
      description: >-
        The JSON payload in a `response.output_item.added` or
        `response.output_item.done` SSE event. The item itself is in `item`.
      additionalProperties: true
      properties:
        type:
          type: string
          enum:
            - response.output_item.added
            - response.output_item.done
        id:
          type: string
        status:
          type: string
        output_index:
          type: integer
        item:
          $ref: '#/components/schemas/ResponsesOutputItem'
        role:
          type: string
        content:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponsesOutputText'
              - $ref: '#/components/schemas/ResponsesOutputRefusal'
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
        result:
          type: string
      required:
        - type
        - id
    ResponsesStreamContentPartEvent:
      type: object
      title: Content Part Event
      description: >-
        The JSON payload in a `response.content_part.added` or
        `response.content_part.done` SSE event.
      properties:
        type:
          type: string
          const: output_text
          default: output_text
        text:
          type: string
        output_index:
          type: integer
        content_index:
          type: integer
      required:
        - type
        - text
        - output_index
        - content_index
    ResponsesStreamTextDeltaEvent:
      type: object
      title: Text Delta Event
      description: The JSON payload in a `response.output_text.delta` SSE event.
      properties:
        delta:
          type: string
        output_index:
          type: integer
        content_index:
          type: integer
      required:
        - delta
        - output_index
        - content_index
    ResponsesStreamFunctionArgumentsDeltaEvent:
      type: object
      title: Function Call Arguments Event
      description: >-
        The JSON payload in a `response.function_call_arguments.delta` SSE
        event.
      properties:
        delta:
          type: string
        output_index:
          type: integer
      required:
        - delta
        - output_index
    ResponsesStreamReasoningSummaryPartEvent:
      type: object
      title: Reasoning Summary Part Event
      description: >-
        The JSON payload in a `response.reasoning_summary_part.added` (empty
        `part.text`) or `response.reasoning_summary_part.done` (full
        `part.text`) SSE event.
      additionalProperties: true
      properties:
        item_id:
          type: string
          description: The reasoning item's `id`.
        output_index:
          type: integer
        summary_index:
          type: integer
          description: Always 0.
        part:
          type: object
          properties:
            type:
              type: string
              const: summary_text
            text:
              type: string
      required:
        - item_id
        - output_index
        - summary_index
        - part
    ResponsesStreamReasoningSummaryTextDeltaEvent:
      type: object
      title: Reasoning Summary Delta Event
      description: >-
        The JSON payload in a `response.reasoning_summary_text.delta` SSE event.
        Sent only when the request set `reasoning.summary`, before the answer.
      additionalProperties: true
      properties:
        item_id:
          type: string
          description: The reasoning item's `id`.
        output_index:
          type: integer
        summary_index:
          type: integer
          description: Always 0.
        delta:
          type: string
          description: The next piece of the reasoning summary.
      required:
        - item_id
        - output_index
        - summary_index
        - delta
    ResponsesStreamReasoningSummaryTextDoneEvent:
      type: object
      title: Reasoning Summary Done Event
      description: The JSON payload in a `response.reasoning_summary_text.done` SSE event.
      additionalProperties: true
      properties:
        item_id:
          type: string
          description: The reasoning item's `id`.
        output_index:
          type: integer
        summary_index:
          type: integer
          description: Always 0.
        text:
          type: string
          description: The full reasoning summary this item streamed.
      required:
        - item_id
        - output_index
        - summary_index
        - text
    ResponsesStreamReasoningTextDeltaEvent:
      type: object
      title: Reasoning Text Delta Event
      description: >-
        The JSON payload in a `response.reasoning_text.delta` SSE event: a piece
        of the raw reasoning of a model outside the Anthropic, Google and OpenAI
        families. These items open with `response.content_part.added` and close
        with `response.reasoning_text.done` and `response.content_part.done`.
        Sent only when the request set `reasoning.summary`.
      additionalProperties: true
      properties:
        item_id:
          type: string
          description: The reasoning item's `id`.
        output_index:
          type: integer
        content_index:
          type: integer
          description: Always 0.
        delta:
          type: string
      required:
        - item_id
        - output_index
        - content_index
        - delta
    ResponsesStreamReasoningTextDoneEvent:
      type: object
      title: Reasoning Text Done Event
      description: The JSON payload in a `response.reasoning_text.done` SSE event.
      additionalProperties: true
      properties:
        item_id:
          type: string
          description: The reasoning item's `id`.
        output_index:
          type: integer
        content_index:
          type: integer
          description: Always 0.
        text:
          type: string
      required:
        - item_id
        - output_index
        - content_index
        - text
    ResponsesStreamCompletedEvent:
      type: object
      title: Completion Event
      description: >-
        The JSON payload in the terminal `response.completed` SSE event: the
        response's top-level fields, without `output`. On Direct Responses, a
        stream from an OpenAI model served over OpenAI's Responses API carries
        OpenAI's own event instead, with the response object nested under
        `response`.
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
          const: response
          default: response
        status:
          type: string
          const: completed
          default: completed
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
        reasoning_carryover:
          $ref: '#/components/schemas/ResponsesReasoningCarryover'
      required:
        - id
        - object
        - status
    ResponsesStreamIncompleteEvent:
      type: object
      title: Incomplete Event
      description: >-
        The JSON payload in the terminal `response.incomplete` SSE event, sent
        instead of `response.completed` when the answer was cut off at
        `max_output_tokens`. Same shape as the completion event, with `status`
        `incomplete`. On Direct Responses, a stream from an OpenAI model served
        over OpenAI's Responses API carries OpenAI's own event, with the
        response nested under `response`.
      additionalProperties: true
      properties:
        id:
          type: string
        object:
          type: string
          const: response
          default: response
        status:
          type: string
          const: incomplete
          default: incomplete
        incomplete_details:
          type: object
          properties:
            reason:
              type: string
              const: max_output_tokens
        usage:
          $ref: '#/components/schemas/ResponsesUsage'
        reasoning_carryover:
          $ref: '#/components/schemas/ResponsesReasoningCarryover'
      required:
        - id
        - object
        - status
    AiErrorResponse:
      type: object
      title: AiErrorResponse
      description: >-
        AI API error response with existing detail field plus enriched error
        metadata.
      required:
        - detail
        - error
      properties:
        detail:
          description: Existing endpoint-specific error detail. May be a string or object.
        error:
          $ref: '#/components/schemas/AiError'
      additionalProperties: true
    Error:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable description of the error.
      title: Error
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ResponsesReasoningConfig:
      type: object
      title: Reasoning Config
      description: >-
        Reasoning controls for a Responses request. On the Responses endpoints,
        a summary comes back only when `summary` is set. See the Reasoning guide
        (/api-guides/reasoning).
      additionalProperties: true
      properties:
        effort:
          $ref: '#/components/schemas/ReasoningEffort'
        summary:
          type: string
          enum:
            - auto
            - concise
            - detailed
          description: >-
            Ask for the model's reasoning, returned as a `reasoning` item in
            output[] and, when streaming, as reasoning events before the answer
            (`response.reasoning_summary_text.delta`, or
            `response.reasoning_text.delta` for models outside the Anthropic,
            Google and OpenAI families). Leave it out and no reasoning is
            streamed.
    ResponsesOutputItem:
      title: Output Item
      description: >-
        An item generated by the model. An item can be an assistant message,
        generated image, function call, or reasoning summary.
      oneOf:
        - $ref: '#/components/schemas/ResponsesOutputMessage'
        - $ref: '#/components/schemas/ResponsesImageGenerationCall'
        - $ref: '#/components/schemas/ResponsesFunctionCall'
        - $ref: '#/components/schemas/ResponsesReasoning'
    ResponsesUsage:
      type: object
      title: Usage
      description: Token usage for the response.
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
        input_tokens_details:
          type: object
          properties:
            cached_tokens:
              type: integer
        output_tokens_details:
          type: object
          properties:
            reasoning_tokens:
              type: integer
        server_tool_use:
          type: object
          properties:
            web_search_requests:
              type: integer
      required:
        - input_tokens
        - output_tokens
        - total_tokens
    ResponsesIgnoredParams:
      type: object
      title: Ignored Parameters
      description: >-
        Parameters that were ignored or not applied as sent. The request still
        succeeds. Entries are `name=value`: sampling parameters the selected
        model does not accept and, on Direct Responses, reasoning removed from
        `input` (`input.reasoning=<n>` reasoning items,
        `input.reasoning_paired=<n>` other items removed with them) and stateful
        parameters that have no effect (`previous_response_id`, `conversation`,
        `store=True`, `background=True`). On a stream, the parameter names are
        in the `X-Ignored-Params` header instead.
      properties:
        params:
          type: array
          items:
            type: string
        model:
          type: string
        reason:
          type: string
      required:
        - params
        - model
        - reason
      example:
        params:
          - input.reasoning=1
        model: gloo-openai-gpt-5.4-nano
        reason: >-
          These parameters were ignored and did not affect the response: the
          model does not accept them, or this surface does not forward them to
          the provider.
    ResponsesReasoningCarryover:
      type: object
      title: Reasoning Carry-over Report
      description: >-
        What happened to the reasoning items in the request's `input`. Present
        only when `input` contained at least one `reasoning` item, or the
        request asked for `include: ["reasoning.encrypted_content"]`; otherwise
        absent. Gloo does not carry reasoning from one request to the next:
        reasoning state sent back in `input` is removed before any model is
        called, and the request still succeeds. Returned by the guarded
        Responses and Grounded Responses endpoints. On a stream, the counts are
        in the `X-Gloo-Reasoning-Carryover` header and this object is a
        top-level field of the final `response.completed` or
        `response.incomplete` event's data; a stream that fails before either
        event ends without it. Direct Responses does not return this object or
        the header: it reports removed reasoning as `input.reasoning=<n>` and
        `input.reasoning_paired=<n>` in `ignored_params` (`X-Ignored-Params` on
        a stream).
      properties:
        received:
          type: integer
          description: The number of `reasoning` items in the request's `input`.
        carried:
          type: integer
          description: >-
            The number of reasoning items passed to the model as reasoning
            state. Always 0.
        dropped:
          type: array
          description: One entry per removed `reasoning` item, in input order.
          items:
            type: object
            properties:
              id:
                type:
                  - string
                  - 'null'
                description: >-
                  The item's `id`; null when it had no string `id`, or one
                  longer than 256 characters.
              reason:
                type: string
                enum:
                  - not_gloo_state
                  - unsupported_route
                  - invalid
                description: >-
                  `not_gloo_state`: the item carried reasoning state Gloo did
                  not issue (such as an OpenAI `encrypted_content` blob), or
                  carried no reasoning state and was removed because another
                  reasoning item in its turn or in the most recent assistant
                  turn was removed, or carried no reasoning state and was on a
                  request converted for the model. `unsupported_route`: the item
                  carried Gloo-issued reasoning state this endpoint does not
                  use. `invalid`: the item carried a Gloo reasoning-state value
                  in a format Gloo does not recognize.
            required:
              - id
              - reason
        not_sealed:
          type:
            - string
            - 'null'
          enum:
            - unsupported_route
            - null
          description: >-
            `unsupported_route` when the request asked for `include:
            ["reasoning.encrypted_content"]`: Gloo returns no reasoning state.
            Null otherwise.
        paired_removed:
          type: integer
          description: >-
            The number of other items removed with that reasoning: hosted tool
            calls tied to it, the caller's items answering them, assistant
            messages with no text, and `item_reference` items naming a removed
            item. Omitted when 0.
      required:
        - received
        - carried
        - dropped
        - not_sealed
      example:
        received: 1
        carried: 0
        dropped:
          - id: rs_123
            reason: not_gloo_state
        not_sealed: null
        paired_removed: 1
    ResponsesOutputText:
      type: object
      title: Text
      description: Text generated by the model, optionally with source citations.
      properties:
        type:
          type: string
          const: output_text
          default: output_text
        text:
          type: string
          description: The generated text.
        annotations:
          type: array
          description: Source citations associated with the generated text.
          items:
            $ref: '#/components/schemas/ResponsesUrlCitation'
      required:
        - type
        - text
    ResponsesOutputRefusal:
      type: object
      title: Refusal
      description: A refusal returned instead of generated text.
      properties:
        type:
          type: string
          const: refusal
          default: refusal
        refusal:
          type: string
          description: The refusal message.
      required:
        - type
        - refusal
    AiError:
      type: object
      title: AiError
      description: >-
        Standard AI API error object emitted by global provider/model error
        handlers.
      required:
        - message
        - type
        - code
        - name
        - category
        - description
        - fault
        - retryable
        - trace_id
      properties:
        message:
          type: string
          description: Request-specific customer-facing error message.
        type:
          type: string
          description: Stable wire-format error type.
        code:
          type: integer
          description: Stable numeric internal error code.
        name:
          type: string
          description: Stable symbolic error code name.
        category:
          type: string
          enum:
            - client_error
            - provider_error
            - platform_error
          description: Error category derived from the numeric code range.
        description:
          type: string
          description: Stable one-sentence explanation of what the error code means.
        fault:
          type: string
          enum:
            - client
            - provider
            - internal
          description: System responsible for the failure.
        retryable:
          type: boolean
          description: Whether retrying the same request may succeed.
        trace_id:
          type:
            - string
            - 'null'
          description: Sentry trace identifier when available.
      additionalProperties: true
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ReasoningEffort:
      type: string
      title: Reasoning Effort
      description: >-
        How much a reasoning model thinks before it answers, from least to most.
        The levels a given model takes are in its `reasoning.effort_levels` on
        GET /platform/v2/models. A level the model does not take is not refused:
        it runs at the nearest level the model has, or without an effort, and is
        listed in `ignored_params` (`X-Ignored-Params` on a stream). See the
        Reasoning guide (/api-guides/reasoning).
      enum:
        - none
        - minimal
        - low
        - medium
        - high
        - xhigh
        - max
    ResponsesOutputMessage:
      type: object
      title: Message
      description: An assistant message produced by the model.
      properties:
        type:
          type: string
          const: message
          default: message
        id:
          type: string
          description: Unique identifier for the message.
        role:
          type: string
          const: assistant
          default: assistant
        status:
          type: string
          description: Processing status of the message.
          enum:
            - completed
            - in_progress
            - failed
        content:
          type: array
          description: >-
            Content parts in the assistant message. Each part contains generated
            text or a refusal.
          items:
            oneOf:
              - $ref: '#/components/schemas/ResponsesOutputText'
              - $ref: '#/components/schemas/ResponsesOutputRefusal'
      required:
        - type
        - id
        - role
        - status
        - content
    ResponsesImageGenerationCall:
      type: object
      title: Image Generation
      description: An image generated by the model.
      properties:
        type:
          type: string
          const: image_generation_call
          default: image_generation_call
        id:
          type: string
          description: Unique identifier for the image generation item.
        status:
          type: string
          description: Processing status of the image generation request.
          enum:
            - completed
            - in_progress
            - generating
            - failed
        result:
          type: string
          description: Base64-encoded generated image data.
      required:
        - type
        - id
        - status
    ResponsesFunctionCall:
      type: object
      title: Function Call
      description: A function call requested by the model.
      properties:
        type:
          type: string
          const: function_call
          default: function_call
        id:
          type: string
          description: Unique identifier for the function call output item.
        call_id:
          type: string
          description: Identifier used to associate the function result with this call.
        name:
          type: string
          description: Name of the function to call.
        arguments:
          type: string
          description: JSON-encoded function arguments.
      required:
        - type
        - id
        - call_id
        - name
        - arguments
    ResponsesReasoning:
      type: object
      title: Reasoning
      description: >-
        The model's reasoning: a summary in `summary`, or, on streams from
        models outside the Anthropic, Google and OpenAI families, raw reasoning
        in `content`. Reasoning items never include `encrypted_content`, even
        when the request asks for `include: ["reasoning.encrypted_content"]`.
      properties:
        type:
          type: string
          const: reasoning
          default: reasoning
        id:
          type: string
          description: Unique identifier for the reasoning item (`rs_...`).
        summary:
          type: array
          description: Summary parts describing the model's reasoning.
          items:
            type: object
            properties:
              type:
                type: string
                const: summary_text
              text:
                type: string
            required:
              - type
              - text
        status:
          type: string
          enum:
            - in_progress
            - completed
            - incomplete
          description: >-
            Present on streamed items: `in_progress` when the item opens,
            `completed` when it closes normally, and `incomplete` when the
            stream reached the output limit or failed with the item open, or
            when the provider failed while the model was reasoning and the
            request was retried. The retry's reasoning is a new item.
        content:
          type: array
          description: >-
            On streamed items from models outside the Anthropic, Google and
            OpenAI families (DeepSeek, GLM, gpt-oss and similar): the raw
            reasoning, as `reasoning_text` parts. `summary` is then empty.
            Non-streamed items use `summary`.
          items:
            type: object
            properties:
              type:
                type: string
                const: reasoning_text
              text:
                type: string
            required:
              - type
              - text
      required:
        - type
        - id
        - summary
    ResponsesUrlCitation:
      type: object
      title: URL Citation
      description: A source citation attached to an output text part.
      properties:
        type:
          type: string
          const: url_citation
          default: url_citation
        url:
          type: string
        title:
          type: string
        start_index:
          type: integer
        end_index:
          type: integer
      required:
        - type
        - url
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: api-key
      x-default: Bearer <api-key>
      description: >-
        Bearer authentication header of the form Bearer `<api-key>`, where
        `<api-key>` is your [API key](/studio/manage-api-credentials).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.