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

# List all responses with pagination

> Retrieves a paginated list of all agent responses for the authenticated user.



## OpenAPI

````yaml https://apigw.mka1.com/speakeasy.json get /api/v1/llm/responses
openapi: 3.1.1
info:
  title: MKA1 API
  version: 1.1.0
  description: >-
    The MKA1 API is a RESTful API that provides access to the MKA1 platform.
    Learn how to get started with the API and the TypeScript SDK
    [here](https://mka1.apidocumentation.com/guides/getting-started).
  license:
    name: Proprietary
servers:
  - url: https://apigw.mka1.com
    description: MKA1 API Gateway
  - url: /
    description: Relative server URL (configurable via SDK constructor)
security: []
tags:
  - name: Resource Authorization
    description: >-
      Manage permissions for LLM resources. Create resources, grant/revoke
      permissions, and delete resources. Only resource owners can grant, revoke,
      or delete permissions.
    x-displayName: Resource Authorization
  - name: Embeddings
    description: >-
      Text embedding API endpoints for generating vector representations of
      text. Create semantic embeddings for search, clustering, and similarity
      matching using various embedding models.
    x-displayName: Embeddings
  - name: Feedback
    description: >-
      User feedback API for rating and commenting on chat completions. Collect
      thumbs up/down ratings and detailed feedback to improve model responses
      and track user satisfaction.
    x-displayName: Feedback
  - name: Images
    description: >-
      Image generation API endpoints for creating images from text descriptions.
      Generate images with control over size, quality, and style.
    x-displayName: Images
  - name: MCP Vault
    description: >-
      MCP vault API for storing user-owned MCP server configurations and
      encrypted credentials. Agents reference vault IDs so secrets are resolved
      only at tool execution time.
    x-displayName: MCP Vault
  - name: Speech
    description: >-
      Speech API endpoints for audio processing. Convert text to
      natural-sounding speech (TTS) or transcribe speech to text (STT) in
      different languages.
    x-displayName: Speech
  - name: Usage
    description: >-
      Usage tracking and analytics API for monitoring token consumption, request
      counts, and cost analysis. View detailed statistics per user, model, and
      time period.
    x-displayName: Usage
  - name: Extract
    description: >-
      Structured data extraction API for extracting information from files.
      Define JSON schemas to extract structured data from images, PDFs, and
      documents. Supports reusable schema templates.
    x-displayName: Extract
  - name: Text Classification
    description: >-
      Text classification API for categorizing text into predefined labels. Use
      AI models to classify text content for sentiment analysis, topic
      categorization, and content moderation.
    x-displayName: Text Classification
  - name: Responses
    description: >-
      Agent-powered responses API for creating AI agents with autonomous tool
      usage. Build conversational assistants that can use web search, file
      operations, image generation, code execution, computer use simulation, and
      MCP integrations. Supports background processing, streaming, and real-time
      status tracking.
    x-displayName: Responses
  - name: Files
    description: >-
      File management API for uploading, storing, and managing files with
      automatic expiration and S3 integration. Upload files that can be used
      with Assistants, Vector Stores, and other features. Files are stored in S3
      with metadata tracked in PostgreSQL. Supports automatic cleanup of expired
      files.
    x-displayName: Files
  - name: Vector Stores
    description: >-
      Vector store API for storing and searching documents using embeddings.
      Create vector stores, upload files with automatic chunking and embedding
      generation, and perform semantic search. Files are processed
      asynchronously using Temporal workflows for durability. Supports automatic
      cleanup of expired stores and LanceDB for efficient vector storage.
    x-displayName: Vector Stores
  - name: Conversations
    description: >-
      Conversation management API for storing and retrieving conversation state
      across Response API calls. Create conversations, add items (user messages,
      assistant messages, system messages), and maintain conversation history.
      Supports metadata tracking and multi-turn dialogue state management.
    x-displayName: Conversations
  - name: Guardrails
    description: >-
      AI safety guardrails API for configuring content moderation and security
      policies. Set up ban word lists, prompt injection detection, and system
      prompt leakage prevention. Guardrails apply to all requests from an
      account and can be tested before deployment.
    x-displayName: Guardrails
  - name: Models
    description: >-
      Model listing API for discovering available models. Returns model IDs,
      ownership, and metadata for all registered models in the gateway.
    x-displayName: Models
  - name: Skills
    description: >-
      Skills API for managing versioned bundles of instructions and files
      following the Agent Skills standard. Create, version, and download
      reusable skill packages that include SKILL.md manifests for agent
      environments.
    x-displayName: Skills
  - name: Chat Completions
    description: >-
      **Deprecated: Use the Responses API (`/api/v1/llm/responses`) instead.**
      Chat completion endpoints with support for streaming, tool calls, and
      multiple providers.
    x-deprecated: true
    x-displayName: Chat Completions
  - name: Batches
    x-displayName: Batches
  - name: Evals
    x-displayName: Evals
  - name: Fine-Tuning
    x-displayName: Fine-Tuning
  - name: Memory Stores
    x-displayName: Memory Stores
  - name: Prompts
    x-displayName: Prompts
  - name: API Key
    x-displayName: API Key
  - name: Organization
    x-displayName: Organization
  - name: Cluster Admin
    x-displayName: Cluster Admin
  - name: Sessions
    description: Create, inspect, access, and terminate sandbox sessions.
    x-displayName: Sessions
  - name: Browser
    description: >-
      Connect to browser sessions through the gateway port proxy. Browser
      sessions expose a Chrome DevTools Protocol endpoint on port 9222.
    x-displayName: Browser
  - name: Execution
    description: Run shell commands and code inside an existing sandbox session.
    x-displayName: Execution
  - name: Workspace
    description: >-
      Inspect the workspace manifest, transfer files or archives, and download
      generated artifacts.
    x-displayName: Workspace
  - name: Sandbox Usage
    description: >-
      Aggregate sandbox usage statistics across sessions, execution, and
      workspace operations.
    x-displayName: Sandbox Usage
  - name: Sandbox Pricing
    description: >-
      Cluster-admin management of the sandbox compute rate card used for
      budgeted spend.
    x-displayName: Sandbox Pricing
  - name: Agents
    description: Create and manage reusable agent definitions.
    x-displayName: Agents
  - name: Agent Versions
    description: Inspect an agent's configuration history and roll back to a prior version.
    x-displayName: Agent Versions
  - name: Agent Runs
    description: Execute saved agents and inspect persisted run results.
    x-displayName: Agent Runs
  - name: Agent Connectors
    description: >-
      Connect saved agents to external messaging channels such as Telegram,
      including text, photo, and supported document exchange.
    x-displayName: Agent Connectors
  - name: Agent Schedules
    description: Create and manage scheduled or recurring saved agent runs.
    x-displayName: Agent Schedules
  - name: schema-4_other
    x-displayName: other
  - name: Budgets
    x-displayName: Budgets
  - name: Settings
    x-displayName: Settings
  - name: Deployments
    description: Long-lived inference servers.
    x-displayName: Deployments
  - name: Fine-Tune Jobs
    description: Submit, monitor, and cancel fine-tune jobs.
    x-displayName: Fine-Tune Jobs
  - name: Container Images
    description: Custom container images for deployments and jobs.
    x-displayName: Container Images
  - name: Serving Models
    description: Models registered for deployment and fine-tuning.
    x-displayName: Serving Models
  - name: Volumes
    description: Persistent storage for weights and checkpoints.
    x-displayName: Volumes
  - name: Secrets
    description: Credentials injected into your workloads.
    x-displayName: Secrets
  - name: Accelerators
    description: Available accelerator types (GPU, NPU, TPU).
    x-displayName: Accelerators
paths:
  /api/v1/llm/responses:
    get:
      tags:
        - Responses
      summary: List all responses with pagination
      description: >-
        Retrieves a paginated list of all agent responses for the authenticated
        user.
      operationId: listResponses
      parameters:
        - name: after
          in: query
          schema:
            type: string
            description: >-
              A response ID to use as a cursor for pagination. Returns responses
              that come after this ID in the list. Used for cursor-based
              pagination to fetch subsequent pages.
            examples:
              - resp_abc123
          allowEmptyValue: true
          example: resp_abc123
        - name: before
          in: query
          schema:
            type: string
            description: >-
              A response ID to use as a cursor for pagination. Returns responses
              that come before this ID in the list. Used for cursor-based
              pagination to fetch previous pages.
            examples:
              - resp_xyz789
          allowEmptyValue: true
          example: resp_xyz789
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
            description: >-
              The maximum number of responses to return per page. Must be
              between 1 and 100. Defaults to 20 items.
            examples:
              - 25
          allowEmptyValue: true
          example: 25
        - name: order
          in: query
          schema:
            enum:
              - asc
              - desc
            type: string
            default: desc
            description: >-
              The order to return the responses in by creation date. 'asc'
              returns oldest responses first, 'desc' returns newest responses
              first. Defaults to 'desc' (newest first).
            examples:
              - desc
          allowEmptyValue: true
          example: desc
        - name: X-On-Behalf-Of
          in: header
          required: false
          schema:
            type: string
          description: Optional external end-user identifier forwarded by the API gateway.
      responses:
        '200':
          description: Paginated list of responses for the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseListObject'
              example:
                object: list
                data:
                  - id: resp_abc123
                    object: response
                    created_at: 1735689600
                    completed_at: 1735689601
                    status: completed
                    error: null
                    incomplete_details: null
                    background: false
                    instructions: null
                    max_output_tokens: null
                    max_tool_calls: 30
                    metadata:
                      status: reviewed
                      reviewer: john_doe
                    model: meetkai:functionary-urdu-mini-pak
                    output:
                      - type: message
                        id: msg_abc123
                        role: assistant
                        content:
                          - type: output_text
                            text: The capital of France is Paris.
                            annotations: []
                        status: completed
                    output_text: The capital of France is Paris.
                    parallel_tool_calls: true
                    previous_response_id: null
                    reasoning:
                      effort: null
                      summary: null
                    service_tier: auto
                    store: true
                    text:
                      format:
                        type: text
                      verbosity: medium
                    tool_choice: auto
                    tools: []
                    truncation: auto
                    usage:
                      input_tokens: 8
                      input_tokens_details:
                        cached_tokens: 0
                      output_tokens: 7
                      output_tokens_details:
                        reasoning_tokens: 0
                      total_tokens: 15
                    user: null
                first_id: resp_abc123
                last_id: resp_abc123
                has_more: false
      security:
        - bearerAuth: []
      x-codeSamples:
        - lang: python
          label: Python (SDK)
          source: |-
            from meetkai_mka1 import SDK


            with SDK(
                bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
            ) as sdk:

                res = sdk.llm.responses.list(after="resp_abc123", before="resp_xyz789", limit=25, order="desc")

                # Handle response
                print(res)
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { SDK } from "@meetkai/mka1";

            const sdk = new SDK({
              bearerAuth: "<YOUR_BEARER_TOKEN_HERE>",
            });

            async function run() {
              const result = await sdk.llm.responses.list({
                after: "resp_abc123",
                before: "resp_xyz789",
                limit: 25,
              });

              console.log(result);
            }

            run();
        - lang: csharp
          label: CSharp (SDK)
          source: |-
            using MeetKai.MKA1;
            using MeetKai.MKA1.Types.Components;
            using MeetKai.MKA1.Types.Requests;

            var sdk = new SDK(bearerAuth: "<YOUR_BEARER_TOKEN_HERE>");

            ListResponsesRequest req = new ListResponsesRequest() {
                After = "resp_abc123",
                Before = "resp_xyz789",
                Limit = 25,
            };

            var res = await sdk.Llm.Responses.ListAsync(req);

            // handle response
components:
  schemas:
    ResponseListObject:
      type: object
      properties:
        object:
          const: list
          description: The object type, always 'list' for paginated list responses.
        data:
          type: array
          items:
            $ref: '#/components/schemas/ResponseObject'
          description: >-
            Array of response objects. Each response contains its status, model,
            input/output, tool usage logs, metadata, and completion information.
        first_id:
          type: string
          description: >-
            The ID of the first response in the current page. Used as a
            reference point for pagination.
        last_id:
          type: string
          description: >-
            The ID of the last response in the current page. Used as a cursor
            for fetching the next page.
        has_more:
          type: boolean
          description: >-
            Indicates whether there are more responses available beyond the
            current page. True if additional pages exist, false otherwise.
      required:
        - object
        - data
        - has_more
      description: >-
        Paginated list object containing responses with cursor-based pagination
        metadata.
    ResponseObject:
      type: object
      properties:
        id:
          type: string
        object:
          const: response
        created_at:
          type: number
        completed_at:
          anyOf:
            - type: number
            - type: 'null'
        status:
          $ref: '#/components/schemas/ResponseStatus'
        error:
          anyOf:
            - $ref: '#/components/schemas/Error'
            - type: 'null'
        incomplete_details:
          anyOf:
            - $ref: '#/components/schemas/IncompleteDetails'
            - type: 'null'
        background:
          type: boolean
        conversation:
          $ref: '#/components/schemas/Conversation'
        instructions:
          anyOf:
            - anyOf:
                - type: string
                - type: array
                  items:
                    $ref: '#/components/schemas/Item'
            - type: 'null'
        max_output_tokens:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
          examples:
            - null
        max_tool_calls:
          anyOf:
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
            - type: 'null'
        metadata:
          type: object
          propertyNames:
            type: string
            maxLength: 64
          additionalProperties:
            type: string
            maxLength: 512
        model:
          type: string
        output:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        output_text:
          type: string
        parallel_tool_calls:
          type: boolean
        previous_response_id:
          anyOf:
            - type: string
            - type: 'null'
        prompt:
          $ref: '#/components/schemas/PromptTemplate'
        prompt_cache_key:
          type: string
        reasoning:
          $ref: '#/components/schemas/ReasoningConfiguration'
        safety_identifier:
          type: string
        service_tier:
          enum:
            - auto
            - default
            - flex
            - priority
          type: string
        store:
          type: boolean
        temperature:
          type: number
          minimum: 0
          maximum: 2
        presence_penalty:
          type: number
        frequency_penalty:
          type: number
        text:
          $ref: '#/components/schemas/TextConfiguration'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        tools:
          type: array
          items:
            anyOf:
              - anyOf:
                  - $ref: '#/components/schemas/FunctionToolDefinition'
                  - type: object
                    properties:
                      type:
                        const: file_search
                      vector_store_ids:
                        type: array
                        items:
                          type: string
                      filters:
                        anyOf:
                          - $ref: '#/components/schemas/ComparisonFilter'
                          - type: object
                            properties:
                              type:
                                enum:
                                  - and
                                  - or
                                type: string
                              filters:
                                type: array
                                items:
                                  anyOf:
                                    - $ref: '#/components/schemas/ComparisonFilter'
                                    - type: object
                                      properties:
                                        type:
                                          enum:
                                            - and
                                            - or
                                          type: string
                                        filters:
                                          type: array
                                          items:
                                            anyOf:
                                              - anyOf:
                                                  - {}
                                                  - {}
                                              - type: 'null'
                                      required:
                                        - type
                                        - filters
                            required:
                              - type
                              - filters
                      max_num_results:
                        type: integer
                        minimum: 1
                        maximum: 50
                      ranking_options:
                        $ref: '#/components/schemas/RankingOptions'
                    required:
                      - type
                      - vector_store_ids
                    title: File search tool definition
                    description: >-
                      File search tool definition: Configures semantic search
                      over one or more vector stores, with optional filters,
                      ranking options, and result limits.
                  - $ref: '#/components/schemas/ComputerUseToolDefinition'
                  - $ref: '#/components/schemas/WebSearchToolDefinition'
                  - title: MCP tool definition
                    description: >-
                      MCP tool definition: Connects to an MCP server and exposes
                      its tools, with optional vault references, auth, headers,
                      allow-lists, connector ID, and approval policy.
                  - $ref: '#/components/schemas/CodeInterpreterToolDefinition'
                  - $ref: '#/components/schemas/ImageGenerationToolDefinition'
                  - $ref: '#/components/schemas/LocalShellToolDefinition'
                  - $ref: '#/components/schemas/ShellToolDefinition'
                  - $ref: '#/components/schemas/CustomToolDefinition'
                  - $ref: '#/components/schemas/WebSearchPreviewToolDefinition'
                  - $ref: '#/components/schemas/HostedToolDefinition'
                  - $ref: '#/components/schemas/SleepToolDefinition'
                  - $ref: '#/components/schemas/HistoryToolDefinition'
              - type: 'null'
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 20
        top_p:
          type: number
          minimum: 0
          maximum: 1
        truncation:
          enum:
            - auto
            - disabled
          type: string
        context_management:
          type: array
          items:
            $ref: '#/components/schemas/CompactionContextManagement'
        usage:
          $ref: '#/components/schemas/Usage'
        user:
          anyOf:
            - type: string
            - type: 'null'
      required:
        - id
        - object
        - created_at
        - completed_at
        - status
        - error
        - incomplete_details
        - background
        - instructions
        - max_output_tokens
        - max_tool_calls
        - metadata
        - model
        - output
        - parallel_tool_calls
        - previous_response_id
        - store
        - text
        - tool_choice
        - tools
        - truncation
        - usage
        - user
      examples:
        - id: resp_abc123
          object: response
          created_at: 1735689600
          completed_at: 1735689601
          status: completed
          error: null
          incomplete_details: null
          background: false
          instructions: null
          max_output_tokens: null
          max_tool_calls: 30
          metadata: {}
          model: meetkai:functionary-urdu-mini-pak
          output:
            - type: message
              id: msg_abc123
              role: assistant
              content:
                - type: output_text
                  text: The capital of France is Paris.
                  annotations: []
              status: completed
          output_text: The capital of France is Paris.
          parallel_tool_calls: true
          previous_response_id: null
          reasoning:
            effort: null
            summary: null
          service_tier: auto
          store: true
          text:
            format:
              type: text
            verbosity: medium
          tool_choice: auto
          tools: []
          truncation: auto
          usage:
            input_tokens: 8
            input_tokens_details:
              cached_tokens: 0
            output_tokens: 7
            output_tokens_details:
              reasoning_tokens: 0
            total_tokens: 15
          user: null
      example:
        id: resp_abc123
        object: response
        created_at: 1735689600
        completed_at: 1735689601
        status: completed
        error: null
        incomplete_details: null
        background: false
        instructions: null
        max_output_tokens: null
        max_tool_calls: 30
        metadata: {}
        model: meetkai:functionary-urdu-mini-pak
        output:
          - type: message
            id: msg_abc123
            role: assistant
            content:
              - type: output_text
                text: The capital of France is Paris.
                annotations: []
            status: completed
        output_text: The capital of France is Paris.
        parallel_tool_calls: true
        previous_response_id: null
        reasoning:
          effort: null
          summary: null
        service_tier: auto
        store: true
        text:
          format:
            type: text
          verbosity: medium
        tool_choice: auto
        tools: []
        truncation: auto
        usage:
          input_tokens: 8
          input_tokens_details:
            cached_tokens: 0
          output_tokens: 7
          output_tokens_details:
            reasoning_tokens: 0
          total_tokens: 15
        user: null
    ResponseStatus:
      enum:
        - completed
        - failed
        - in_progress
        - cancelled
        - queued
        - incomplete
      type: string
      description: >-
        The overall status of the response generation. 'completed' means
        successfully finished, 'failed' means error occurred, 'in_progress'
        means currently processing, 'cancelled' means user-cancelled, 'queued'
        means waiting to start, 'incomplete' means partial completion.
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
    IncompleteDetails:
      type: object
      properties:
        type:
          type: string
        reason:
          type: string
      required:
        - reason
    Conversation:
      type: object
      properties:
        id:
          type: string
      required:
        - id
    Item:
      anyOf:
        - $ref: '#/components/schemas/InputMessage'
        - $ref: '#/components/schemas/OutputMessage'
        - $ref: '#/components/schemas/OutputAudioItem'
        - $ref: '#/components/schemas/FileSearchToolCall'
        - $ref: '#/components/schemas/ComputerToolCall'
        - $ref: '#/components/schemas/ComputerToolCallOutput'
        - $ref: '#/components/schemas/WebSearchToolCall'
        - $ref: '#/components/schemas/FunctionToolCall'
        - $ref: '#/components/schemas/FunctionToolCallOutput'
        - $ref: '#/components/schemas/Reasoning'
        - $ref: '#/components/schemas/ImageGenerationCall'
        - $ref: '#/components/schemas/CodeInterpreterToolCall'
        - $ref: '#/components/schemas/LocalShellCall'
        - $ref: '#/components/schemas/LocalShellCallOutput'
        - $ref: '#/components/schemas/ShellCall'
        - $ref: '#/components/schemas/ShellCallOutput'
        - $ref: '#/components/schemas/MCPListTools'
        - $ref: '#/components/schemas/MCPApprovalRequest'
        - $ref: '#/components/schemas/MCPApprovalResponse'
        - $ref: '#/components/schemas/MCPToolCall'
        - $ref: '#/components/schemas/CustomToolCall'
        - $ref: '#/components/schemas/CustomToolCallOutput'
        - $ref: '#/components/schemas/ItemReference'
        - $ref: '#/components/schemas/ResponseCompactionItem'
    PromptTemplate:
      type: object
      properties:
        id:
          type: string
        variables:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            anyOf:
              - type: string
              - {}
        version:
          type: string
      required:
        - id
    ReasoningConfiguration:
      type: object
      properties:
        effort:
          anyOf:
            - enum:
                - none
                - minimal
                - low
                - medium
                - high
                - xhigh
              type: string
            - type: 'null'
        summary:
          anyOf:
            - enum:
                - auto
                - concise
                - detailed
              type: string
            - type: 'null'
      required:
        - effort
        - summary
    TextConfiguration:
      type: object
      properties:
        format:
          $ref: '#/components/schemas/ResponseFormat'
        verbosity:
          enum:
            - low
            - medium
            - high
          type: string
          default: medium
      required:
        - format
    ToolChoice:
      anyOf:
        - $ref: '#/components/schemas/ToolChoiceMode'
        - $ref: '#/components/schemas/AllowedTools'
        - $ref: '#/components/schemas/HostedToolChoice'
        - $ref: '#/components/schemas/FunctionToolChoice'
        - $ref: '#/components/schemas/MCPToolChoice'
        - $ref: '#/components/schemas/CustomToolChoice'
    FunctionToolDefinition:
      type: object
      properties:
        type:
          const: function
        name:
          type: string
        parameters:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        strict:
          type: boolean
        description:
          type: string
        defer_loading:
          type: boolean
      required:
        - type
        - name
        - parameters
        - strict
      title: Function tool definition
      description: >-
        Function tool definition: Defines a callable function tool. Provide a
        tool name and parameters schema, with optional description and deferred
        loading.
    ComparisonFilter:
      type: object
      properties:
        type:
          enum:
            - eq
            - ne
            - gt
            - gte
            - lt
            - lte
          type: string
        key:
          type: string
        value:
          anyOf:
            - type: string
            - type: number
            - type: boolean
      required:
        - type
        - key
        - value
    RankingOptions:
      type: object
      properties:
        ranker:
          type: string
        score_threshold:
          type: number
    ComputerUseToolDefinition:
      type: object
      properties:
        type:
          const: computer_use_preview
        display_height:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        display_width:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        environment:
          type: string
      required:
        - type
        - display_height
        - display_width
        - environment
      title: Computer use tool definition
      description: >-
        Computer use tool definition: Configures the computer-use preview tool,
        including required display dimensions and runtime environment.
    WebSearchToolDefinition:
      type: object
      properties:
        type:
          enum:
            - web_search
            - web_search_2025_08_26
          type: string
        filters:
          $ref: '#/components/schemas/WebSearchFilters'
        search_context_size:
          enum:
            - low
            - medium
            - high
          type: string
          default: medium
        user_location:
          $ref: '#/components/schemas/UserLocation'
      required:
        - type
      title: Web search tool definition
      description: >-
        Web search tool definition: Enables web search with optional domain
        filters, search context size, and approximate user location.
    CodeInterpreterToolDefinition:
      type: object
      properties:
        type:
          const: code_interpreter
        container:
          anyOf:
            - type: string
            - $ref: '#/components/schemas/CodeInterpreterContainerAuto'
      required:
        - type
        - container
      title: Code interpreter tool definition
      description: >-
        Code interpreter tool definition: Enables code execution. Provide an
        explicit container ID or auto container configuration with optional file
        IDs and memory limit.
    ImageGenerationToolDefinition:
      type: object
      properties:
        type:
          const: image_generation
        background:
          enum:
            - transparent
            - opaque
            - auto
          type: string
          default: auto
        input_fidelity:
          enum:
            - high
            - low
          type: string
          default: low
        input_image_mask:
          $ref: '#/components/schemas/InputImageMask'
        model:
          type: string
          minLength: 1
          default: auto
          description: >-
            The model to use for image generation. Defaults to 'auto' for
            automatic model selection.
        moderation:
          enum:
            - auto
            - low
            - none
          type: string
          default: auto
        output_compression:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          default: 100
        output_format:
          enum:
            - png
            - webp
            - jpeg
          type: string
          default: png
        partial_images:
          type: integer
          minimum: 0
          maximum: 3
          default: 0
        quality:
          enum:
            - low
            - medium
            - high
            - auto
          type: string
          default: auto
        size:
          enum:
            - 1024x1024
            - 1024x1536
            - 1536x1024
            - auto
          type: string
          default: auto
        prompt_guard:
          type: string
          description: >-
            Adds a guardrail to prevent the model from generating content that
            is not allowed.
      required:
        - type
      title: Image generation tool definition
      description: >-
        Image generation tool definition: Enables image generation and
        configures output settings like model, quality, size, format,
        moderation, and optional masking.
    LocalShellToolDefinition:
      type: object
      properties:
        type:
          const: local_shell
      required:
        - type
      title: Local shell tool definition
      description: 'Local shell tool definition: Enables the local shell execution tool.'
    ShellToolDefinition:
      type: object
      properties:
        type:
          const: shell
        environment:
          $ref: '#/components/schemas/ShellEnvironment'
          description: Container environment configuration. Defaults to container_auto.
      required:
        - type
      title: Shell tool definition
      description: >-
        Shell tool definition: Enables shell command execution in a managed
        container environment.
    CustomToolDefinition:
      type: object
      properties:
        type:
          const: custom
        name:
          type: string
        description:
          type: string
        format:
          $ref: '#/components/schemas/CustomToolFormat'
      required:
        - type
        - name
      title: Custom tool definition
      description: >-
        Custom tool definition: Defines a custom tool by name, with optional
        description and optional output format constraints.
    WebSearchPreviewToolDefinition:
      type: object
      properties:
        type:
          enum:
            - web_search_preview
            - web_search_preview_2025_03_11
          type: string
        search_context_size:
          enum:
            - low
            - medium
            - high
          type: string
        user_location:
          $ref: '#/components/schemas/UserLocation'
      required:
        - type
      title: Web search preview tool definition
      description: >-
        Web search preview tool definition: Enables the preview web search tool
        variant with optional context size and user location.
    HostedToolDefinition:
      type: object
      properties:
        type:
          enum:
            - file_search
            - web_search_preview
            - computer_use_preview
            - code_interpreter
            - image_generation
          type: string
      required:
        - type
      title: Hosted tool definition
      description: >-
        Hosted tool definition: Shorthand hosted-tool selector for built-in tool
        types. This is a compatibility form that overlaps with the detailed
        per-tool schemas.
    SleepToolDefinition:
      type: object
      properties:
        type:
          const: sleep
      required:
        - type
      title: Sleep tool definition
      description: >-
        Sleep tool definition: Allows an agent to pause the current response
        briefly and resume later or when woken.
    HistoryToolDefinition:
      type: object
      properties:
        type:
          const: history
      required:
        - type
      title: History tool definition
      description: >-
        History tool definition: Enables the internal conversation-history
        retrieval tool for semantic lookup of past interactions.
    CompactionContextManagement:
      type: object
      properties:
        type:
          const: compaction
        compact_threshold:
          type: integer
          minimum: 1000
          maximum: 9007199254740991
          description: >-
            The token threshold above which conversation context should be
            compacted. Must be at least 1000.
      required:
        - type
        - compact_threshold
    Usage:
      type: object
      properties:
        input_tokens:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        input_tokens_details:
          $ref: '#/components/schemas/InputTokensDetails'
        output_tokens:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        output_tokens_details:
          $ref: '#/components/schemas/OutputTokensDetails'
        total_tokens:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - input_tokens
        - input_tokens_details
        - output_tokens
        - output_tokens_details
        - total_tokens
    InputMessage:
      type: object
      properties:
        type:
          const: message
          description: The item type identifier. Always 'message' for message items.
        role:
          enum:
            - user
            - assistant
            - system
            - developer
          type: string
          description: >-
            The role of the message sender (user, assistant, system, or
            developer).
        content:
          anyOf:
            - type: string
            - $ref: '#/components/schemas/InputMessageContent'
          description: >-
            The message content. Can be a simple text string or an array of
            multimodal content items (text, images, files, audio).
        status:
          $ref: '#/components/schemas/Status'
          description: >-
            The processing status of this message. Optional - indicates if the
            message is in_progress, completed, or incomplete.
        id:
          type: string
          default: msg_aa87e2b1112a455b8deabed784372198
      required:
        - role
        - content
      title: Input message item
      description: >-
        Input message item: A message with role and content. Use this for user,
        assistant, system, or developer turns in structured inputs.
    OutputMessage:
      type: object
      properties:
        type:
          const: message
          description: The item type identifier for message outputs.
        id:
          type: string
          description: The unique identifier for this output message.
        role:
          const: assistant
          description: >-
            The role of the message sender. Always 'assistant' for
            model-generated messages.
        content:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/OutputText'
              - $ref: '#/components/schemas/Refusal'
          description: >-
            Array of content items in the assistant's response. Can contain text
            outputs or refusal messages.
        status:
          enum:
            - in_progress
            - completed
            - incomplete
          type: string
          description: >-
            The processing status of this message (in_progress, completed, or
            incomplete).
        phase:
          enum:
            - commentary
            - final_answer
          type: string
          description: >-
            Labels an assistant message as intermediate commentary or the final
            answer.
      required:
        - type
        - id
        - role
        - content
        - status
      title: Output message item
      description: >-
        Output message item: An assistant message containing generated text
        content or refusal content.
    OutputAudioItem:
      type: object
      properties:
        type:
          const: output_audio
          description: The content type identifier for audio output.
        data:
          type: string
          description: Base64-encoded audio data.
        transcript:
          type: string
          description: The text transcript that was synthesized into audio.
        id:
          type: string
          description: The unique identifier for this output audio item.
        status:
          enum:
            - in_progress
            - completed
            - incomplete
          type: string
          description: The processing status of this audio item.
      required:
        - type
        - data
        - transcript
        - id
        - status
      title: Output audio item
      description: >-
        Output audio item: Audio content synthesized from the model's text
        response via TTS.
    FileSearchToolCall:
      type: object
      properties:
        type:
          const: file_search_call
        id:
          type: string
        queries:
          type: array
          items:
            type: string
        status:
          enum:
            - in_progress
            - searching
            - completed
            - incomplete
            - failed
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/FileSearchResult'
      required:
        - type
        - id
        - queries
        - status
      title: File search call item
      description: >-
        File search call item: A tool-call record for semantic file search,
        including query terms, status, and optional results.
    ComputerToolCall:
      type: object
      properties:
        type:
          const: computer_call
        id:
          type: string
        call_id:
          type: string
        action:
          $ref: '#/components/schemas/ComputerAction'
        pending_safety_checks:
          type: array
          items:
            $ref: '#/components/schemas/PendingSafetyCheck'
        status:
          $ref: '#/components/schemas/Status'
      required:
        - type
        - id
        - call_id
        - action
        - pending_safety_checks
        - status
      title: Computer call item
      description: >-
        Computer call item: A computer-use tool-call step with the selected UI
        action and safety-check state.
    ComputerToolCallOutput:
      type: object
      properties:
        type:
          const: computer_call_output
        call_id:
          type: string
        output:
          $ref: '#/components/schemas/ComputerScreenshot'
        acknowledged_safety_checks:
          type: array
          items:
            $ref: '#/components/schemas/AcknowledgedSafetyCheck'
        id:
          type: string
        status:
          $ref: '#/components/schemas/Status'
      required:
        - type
        - call_id
        - output
      title: Computer call output item
      description: >-
        Computer call output item: Output emitted by a computer-use tool call,
        typically including screenshot data.
    WebSearchToolCall:
      type: object
      properties:
        type:
          const: web_search_call
        id:
          type: string
        action:
          $ref: '#/components/schemas/WebSearchAction'
        status:
          type: string
      required:
        - type
        - id
        - action
        - status
      title: Web search call item
      description: >-
        Web search call item: A web-search tool-call record containing the
        executed action and status.
    FunctionToolCall:
      type: object
      properties:
        type:
          const: function_call
        arguments:
          type: string
        call_id:
          type: string
        name:
          type: string
        id:
          type: string
        status:
          $ref: '#/components/schemas/Status'
      required:
        - type
        - arguments
        - call_id
        - name
      title: Function call item
      description: >-
        Function call item: A call to a function tool, including function name
        and JSON-string arguments.
    FunctionToolCallOutput:
      type: object
      properties:
        type:
          const: function_call_output
        call_id:
          type: string
        output:
          type: string
        id:
          type: string
        status:
          $ref: '#/components/schemas/Status'
      required:
        - type
        - call_id
        - output
      title: Function call output item
      description: >-
        Function call output item: The output payload returned from a function
        tool call.
    Reasoning:
      type: object
      properties:
        type:
          const: reasoning
        id:
          type: string
        summary:
          type: array
          items:
            $ref: '#/components/schemas/SummaryText'
        content:
          type: array
          items:
            $ref: '#/components/schemas/ReasoningText'
        encrypted_content:
          anyOf:
            - type: string
            - type: 'null'
        status:
          anyOf:
            - $ref: '#/components/schemas/Status'
            - type: 'null'
      required:
        - type
        - id
        - summary
      title: Reasoning item
      description: >-
        Reasoning item: Model reasoning metadata, including summary text and
        optional detailed reasoning content.
    ImageGenerationCall:
      type: object
      properties:
        type:
          const: image_generation_call
        id:
          type: string
        status:
          type: string
        result:
          type: string
        background:
          type: string
        output_format:
          type: string
        quality:
          type: string
        size:
          type: string
        revised_prompt:
          type: string
      required:
        - type
        - id
        - status
        - result
      title: Image generation call item
      description: >-
        Image generation call item: A tool-call record for image generation,
        including status and result URL.
    CodeInterpreterToolCall:
      type: object
      properties:
        type:
          const: code_interpreter_call
        id:
          type: string
        code:
          anyOf:
            - type: string
            - type: 'null'
        container_id:
          type: string
        outputs:
          anyOf:
            - type: array
              items:
                $ref: '#/components/schemas/CodeInterpreterOutput'
            - type: 'null'
        status:
          enum:
            - in_progress
            - completed
            - incomplete
            - interpreting
            - failed
          type: string
      required:
        - type
        - id
        - code
        - container_id
        - outputs
        - status
      title: Code interpreter call item
      description: >-
        Code interpreter call item: A tool-call record for code execution,
        including code, container, outputs, and status.
    LocalShellCall:
      type: object
      properties:
        type:
          const: local_shell_call
        id:
          type: string
        call_id:
          type: string
        action:
          $ref: '#/components/schemas/LocalShellAction'
        status:
          type: string
      required:
        - type
        - id
        - call_id
        - action
        - status
      title: Local shell call item
      description: >-
        Local shell call item: A local-shell execution request with command
        details and execution status.
    LocalShellCallOutput:
      type: object
      properties:
        type:
          const: local_shell_call_output
        id:
          type: string
        output:
          type: string
        status:
          $ref: '#/components/schemas/Status'
      required:
        - type
        - id
        - output
      title: Local shell call output item
      description: >-
        Local shell call output item: The captured output payload returned by a
        local-shell tool call.
    ShellCall:
      type: object
      properties:
        type:
          const: shell_call
        id:
          type: string
        call_id:
          type: string
        action:
          $ref: '#/components/schemas/ShellCallAction'
        status:
          enum:
            - in_progress
            - completed
            - incomplete
          type: string
      required:
        - type
        - id
        - call_id
        - action
        - status
      title: Shell call item
      description: >-
        Shell call item: A hosted-container shell execution request with a
        command and status.
    ShellCallOutput:
      type: object
      properties:
        type:
          const: shell_call_output
        id:
          type: string
        call_id:
          type: string
        output:
          type: object
          properties:
            stdout:
              type: string
              description: Standard output from the command.
            stderr:
              type: string
              description: Standard error from the command.
            outcome:
              type: object
              properties:
                type:
                  enum:
                    - exit
                    - timeout
                  type: string
                  description: Whether the command exited normally or timed out.
                exit_code:
                  anyOf:
                    - type: integer
                      minimum: -9007199254740991
                      maximum: 9007199254740991
                    - type: 'null'
                  description: Exit code of the command, or null if timed out.
              required:
                - type
                - exit_code
          required:
            - stdout
            - stderr
            - outcome
          description: Result of the executed command.
        status:
          $ref: '#/components/schemas/Status'
      required:
        - type
        - id
        - call_id
        - output
      title: Shell call output item
      description: >-
        Shell call output item: The captured output from a hosted-container
        shell tool call.
    MCPListTools:
      type: object
      properties:
        type:
          const: mcp_list_tools
        id:
          type: string
        server_label:
          type: string
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPTool'
        error:
          type: string
      required:
        - type
        - id
        - server_label
        - tools
      title: MCP list tools item
      description: >-
        MCP list tools item: Result of discovering available tools from an MCP
        server.
    MCPApprovalRequest:
      type: object
      properties:
        type:
          const: mcp_approval_request
        id:
          type: string
        arguments:
          type: string
        name:
          type: string
        server_label:
          type: string
      required:
        - type
        - id
        - arguments
        - name
        - server_label
      title: MCP approval request item
      description: >-
        MCP approval request item: A request to approve or deny execution of an
        MCP tool call.
    MCPApprovalResponse:
      type: object
      properties:
        type:
          const: mcp_approval_response
        approval_request_id:
          type: string
        approve:
          type: boolean
        id:
          type: string
        reason:
          type: string
      required:
        - type
        - approval_request_id
        - approve
      title: MCP approval response item
      description: >-
        MCP approval response item: The decision payload for a prior MCP
        approval request.
    MCPToolCall:
      type: object
      properties:
        type:
          const: mcp_call
        id:
          type: string
        arguments:
          type: string
        name:
          type: string
        server_label:
          type: string
        error:
          type: string
        output:
          type: string
      required:
        - type
        - id
        - arguments
        - name
        - server_label
      title: MCP call item
      description: >-
        MCP call item: A direct call record for an MCP tool, including request
        arguments and optional output/error.
    CustomToolCall:
      type: object
      properties:
        type:
          const: custom_tool_call
        call_id:
          type: string
        input:
          type: string
        name:
          type: string
        id:
          type: string
      required:
        - type
        - call_id
        - input
        - name
      title: Custom tool call item
      description: >-
        Custom tool call item: A call record for a custom tool with input
        payload and tool name.
    CustomToolCallOutput:
      type: object
      properties:
        type:
          const: custom_tool_call_output
        call_id:
          type: string
        output:
          type: string
        id:
          type: string
      required:
        - type
        - call_id
        - output
      title: Custom tool call output item
      description: >-
        Custom tool call output item: The output payload returned by a custom
        tool call.
    ItemReference:
      type: object
      properties:
        type:
          const: item_reference
          default: item_reference
        id:
          type: string
      required:
        - id
      title: Item reference item
      description: 'Item reference item: A pointer to another response item by ID.'
    ResponseCompactionItem:
      type: object
      properties:
        type:
          const: compaction
        id:
          type: string
        content:
          type: string
          description: The compacted/summarized conversation content.
        encrypted_content:
          type: string
          description: Optional encrypted content for OpenAI API compatibility.
        created_by:
          type: string
          description: The model that created this compaction.
      required:
        - type
        - id
        - content
      title: Compaction item
      description: >-
        Compaction item: A condensed summary of prior conversation history to
        reduce context size.
    ResponseFormat:
      anyOf:
        - $ref: '#/components/schemas/TextResponseFormat'
        - $ref: '#/components/schemas/JSONSchemaResponseFormat'
        - $ref: '#/components/schemas/JSONObjectResponseFormat'
    ToolChoiceMode:
      enum:
        - none
        - auto
        - required
      type: string
      title: Tool choice mode
      description: >-
        Tool choice mode: Selects how the model decides tool usage. Use none,
        auto, or required.
    AllowedTools:
      type: object
      properties:
        type:
          const: allowed_tools
        mode:
          enum:
            - auto
            - required
          type: string
        tools:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
              name:
                type: string
              server_label:
                type: string
            required:
              - type
      required:
        - type
        - mode
        - tools
      title: Allowed tools tool choice
      description: >-
        Allowed tools tool choice: Restricts tool use to a provided list and
        sets whether tool use is optional (auto) or mandatory (required).
    HostedToolChoice:
      type: object
      properties:
        type:
          enum:
            - file_search
            - web_search_preview
            - computer_use_preview
            - code_interpreter
            - image_generation
          type: string
      required:
        - type
      title: Hosted tool choice
      description: 'Hosted tool choice: Forces a specific built-in hosted tool type.'
    FunctionToolChoice:
      type: object
      properties:
        type:
          const: function
        name:
          type: string
      required:
        - type
        - name
      title: Function tool choice
      description: 'Function tool choice: Forces a specific function tool by name.'
    MCPToolChoice:
      type: object
      properties:
        type:
          const: mcp
        server_label:
          type: string
        name:
          type: string
      required:
        - type
        - server_label
      title: MCP tool choice
      description: >-
        MCP tool choice: Forces an MCP server, optionally narrowed to a specific
        MCP tool name.
    CustomToolChoice:
      type: object
      properties:
        type:
          const: custom
        name:
          type: string
      required:
        - type
        - name
      title: Custom tool choice
      description: 'Custom tool choice: Forces a specific custom tool by name.'
    WebSearchFilters:
      type: object
      properties:
        allowed_domains:
          type: array
          items:
            type: string
          default: []
    UserLocation:
      type: object
      properties:
        type:
          const: approximate
          default: approximate
        city:
          type: string
        country:
          type: string
        region:
          type: string
        timezone:
          type: string
    CodeInterpreterContainerAuto:
      type: object
      properties:
        type:
          const: auto
        file_ids:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
        memory_limit:
          anyOf:
            - enum:
                - 1g
                - 4g
                - 16g
                - 64g
              type: string
            - type: 'null'
      required:
        - type
    InputImageMask:
      type: object
      properties:
        file_id:
          type: string
        image_url:
          type: string
    ShellEnvironment:
      anyOf:
        - $ref: '#/components/schemas/ShellEnvironmentContainerAuto'
        - $ref: '#/components/schemas/ShellEnvironmentContainerReference'
      discriminator:
        propertyName: type
        mapping:
          container_auto:
            $ref: '#/components/schemas/ShellEnvironmentContainerAuto'
          container_reference:
            $ref: '#/components/schemas/ShellEnvironmentContainerReference'
    CustomToolFormat:
      anyOf:
        - $ref: '#/components/schemas/TextFormat'
        - $ref: '#/components/schemas/GrammarFormat'
    InputTokensDetails:
      type: object
      properties:
        cached_tokens:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - cached_tokens
    OutputTokensDetails:
      type: object
      properties:
        reasoning_tokens:
          type: integer
          minimum: 0
          maximum: 9007199254740991
      required:
        - reasoning_tokens
    InputMessageContent:
      type: array
      items:
        anyOf:
          - type: string
          - $ref: '#/components/schemas/InputText'
          - $ref: '#/components/schemas/InputImage'
          - $ref: '#/components/schemas/InputFile'
          - $ref: '#/components/schemas/InputAudio'
          - $ref: '#/components/schemas/OutputText'
          - $ref: '#/components/schemas/Refusal'
      description: >-
        Array of content items for a multimodal message. Can contain text
        strings, text objects, images, files, audio, or output text blocks from
        previous assistant turns.
    Status:
      enum:
        - in_progress
        - completed
        - incomplete
      type: string
      description: >-
        The processing status of an individual item. 'in_progress' means
        currently processing, 'completed' means finished successfully,
        'incomplete' means processing stopped before completion.
    OutputText:
      type: object
      properties:
        type:
          const: output_text
          description: The content type identifier for text output.
        text:
          type: string
          description: The generated text content from the model.
        annotations:
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/FileCitation'
              - $ref: '#/components/schemas/URLCitation'
              - $ref: '#/components/schemas/ContainerFileCitation'
              - $ref: '#/components/schemas/FilePath'
          default: []
          description: >-
            Array of annotations providing citations and references for the
            text. Used to attribute sources and reference files mentioned in the
            output.
        logprobs:
          type: array
          items:
            $ref: '#/components/schemas/LogProb'
      required:
        - type
        - text
      description: >-
        Text content output from the model with optional annotations for
        citations and file references.
    Refusal:
      type: object
      properties:
        type:
          const: refusal
          description: The content type identifier for refusal responses.
        refusal:
          type: string
          description: >-
            The refusal message explaining why the model declined to respond to
            the request.
      required:
        - type
        - refusal
      description: >-
        Refusal response when the model declines to answer due to safety
        policies, content moderation, or capability limitations.
    FileSearchResult:
      type: object
      properties:
        attributes:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            anyOf:
              - type: string
              - type: boolean
              - type: number
        file_id:
          type: string
        filename:
          type: string
        score:
          type: number
        text:
          type: string
    ComputerAction:
      anyOf:
        - $ref: '#/components/schemas/ClickAction'
        - $ref: '#/components/schemas/DoubleClickAction'
        - $ref: '#/components/schemas/DragAction'
        - $ref: '#/components/schemas/KeyPressAction'
        - $ref: '#/components/schemas/MoveAction'
        - $ref: '#/components/schemas/ScreenshotAction'
        - $ref: '#/components/schemas/ScrollAction'
        - $ref: '#/components/schemas/TypeAction'
        - $ref: '#/components/schemas/WaitAction'
    PendingSafetyCheck:
      type: object
      properties:
        code:
          type: string
        id:
          type: string
        message:
          type: string
      required:
        - code
        - id
        - message
    ComputerScreenshot:
      type: object
      properties:
        type:
          const: computer_screenshot
        file_id:
          type: string
        image_url:
          type: string
      required:
        - type
    AcknowledgedSafetyCheck:
      type: object
      properties:
        id:
          type: string
        code:
          type: string
        message:
          type: string
      required:
        - id
    WebSearchAction:
      anyOf:
        - $ref: '#/components/schemas/SearchAction'
        - $ref: '#/components/schemas/OpenPageAction'
        - $ref: '#/components/schemas/FindAction'
    SummaryText:
      type: object
      properties:
        type:
          const: summary_text
        text:
          type: string
      required:
        - type
        - text
    ReasoningText:
      type: object
      properties:
        type:
          const: reasoning_text
        text:
          type: string
      required:
        - type
        - text
    CodeInterpreterOutput:
      anyOf:
        - $ref: '#/components/schemas/CodeInterpreterOutputLogs'
        - $ref: '#/components/schemas/CodeInterpreterOutputImage'
    LocalShellAction:
      type: object
      properties:
        type:
          const: exec
        command:
          type: array
          items:
            type: string
        env:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        timeout_ms:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        user:
          type: string
        working_directory:
          type: string
      required:
        - type
        - command
        - env
    ShellCallAction:
      type: object
      properties:
        type:
          const: exec
        command:
          type: string
          description: Shell command to execute.
        timeout_ms:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Command timeout in milliseconds.
        max_output_length:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Maximum output characters.
      required:
        - type
    MCPTool:
      type: object
      properties:
        name:
          type: string
        input_schema:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        annotations:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        description:
          type: string
      required:
        - name
        - input_schema
    TextResponseFormat:
      type: object
      properties:
        type:
          const: text
      required:
        - type
    JSONSchemaResponseFormat:
      type: object
      properties:
        type:
          const: json_schema
        name:
          type: string
          maxLength: 64
          pattern: ^[a-zA-Z0-9_-]+$
        schema:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
        description:
          type: string
        strict:
          type: boolean
          default: false
      required:
        - type
        - name
        - schema
    JSONObjectResponseFormat:
      type: object
      properties:
        type:
          const: json_object
      required:
        - type
    ShellEnvironmentContainerAuto:
      type: object
      properties:
        type:
          const: container_auto
        network_policy:
          $ref: '#/components/schemas/ShellNetworkPolicy'
          description: Network policy restricting outbound access.
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillEntry'
          description: Skills to inject into the container's /skills directory.
        memory_stores:
          type: array
          items:
            $ref: '#/components/schemas/MemoryStoreMount'
          description: Memory stores to mount into the container under /mnt/memory.
      required:
        - type
    ShellEnvironmentContainerReference:
      type: object
      properties:
        type:
          const: container_reference
        container_id:
          type: string
          description: ID of an existing container to reuse.
        network_policy:
          $ref: '#/components/schemas/ShellNetworkPolicy'
          description: Network policy restricting outbound access.
        skills:
          type: array
          items:
            $ref: '#/components/schemas/SkillEntry'
          description: Skills to inject into the container's /skills directory.
        memory_stores:
          type: array
          items:
            $ref: '#/components/schemas/MemoryStoreMount'
          description: Memory stores to mount into the container under /mnt/memory.
      required:
        - type
        - container_id
    TextFormat:
      type: object
      properties:
        type:
          const: text
      required:
        - type
    GrammarFormat:
      type: object
      properties:
        type:
          const: grammar
        definition:
          type: string
        syntax:
          enum:
            - lark
            - regex
          type: string
      required:
        - type
        - definition
        - syntax
    InputText:
      type: object
      properties:
        type:
          const: input_text
          description: The content type identifier for text input.
        text:
          type: string
          description: The text content to send to the model.
      required:
        - type
        - text
      title: Input text content item
      description: 'Input text content item: Plain text content to send to the model.'
    InputImage:
      type: object
      properties:
        type:
          const: input_image
          description: The content type identifier for image input.
        detail:
          enum:
            - high
            - low
            - auto
          type: string
          default: auto
          description: >-
            The detail level for image processing. 'high' for detailed analysis
            (higher cost), 'low' for basic analysis (lower cost), 'auto' lets
            the model choose based on image size. Defaults to 'auto'.
        file_id:
          type: string
          description: >-
            The ID of a previously uploaded file containing the image. Mutually
            exclusive with image_url.
        image_url:
          type: string
          description: >-
            A URL or data URI pointing to the image. Mutually exclusive with
            file_id.
      required:
        - type
      title: Input image content item
      description: >-
        Input image content item: Image input for multimodal analysis. Provide
        either file_id or image_url.
    InputFile:
      type: object
      properties:
        type:
          const: input_file
          description: The content type identifier for file input.
        file_data:
          type: string
          description: >-
            Base64-encoded file data for inline file uploads. Mutually exclusive
            with file_id and file_url.
        file_id:
          type: string
          description: >-
            The ID of a previously uploaded file. Mutually exclusive with
            file_data and file_url.
        file_url:
          type: string
          description: >-
            A URL pointing to the file to process. Mutually exclusive with
            file_data and file_id.
        filename:
          type: string
          description: The original filename for display and reference purposes.
      required:
        - type
      title: Input file content item
      description: >-
        Input file content item: File input for document processing. Provide one
        of file_data, file_id, or file_url.
    InputAudio:
      type: object
      properties:
        type:
          const: input_audio
          description: The content type identifier for audio input.
        input_audio:
          type: object
          properties:
            data:
              type: string
              description: Base64-encoded audio data to send to the model.
            format:
              enum:
                - mp3
                - wav
              type: string
              description: The audio format/codec. Supported formats are 'mp3' and 'wav'.
          required:
            - data
            - format
          description: The audio data and its format.
      required:
        - type
        - input_audio
      title: Input audio content item
      description: >-
        Input audio content item: Audio input for speech processing and
        transcription.
    FileCitation:
      type: object
      properties:
        type:
          const: file_citation
          description: The annotation type identifier for file citations.
        file_id:
          type: string
          description: The ID of the file being cited.
        filename:
          type: string
          description: The name of the file being cited.
        index:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: The character index in the output text where this citation applies.
      required:
        - type
        - file_id
        - filename
        - index
      description: >-
        Annotation for citing a specific file in the model's output. Used when
        the model references information from a file.
    URLCitation:
      type: object
      properties:
        type:
          const: url_citation
          description: The annotation type identifier for URL citations.
        end_index:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: The character index where the cited text ends in the output.
        start_index:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: The character index where the cited text begins in the output.
        title:
          type: string
          description: The title of the web page or resource being cited.
        url:
          type: string
          description: The URL of the web resource being cited.
      required:
        - type
        - end_index
        - start_index
        - title
        - url
      description: >-
        Annotation for citing a web URL in the model's output. Used when the
        model references information from web sources.
    ContainerFileCitation:
      type: object
      properties:
        type:
          const: container_file_citation
          description: The annotation type identifier for container file citations.
        container_id:
          type: string
          description: >-
            The ID of the container (e.g., code interpreter container) where the
            file resides.
        end_index:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: The character index where the cited text ends in the output.
        file_id:
          type: string
          description: The ID of the file within the container being cited.
        filename:
          type: string
          description: The name of the file being cited.
        start_index:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: The character index where the cited text begins in the output.
      required:
        - type
        - container_id
        - end_index
        - file_id
        - filename
        - start_index
      description: >-
        Annotation for citing a file within a specific container (like a code
        interpreter sandbox). Used when the model references files generated
        within tool executions.
    FilePath:
      type: object
      properties:
        type:
          const: file_path
          description: The annotation type identifier for file path references.
        file_id:
          type: string
          description: The ID of the file being referenced.
        index:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: >-
            The character index in the output text where this file path
            reference applies.
      required:
        - type
        - file_id
        - index
      description: >-
        Annotation for referencing a file path in the model's output. Used when
        the model mentions specific files.
    LogProb:
      type: object
      properties:
        token:
          type: string
        logprob:
          type: number
        bytes:
          type: array
          items:
            type: number
        top_logprobs:
          type: array
          items:
            $ref: '#/components/schemas/TopLogProb'
      required:
        - token
        - logprob
        - bytes
        - top_logprobs
    ClickAction:
      type: object
      properties:
        type:
          const: click
        button:
          enum:
            - left
            - right
            - wheel
            - back
            - forward
          type: string
        x:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        'y':
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - type
        - button
        - x
        - 'y'
    DoubleClickAction:
      type: object
      properties:
        type:
          const: double_click
        x:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        'y':
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - type
        - x
        - 'y'
    DragAction:
      type: object
      properties:
        type:
          const: drag
        path:
          type: array
          items:
            type: object
            properties:
              x:
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
              'y':
                type: integer
                minimum: -9007199254740991
                maximum: 9007199254740991
            required:
              - x
              - 'y'
      required:
        - type
        - path
    KeyPressAction:
      type: object
      properties:
        type:
          const: keypress
        keys:
          type: array
          items:
            type: string
      required:
        - type
        - keys
    MoveAction:
      type: object
      properties:
        type:
          const: move
        x:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        'y':
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - type
        - x
        - 'y'
    ScreenshotAction:
      type: object
      properties:
        type:
          const: screenshot
      required:
        - type
    ScrollAction:
      type: object
      properties:
        type:
          const: scroll
        scroll_x:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        scroll_y:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        x:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        'y':
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
      required:
        - type
        - scroll_x
        - scroll_y
        - x
        - 'y'
    TypeAction:
      type: object
      properties:
        type:
          const: type
        text:
          type: string
      required:
        - type
        - text
    WaitAction:
      type: object
      properties:
        type:
          const: wait
      required:
        - type
    SearchAction:
      type: object
      properties:
        type:
          const: search
        query:
          type: string
        sources:
          type: array
          items:
            $ref: '#/components/schemas/SearchActionSource'
      required:
        - type
        - query
    OpenPageAction:
      type: object
      properties:
        type:
          const: open_page
        url:
          type: string
      required:
        - type
        - url
    FindAction:
      type: object
      properties:
        type:
          const: find
        pattern:
          type: string
        url:
          type: string
      required:
        - type
        - pattern
        - url
    CodeInterpreterOutputLogs:
      type: object
      properties:
        type:
          const: logs
        logs:
          type: string
      required:
        - type
        - logs
    CodeInterpreterOutputImage:
      type: object
      properties:
        type:
          const: image
        url:
          type: string
      required:
        - type
        - url
    ShellNetworkPolicy:
      type: object
      properties:
        type:
          const: allowlist
        allowed_domains:
          type: array
          items:
            type: string
          description: Domains permitted for outbound network access.
        domain_secrets:
          type: array
          items:
            $ref: '#/components/schemas/ShellNetworkPolicyDomainSecret'
          description: Secrets injected per domain.
      required:
        - type
    SkillEntry:
      anyOf:
        - $ref: '#/components/schemas/SkillReference'
        - $ref: '#/components/schemas/PreconfiguredSkillReference'
      discriminator:
        propertyName: type
        mapping:
          skill_reference:
            $ref: '#/components/schemas/SkillReference'
          preconfigured:
            $ref: '#/components/schemas/PreconfiguredSkillReference'
    MemoryStoreMount:
      type: object
      properties:
        store_id:
          type: string
          minLength: 1
          description: ID of the memory store to mount into the container.
        label:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^(?!\.+$)[A-Za-z0-9._-]+$
          description: Directory name for this store under /mnt/memory.
        access:
          enum:
            - read_only
            - read_write
          type: string
          default: read_only
          description: Whether the mounted memory store can be modified.
        description:
          type: string
          maxLength: 2000
          description: Optional short description of the store for agent context.
        instructions:
          type: string
          maxLength: 4000
          description: >-
            Optional instructions for how the agent should use this mounted
            store.
      required:
        - store_id
        - label
    TopLogProb:
      type: object
      properties:
        token:
          type: string
        logprob:
          type: number
        bytes:
          type: array
          items:
            type: number
      required:
        - token
        - logprob
        - bytes
    SearchActionSource:
      type: object
      properties:
        type:
          const: url
        url:
          type: string
      required:
        - type
        - url
    ShellNetworkPolicyDomainSecret:
      type: object
      properties:
        domain:
          type: string
          description: The domain to associate this secret with.
        name:
          type: string
          description: The name/placeholder for the secret (e.g., $API_KEY).
        value:
          type: string
          description: The secret value to substitute.
      required:
        - domain
        - name
        - value
    SkillReference:
      type: object
      properties:
        type:
          const: skill_reference
        skill_id:
          type: string
          description: ID of the skill to inject into the container.
        version:
          anyOf:
            - type: string
            - type: integer
              minimum: -9007199254740991
              maximum: 9007199254740991
          description: >-
            Version number, or 'latest' for the most recent version. Defaults to
            the skill's default_version.
      required:
        - type
        - skill_id
    PreconfiguredSkillReference:
      type: object
      properties:
        type:
          const: preconfigured
        name:
          type: string
          description: Name of a preconfigured skill (e.g., 'pdf', 'docx', 'xlsx', 'pptx').
      required:
        - type
        - name
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Gateway auth: send `Authorization: Bearer <mka1-api-key>`. For
        multi-user server-side integrations, you can also send `X-On-Behalf-Of:
        <external-user-id>`.

````