openapi: 3.0.0
info:
  description: The Companies API allows developers to manage marketplace companies and their user memberships.
  title: Companies AI Embed Responses API v2 API
  license:
    name: Apache License, Version 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  version: v296.0-SNAPSHOT
servers:
- url: https://marketplace.appdirect.com/api
- url: https://virtserver.swaggerhub.com
tags:
- name: Responses API v2
  description: 'OpenAI Responses-compatible API (v2). Supports streaming (SSE) and non-streaming runs, threaded and stateless execution, and lifecycle control (cancel / pause / resume).


    The shape mirrors the [official OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) for inputs, outputs, tools, and streaming events. Items below labelled **[devs.ai extension]** have no equivalent in OpenAI''s spec; everything else is intended to be 1:1 compatible.


    ### Vendor extensions used to flag devs.ai additions


    Every devs.ai-specific element in this spec is also tagged with a machine-readable [OpenAPI specification extension](https://swagger.io/docs/specification/openapi-extensions/) so tooling can detect them programmatically without parsing description text:


    - **`x-devs-ai-extension: true`** — applied to schemas, schema properties, parameters, response headers, and operations that have no OpenAI counterpart.

    - **`x-devs-ai-extension-values: [string, ...]`** — applied to enum schemas/properties whose enum is OpenAI-aligned but where devs.ai accepts/emits additional values. Lists only the extra values (e.g. `["cancelled"]` on `ResponseStatus`).

    - **`x-devs-ai-extension-behavior: "<id>"`** — applied where the field name itself is OpenAI-standard but devs.ai''s handling differs (e.g. `optional-on-request` on `MessageInputItem.type` because devs.ai accepts the field being omitted while OpenAI requires it).


    ### devs.ai Extensions


    A single reference list of every devs.ai-specific addition exposed by this API. Each entry below is also marked `**[devs.ai extension]**` at its source and carries one of the `x-devs-ai-extension*` vendor extensions described above.


    **Request fields (`CreateResponseRequest`)**

    - `chat_mode` — `execute` / `chat` / `plan` execution mode.

    - `user_secrets` — short-lived per-request API keys / secrets for tools.

    - `thread_mode` — concurrent-request handling on an existing thread (`collect` / `steer` / `interrupt` / `force`).

    - `options` — internal devs.ai chat options (provider routing, tracing, etc.).

    - `reasoning.effort` extra values `none` and `xhigh` (in addition to OpenAI''s `minimal` / `low` / `medium` / `high`).


    **Input content-part flags**

    - `input_text.invisible` / `input_image.invisible` / `input_file.invisible` — content sent to the model but hidden from end-user transcripts.

    - `input_text.metadata` — arbitrary metadata attached to a content part (not forwarded to the model).

    - `output_text.logprobs` (when `output_text` appears inside an `OutputMessageInputItem`).


    **Input item enum**

    - `FunctionCallOutputInputItem.status` uses `["success", "error", "cancelled"]` instead of OpenAI''s `["in_progress", "completed", "incomplete"]` (incompatible enum).


    **Tools (`ToolDefinition`)** — only `function` and `web_search` mirror OpenAI; everything below is devs.ai-specific.

    - `python` — emits `server_tool_call` items (not OpenAI''s `code_interpreter_call`).

    - `image_generation` — shares the type name with OpenAI but uses devs.ai''s input shape and emits `server_tool_call` items.

    - `mcp_server` — references a configured devs.ai MCP integration; does not emit OpenAI''s `mcp_list_tools` discovery events or `mcp_approval_request` / `mcp_approval_response` items.

    - `spreadsheet`, `memory`, `sandbox`, `deep_research` — no OpenAI counterpart.

    - `web_search.includeXSearch` — extra X (Twitter) search inclusion flag.


    **Output items (`OutputItem`)**

    - `server_tool_call` and `server_tool_call_output` — emitted instead of OpenAI''s `code_interpreter_call` / `image_generation_call` items for devs.ai''s server-side tools.


    **Response fields (`Response`)**

    - `selection_metadata` — model routing / selection metadata (chosen provider, fallback chain, latency hints).

    - `status` extra value `cancelled` (in addition to OpenAI''s `in_progress` / `completed` / `failed` / `incomplete`).

    - `incomplete_details.reason` extra value `paused` (in addition to OpenAI''s `max_output_tokens` / `content_filter`).


    **Streaming events** (full list and payloads in the `x-streaming-events` reference under `components`)

    - `response.server_tool_call.in_progress` / `.completed` / `.failed`.

    - `response.server_tool_call_arguments.delta` / `.done`.

    - `response.subagent.started` / `.progress` / `.completed`.

    - `response.output_item.added.status_hints` (optional field on `response.output_item.added`).

    - Every event payload includes a monotonically increasing `sequence_number` field.

    - Terminal sentinel `event: done` / `data: [DONE]` after the last lifecycle event.


    **Endpoints / headers**

    - `POST /api/v2/responses/{responseId}/pause` — pause an active threaded response run.

    - `POST /api/v2/responses/{responseId}/resume` — resume a paused threaded response run, optionally supplying tool outputs.

    - `GET /api/v2/responses/{responseId}/stream` — reconnect to an in-flight SSE stream after a network drop, resuming from `lastSequence`.

    - `POST /api/v2/responses/{responseId}/deep-research/resume` — approve / deny / clarify a paused deep research subagent.

    - `x-stream-chat-id` response header on streaming `POST /api/v2/responses` and on the `/stream` reconnect endpoint.'
paths:
  /api/v2/responses:
    post:
      operationId: createResponse
      summary: Create a response
      description: "Submit a prompt and receive a model response. When `stream=true` (default),\nreturns an SSE event stream following the OpenAI Responses streaming format.\nWhen `stream=false`, returns the completed response as JSON.\n\n**Execution modes:**\n- **Threaded**: when `previous_response_id` or `conversation` is provided.\n  Signals a long-lived Temporal `ThreadWorkflow` that processes requests sequentially.\n- **Stateless**: when neither `previous_response_id` nor `conversation` is set.\n  Starts a one-shot `SingleResponseWorkflow`.\n\nResponse headers include `x-response-id`, `x-response-status`, and, for streaming responses, `x-stream-epoch`.\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
      responses:
        '200':
          description: 'When `stream=true`: SSE event stream. When `stream=false`: completed Response object.

            '
          headers:
            x-response-id:
              schema:
                type: string
              description: Unique response run identifier.
            x-response-status:
              schema:
                type: string
              description: Initial response status.
            x-stream-chat-id:
              schema:
                type: string
              description: '**[devs.ai extension]** Set on streaming responses (`stream=true`). Equals the underlying chat-stream identifier and can be passed as `streamChatId` to `GET /api/v2/responses/{responseId}/stream` to reconnect after a network drop. Equal to `x-response-id`.'
              x-devs-ai-extension: true
            x-stream-epoch:
              schema:
                type: string
              description: '**[devs.ai extension]** Redis stream epoch for reconnect handshakes. Persist this with `lastSequence` and pass it as `streamEpoch` to `GET /api/v2/responses/{responseId}/stream`.'
              x-devs-ai-extension: true
          content:
            text/event-stream:
              schema:
                description: SSE event stream. See Streaming Events section.
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid request (missing model, invalid file references, schema validation failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Responses API v2
      security:
      - ApiKeyAuth: []
  /api/v2/responses/{responseId}:
    get:
      operationId: getResponse
      summary: Get a response
      description: 'Retrieve a response run by ID. Returns the full response object including

        output items, usage, and status.

        '
      parameters:
      - $ref: '#/components/parameters/responseId'
      responses:
        '200':
          description: Response object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: Response not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Responses API v2
      security:
      - ApiKeyAuth: []
  /api/v2/responses/{responseId}/stream:
    get:
      operationId: streamResponse
      summary: Reconnect to an in-flight response stream
      description: '**[devs.ai extension]** Re-attach to a still-running response''s SSE event stream after a network drop. The path parameter `responseId` and the required query parameter `streamChatId` MUST be equal — `streamChatId` exists for explicit client-side intent and to align with the underlying chat-stream backend.


        When `lastSequence` is supplied, events with `sequence_number <= lastSequence` are suppressed so the client receives only events it has not yet seen. The first event delivered is therefore typically `response.in_progress` (or whatever event follows `lastSequence`), NOT `response.created`.


        This endpoint has no equivalent in OpenAI''s Responses API.


        Returns `404` when the run cannot be found, `streamChatId` does not equal `responseId`, or the underlying stream has already completed and can no longer be reattached.

        '
      x-devs-ai-extension: true
      parameters:
      - $ref: '#/components/parameters/responseId'
      - name: streamChatId
        in: query
        required: true
        description: '**[devs.ai extension]** Must equal the path `responseId`. Identifies the underlying chat-stream to attach to.'
        schema:
          type: string
          minLength: 1
        x-devs-ai-extension: true
      - name: lastSequence
        in: query
        required: false
        description: '**[devs.ai extension]** Last `sequence_number` the client has already processed. Events with `sequence_number <= lastSequence` are suppressed. Default `-1` (no events suppressed).'
        schema:
          type: integer
          minimum: -1
          default: -1
        x-devs-ai-extension: true
      responses:
        '200':
          description: SSE event stream identical in shape to the create-response stream (see Streaming Events section).
          headers:
            x-response-id:
              schema:
                type: string
              description: Echoed response run identifier.
            x-stream-chat-id:
              schema:
                type: string
              description: '**[devs.ai extension]** Echoed `streamChatId` query parameter.'
              x-devs-ai-extension: true
          content:
            text/event-stream:
              schema:
                description: SSE event stream. See Streaming Events section.
                type: string
        '404':
          description: Response not found, `streamChatId` does not match `responseId`, or the underlying stream has already completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Responses API v2
      security:
      - ApiKeyAuth: []
  /api/v2/responses/{responseId}/cancel:
    post:
      operationId: cancelResponse
      summary: Cancel a response
      description: 'Cancel an active response run. Only works for threaded execution mode.

        Idempotent — returns success if the response is already in a terminal state.

        Sends a `CANCEL_ACTIVE_REQUEST` signal to the Temporal workflow.

        '
      parameters:
      - $ref: '#/components/parameters/responseId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelResponseRequest'
      responses:
        '200':
          description: Cancel requested (or already terminal)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlResponse'
        '404':
          description: Response not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Not a threaded response (stateless responses cannot be cancelled via this endpoint)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Responses API v2
      security:
      - ApiKeyAuth: []
  /api/v2/responses/{responseId}/pause:
    post:
      operationId: pauseResponse
      summary: Pause a response
      description: '**[devs.ai extension]** Pause an active response run. Execution halts at the next safe checkpoint;

        in-flight activities complete but no new turns are scheduled.

        Only works for threaded execution mode. No equivalent in OpenAI''s Responses API.

        '
      x-devs-ai-extension: true
      parameters:
      - $ref: '#/components/parameters/responseId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PauseResponseRequest'
      responses:
        '200':
          description: Pause requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlResponse'
        '404':
          description: Response not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Not a threaded response or already terminal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Responses API v2
      security:
      - ApiKeyAuth: []
  /api/v2/responses/{responseId}/resume:
    post:
      operationId: resumeResponse
      summary: Resume a response
      description: '**[devs.ai extension]** Resume a paused response run. Optionally provide tool outputs for

        human-in-the-loop tool calling (function tools that require client execution).

        Only works for threaded execution mode. No equivalent in OpenAI''s Responses API.

        '
      x-devs-ai-extension: true
      parameters:
      - $ref: '#/components/parameters/responseId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeResponseRequest'
      responses:
        '200':
          description: Resume requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ControlResponse'
        '404':
          description: Response not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Not a threaded response or already terminal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Responses API v2
      security:
      - ApiKeyAuth: []
  /api/v2/responses/{responseId}/deep-research/resume:
    post:
      operationId: resumeDeepResearch
      summary: Resume a deep research subagent
      description: '**[devs.ai extension]** Resume a paused deep research child workflow. Used to approve, deny,

        or provide clarification for a deep research run that is awaiting

        human input. Signals the deep research subagent workflow directly. No equivalent in OpenAI''s Responses API.

        '
      x-devs-ai-extension: true
      parameters:
      - $ref: '#/components/parameters/responseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeDeepResearchRequest'
      responses:
        '200':
          description: Resume requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeepResearchControlResponse'
        '404':
          description: Response not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Response is already terminal
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Responses API v2
      security:
      - ApiKeyAuth: []
components:
  schemas:
    PythonToolDefinition:
      type: object
      required:
      - type
      description: '**[devs.ai extension]** Server-side Python execution tool. Conceptually similar to OpenAI''s `code_interpreter` tool, but devs.ai emits `server_tool_call` / `server_tool_call_output` items and `response.server_tool_call.*` events instead of OpenAI''s `code_interpreter_call` items and `response.code_interpreter_call.*` events.'
      x-devs-ai-extension: true
      properties:
        type:
          type: string
          enum:
          - python
    ServerToolCallResultOutputItem:
      type: object
      description: '**[devs.ai extension]** Server-executed tool call result. Emitted in pair with `ServerToolCallOutputItem` instead of OpenAI''s `code_interpreter_call_output` / `image_generation_call_output` items.'
      x-devs-ai-extension: true
      required:
      - type
      - call_id
      - output
      properties:
        type:
          type: string
          enum:
          - server_tool_call_output
        call_id:
          type: string
        output:
          type: string
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
    ToolOutput:
      type: object
      required:
      - toolCallId
      - output
      additionalProperties: false
      properties:
        toolCallId:
          type: string
          minLength: 1
        status:
          type: string
          enum:
          - success
          - error
          default: success
        output:
          oneOf:
          - type: string
          - type: array
            items:
              type: string
    ResumeResponseRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
        toolOutputs:
          type: array
          items:
            $ref: '#/components/schemas/ToolOutput'
    Response:
      type: object
      required:
      - id
      - object
      - status
      - output
      - created_at
      description: A model response. Mirrors OpenAI's Responses API `Response` shape with the devs.ai extensions noted below.
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - response
        status:
          $ref: '#/components/schemas/ResponseStatus'
        model:
          type: string
          nullable: true
        output:
          type: array
          items:
            $ref: '#/components/schemas/OutputItem'
        usage:
          $ref: '#/components/schemas/Usage'
        error:
          $ref: '#/components/schemas/ResponseError'
        created_at:
          type: integer
          description: Unix timestamp (seconds since epoch) when the response was created.
        instructions:
          type: string
          nullable: true
          description: Echoed instructions from the request.
        temperature:
          type: number
          nullable: true
        top_p:
          type: number
          nullable: true
        max_output_tokens:
          type: integer
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
        previous_response_id:
          type: string
          nullable: true
        parallel_tool_calls:
          type: boolean
          description: Whether the model was allowed to call tools in parallel for this response. Echoed from the request; defaults to `true` when not set on the request.
        incomplete_details:
          type: object
          nullable: true
          description: 'Details about why the response is incomplete (only populated when `status: "incomplete"`).'
          properties:
            reason:
              type: string
              enum:
              - max_output_tokens
              - content_filter
              - paused
              description: OpenAI's enum is `["max_output_tokens", "content_filter"]`. The value `paused` is a **[devs.ai extension]** emitted when an in-flight run is paused via `POST /api/v2/responses/{responseId}/pause`.
              x-devs-ai-extension-values:
              - paused
        tool_choice:
          oneOf:
          - type: string
            nullable: true
          - type: object
            additionalProperties: true
            nullable: true
          description: Echoed tool choice strategy from the request.
        tools:
          type: array
          nullable: true
          items: {}
          description: Echoed tools from the request.
        text:
          type: object
          additionalProperties: true
          nullable: true
          description: Echoed text format configuration from the request.
        reasoning:
          type: object
          additionalProperties: true
          nullable: true
          description: Echoed reasoning configuration from the request.
        selection_metadata:
          type: object
          description: '**[devs.ai extension]** Model routing / selection metadata captured during the run (chosen provider, fallback chain, latency hints, etc.).'
          nullable: true
          additionalProperties: true
          x-devs-ai-extension: true
    InputContentPart:
      description: 'Content part for an `InputMessageInputItem` (`role: user|system|developer`). Mirrors OpenAI''s `InputContent` union: `input_text`, `input_image`, or `input_file` only.'
      oneOf:
      - $ref: '#/components/schemas/InputTextContent'
      - $ref: '#/components/schemas/InputImageContent'
      - $ref: '#/components/schemas/InputFileContent'
      discriminator:
        propertyName: type
        mapping:
          input_text: '#/components/schemas/InputTextContent'
          input_image: '#/components/schemas/InputImageContent'
          input_file: '#/components/schemas/InputFileContent'
    CreateResponseRequest:
      type: object
      required:
      - input
      additionalProperties: true
      description: Request body for `POST /api/v2/responses`. Mirrors OpenAI's Responses API `CreateResponse` shape with a small set of devs.ai extensions (each marked `**[devs.ai extension]**` below).
      properties:
        input:
          description: User prompt — plain text or an array of input items (`message`, `function_call`, `function_call_output`). See the `InputItem` schema for the full grammar.
          oneOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/InputItem'
        model:
          type: string
          description: Model ID to use, like `gpt-4o` or `o3`. Required for stateless requests; optional when continuing a thread via `previous_response_id` / `conversation`.
        previous_response_id:
          type: string
          nullable: true
          description: ID of a previous response to continue the conversation. Establishes multi-turn context.
        conversation:
          description: Conversation/thread ID (string) or object with `id` field. Items from this conversation are prepended to `input` and items from this response are appended to it.
          oneOf:
          - type: string
          - type: object
            properties:
              id:
                type: string
            required:
            - id
        instructions:
          type: string
          nullable: true
          description: System/developer instructions inserted as the first item in the model's context. When used with `previous_response_id`, instructions from the previous response are not carried over.
        stream:
          type: boolean
          default: true
          description: If `true` (default), the response data is streamed to the client as Server-Sent Events. If `false`, the completed response is returned as JSON.
        tools:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/ToolDefinition'
          description: Tools the model may call while generating a response. See `ToolDefinition` for available tools (most built-ins are devs.ai extensions).
        temperature:
          type: number
          minimum: 0
          maximum: 2
          description: Sampling temperature between 0 and 2. Higher values produce more random output.
        top_p:
          type: number
          minimum: 0
          maximum: 1
          description: Nucleus sampling parameter. We generally recommend altering this OR `temperature`, not both.
        max_output_tokens:
          type: integer
          minimum: 1
          description: Upper bound for the number of tokens that can be generated for a response, including reasoning tokens.
        reasoning:
          type: object
          description: Reasoning configuration for reasoning-capable models (e.g. o-series).
          properties:
            effort:
              type: string
              description: Reasoning effort. OpenAI's standard enum is `["minimal", "low", "medium", "high"]`. devs.ai also accepts the `**[devs.ai extension]**` values `none` and `xhigh`.
              enum:
              - none
              - minimal
              - low
              - medium
              - high
              - xhigh
              x-devs-ai-extension-values:
              - none
              - xhigh
            summary:
              type: string
              nullable: true
              enum:
              - auto
              - concise
              - detailed
              description: Reasoning summary verbosity.
            generate_summary:
              type: string
              nullable: true
              enum:
              - auto
              - concise
              - detailed
              description: Deprecated alias of `summary` (kept for backward compatibility with older OpenAI SDKs).
        metadata:
          type: object
          nullable: true
          additionalProperties:
            type: string
          description: Metadata key-value pairs for tagging.
        parallel_tool_calls:
          type: boolean
          description: Whether to allow the model to run tool calls in parallel. Default `true`. Echoed back on the Response object.
        tool_choice:
          description: How the model should select which tool(s) to use. Accepts the OpenAI `tool_choice` shapes (e.g. `"auto"`, `"none"`, `"required"`, or a typed object referring to a specific tool).
        store:
          type: boolean
          description: Whether to store the generated response for later retrieval via the API. Default `true`.
        truncation:
          description: Truncation strategy for the model response. OpenAI accepts `"auto"` or `"disabled"`.
        text:
          description: 'Configuration options for a text response from the model. Can be plain text or structured JSON (e.g. `{ format: { type: "json_schema", ... } }`).'
        service_tier:
          type: string
          description: Service tier to use for this request (e.g. `"auto"`, `"default"`, `"flex"`).
        user:
          type: string
          description: Stable identifier for the end-user. Used to boost cache hit rates and to help OpenAI detect abuse. Deprecated by OpenAI in favor of `safety_identifier` / `prompt_cache_key`.
        include:
          type: array
          items:
            type: string
          description: Specify additional output data to include in the model response (e.g. `file_search_call.results`, `message.input_image.image_url`, `message.output_text.logprobs`, `reasoning.encrypted_content`).
        background:
          type: boolean
          description: If `true`, the model runs in the background and the response can be polled / streamed via the dedicated endpoints.
        options:
          allOf:
          - $ref: '#/components/schemas/ChatOptions'
          - description: '**[devs.ai extension]** Internal devs.ai chat options (provider-specific routing, sub-flow tracing, etc.). Not part of the OpenAI Responses API.'
          x-devs-ai-extension: true
        chat_mode:
          type: string
          enum:
          - execute
          - chat
          - plan
          default: execute
          description: '**[devs.ai extension]** Chat execution mode: `execute` runs tools, `chat` returns text only, `plan` returns the planned steps without running them.'
          x-devs-ai-extension: true
        user_secrets:
          type: object
          additionalProperties:
            type: string
          description: '**[devs.ai extension]** User-provided API keys / secrets that tools may reference at execution time. Keys are short-lived and never persisted server-side.'
          x-devs-ai-extension: true
        thread_mode:
          allOf:
          - $ref: '#/components/schemas/ThreadMode'
          - description: '**[devs.ai extension]** How to handle a new request when an existing thread is mid-run: `collect` (queue), `steer` (signal current run), `interrupt` (cancel + start), `force` (start fresh stateless run).'
          x-devs-ai-extension: true
    OutputMessage:
      type: object
      required:
      - id
      - type
      - role
      - status
      - content
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - message
        role:
          type: string
          enum:
          - assistant
        status:
          type: string
          enum:
          - in_progress
          - completed
          - incomplete
        content:
          type: array
          items:
            $ref: '#/components/schemas/OutputTextPart'
    ResponseError:
      type: object
      nullable: true
      required:
      - code
      - message
      properties:
        code:
          type: string
        message:
          type: string
    InputImageContent:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - input_image
        image_url:
          type: string
        file_id:
          type: string
        detail:
          type: string
          enum:
          - auto
          - low
          - high
        invisible:
          type: boolean
          description: '**[devs.ai extension]** When `true`, this image is sent to the model but hidden from end-user-facing transcripts.'
          x-devs-ai-extension: true
    WebSearchToolDefinition:
      type: object
      required:
      - type
      description: 'Web search tool. The output items (`web_search_call`) and streaming events (`response.web_search_call.in_progress|searching|completed`) emitted by devs.ai match OpenAI''s standard shapes. NOTE: OpenAI''s `web_search` / `web_search_preview` tool also accepts `user_location` and `search_context_size`; devs.ai currently ignores those input fields (they are silently dropped).'
      properties:
        type:
          type: string
          enum:
          - web_search
        includeXSearch:
          type: boolean
          description: '**[devs.ai extension]** When `true`, also includes results from X (Twitter) search alongside web results.'
          x-devs-ai-extension: true
    McpServerToolDefinition:
      type: object
      required:
      - type
      - toolId
      description: '**[devs.ai extension]** Reference to a configured MCP server integration. Differs from OpenAI''s `mcp` tool: devs.ai accepts `{ type: ''mcp_server'', toolId }` referring to a configured MCP integration, instead of OpenAI''s `server_label` / `server_url` / `connector_id` / `headers` / `allowed_tools` / `require_approval`. devs.ai DOES emit `mcp_call` output items and `response.mcp_call.in_progress|completed|failed` events that match OpenAI''s standard shapes for executed tool calls, but does NOT currently emit OpenAI''s `mcp_list_tools` discovery items, `mcp_approval_request` / `mcp_approval_response` items, `response.mcp_list_tools.*` events, or `response.mcp_call_arguments.*` events.'
      x-devs-ai-extension: true
      properties:
        type:
          type: string
          enum:
          - mcp_server
        toolId:
          type: string
          description: ID of the MCP server integration configured in devs.ai.
    RefusalContent:
      type: object
      required:
      - type
      - refusal
      description: A `refusal` content part inside an assistant message. Mirrors OpenAI's `RefusalContent`.
      properties:
        type:
          type: string
          enum:
          - refusal
        refusal:
          type: string
    ToolDefinition:
      description: A tool the model may invoke. The `function` and `web_search` variants mirror OpenAI's Responses API tools. All other variants are devs.ai-specific built-ins.
      oneOf:
      - $ref: '#/components/schemas/FunctionToolDefinition'
      - $ref: '#/components/schemas/WebSearchToolDefinition'
      - $ref: '#/components/schemas/PythonToolDefinition'
      - $ref: '#/components/schemas/ImageGenerationToolDefinition'
      - $ref: '#/components/schemas/SpreadsheetToolDefinition'
      - $ref: '#/components/schemas/MemoryToolDefinition'
      - $ref: '#/components/schemas/SandboxToolDefinition'
      - $ref: '#/components/schemas/McpServerToolDefinition'
      - $ref: '#/components/schemas/DeepResearchToolDefinition'
      discriminator:
        propertyName: type
        mapping:
          function: '#/components/schemas/FunctionToolDefinition'
          web_search: '#/components/schemas/WebSearchToolDefinition'
          python: '#/components/schemas/PythonToolDefinition'
          image_generation: '#/components/schemas/ImageGenerationToolDefinition'
          spreadsheet: '#/components/schemas/SpreadsheetToolDefinition'
          memory: '#/components/schemas/MemoryToolDefinition'
          sandbox: '#/components/schemas/SandboxToolDefinition'
          mcp_server: '#/components/schemas/McpServerToolDefinition'
          deep_research: '#/components/schemas/DeepResearchToolDefinition'
    OutputContentPart:
      description: 'Content part for an `OutputMessageInputItem` (`role: assistant`). Mirrors OpenAI''s `OutputMessageContent` union: `output_text` or `refusal` only.'
      oneOf:
      - $ref: '#/components/schemas/OutputTextContent'
      - $ref: '#/components/schemas/RefusalContent'
      discriminator:
        propertyName: type
        mapping:
          output_text: '#/components/schemas/OutputTextContent'
          refusal: '#/components/schemas/RefusalContent'
    SpreadsheetToolDefinition:
      type: object
      required:
      - type
      description: '**[devs.ai extension]** Spreadsheet manipulation tool. No OpenAI counterpart. Emits `server_tool_call` / `server_tool_call_output` items.'
      x-devs-ai-extension: true
      properties:
        type:
          type: string
          enum:
          - spreadsheet
    InputItem:
      description: Input item for the Responses API (message, function_call, or function_call_output)
      oneOf:
      - $ref: '#/components/schemas/MessageInputItem'
      - $ref: '#/components/schemas/FunctionCallInputItem'
      - $ref: '#/components/schemas/FunctionCallOutputInputItem'
      discriminator:
        propertyName: type
        mapping:
          message: '#/components/schemas/MessageInputItem'
          function_call: '#/components/schemas/FunctionCallInputItem'
          function_call_output: '#/components/schemas/FunctionCallOutputInputItem'
    ResponseStatus:
      type: string
      enum:
      - in_progress
      - completed
      - failed
      - cancelled
      - incomplete
      description: Lifecycle status of the response. OpenAI's standard enum is `["in_progress", "completed", "failed", "incomplete"]`. The value `cancelled` is a **[devs.ai extension]** returned when a run is cancelled via `POST /api/v2/responses/{responseId}/cancel`.
      x-devs-ai-extension-values:
      - cancelled
    ThreadMode:
      type: string
      enum:
      - collect
      - steer
      - interrupt
      - force
      default: collect
      description: '**[devs.ai extension]** Controls how a new request is handled when an existing thread is mid-run. No OpenAI counterpart.'
      x-devs-ai-extension: true
    ReasoningOutputItem:
      type: object
      required:
      - id
      - type
      - status
      - summary
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - reasoning
        status:
          type: string
          enum:
          - in_progress
          - completed
          - incomplete
        summary:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - summary_text
              text:
                type: string
        content:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                - reasoning_text
              text:
                type: string
    ResumeDeepResearchRequest:
      type: object
      required:
      - subagentRunId
      additionalProperties: false
      properties:
        subagentRunId:
          type: string
          minLength: 1
        approved:
          type: boolean
        clarificationAnswer:
          type: string
        goal:
          type: string
        scope:
          type: string
        deniedReason:
          type: string
        reason:
          type: string
    WebSearchCallOutputItem:
      type: object
      required:
      - id
      - type
      - status
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - web_search_call
        status:
          type: string
          enum:
          - in_progress
          - searching
          - completed
          - failed
    SandboxToolDefinition:
      type: object
      required:
      - type
      description: '**[devs.ai extension]** General-purpose sandbox execution tool. No OpenAI counterpart. Emits `server_tool_call` / `server_tool_call_output` items.'
      x-devs-ai-extension: true
      properties:
        type:
          type: string
          enum:
          - sandbox
    FunctionCallInputItem:
      type: object
      required:
      - type
      - call_id
      - name
      - arguments
      description: A prior `function_call` item submitted as input. Mirrors OpenAI's `FunctionCallItemParam`.
      properties:
        type:
          type: string
          enum:
          - function_call
        id:
          type: string
          description: Stable item identifier. Optional on the request side; preserved when echoed back.
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
          description: JSON-encoded arguments string.
    CancelResponseRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
        cancelPolicy:
          $ref: '#/components/schemas/CancelPolicy'
    CancelPolicy:
      type: string
      enum:
      - graceful
      - immediate
      default: graceful
    ServerToolCallOutputItem:
      type: object
      description: '**[devs.ai extension]** Server-executed tool call output item. Emitted instead of OpenAI''s `code_interpreter_call` / `image_generation_call` items for devs.ai''s `python` and `image_generation` tools.'
      x-devs-ai-extension: true
      required:
      - id
      - type
      - server_tool_call
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - server_tool_call
        server_tool_call:
          type: object
          required:
          - call_id
          - name
          - arguments
          - status
          properties:
            call_id:
              type: string
            name:
              type: string
            arguments:
              type: string
              description: JSON-encoded arguments
            status:
              type: string
              enum:
              - in_progress
              - completed
              - failed
    FunctionCallOutputItem:
      type: object
      required:
      - id
      - type
      - name
      - call_id
      - arguments
      - status
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - function_call
        name:
          type: string
        call_id:
          type: string
        arguments:
          type: string
          description: JSON-encoded arguments
        status:
          type: string
          enum:
          - in_progress
          - completed
    ChatOptions:
      type: object
      properties:
        flow:
          type: object
          properties:
            override:
              type: object
              properties:
                force:
                  type: boolean
                id:
                  type: string
                version:
                  type: number
            tracing:
              type: object
              properties:
                enabled:
                  type: boolean
    Usage:
      type: object
      nullable: true
      description: Token usage details for the response. Mirrors OpenAI's `ResponseUsage` shape, including the plural `input_tokens_details` / `output_tokens_details` field names.
      required:
      - input_tokens
      - input_tokens_details
      - output_tokens
      - output_tokens_details
      - total_tokens
      properties:
        input_tokens:
          type: integer
          minimum: 0
          description: The number of input tokens (prompt + tools + previous turns).
        input_tokens_details:
          type: object
          required:
          - cached_tokens
          description: Detailed breakdown of input tokens.
          properties:
            cached_tokens:
              type: integer
              minimum: 0
              description: The number of input tokens that were served from cache.
        output_tokens:
          type: integer
          minimum: 0
          description: The number of output tokens (model response).
        output_tokens_details:
          type: object
          required:
          - reasoning_tokens
          description: Detailed breakdown of output tokens.
          properties:
            reasoning_tokens:
              type: integer
              minimum: 0
              description: The number of reasoning tokens (extended thinking) included in the output count.
        total_tokens:
          type: integer
          minimum: 0
          description: The total number of tokens used (`input_tokens + output_tokens`).
    MessageInputItem:
      description: 'A `message` input item. Mirrors OpenAI''s input grammar: items with `role: user|system|developer` are `InputMessage`-shaped (with `input_text`/`input_image`/`input_file` content), while items with `role: assistant` are `OutputMessage`-shaped (with `output_text`/`refusal` content, required `id`, required `status`). The two shapes do NOT share content parts.'
      oneOf:
      - $ref: '#/components/schemas/InputMessageInputItem'
      - $ref: '#/components/schemas/OutputMessageInputItem'
      discriminator:
        propertyName: role
        mapping:
          user: '#/components/schemas/InputMessageInputItem'
          system: '#/components/schemas/InputMessageInputItem'
          developer: '#/components/schemas/InputMessageInputItem'
          assistant: '#/components/schemas/OutputMessageInputItem'
    OutputMessageInputItem:
      type: object
      required:
      - id
      - type
      - role
      - status
      - content
      description: 'An assistant message submitted as input (e.g. when reconstructing prior turns). Mirrors OpenAI''s `OutputMessage`. `id`, `status`, `role: assistant`, and `type: message` are all required.'
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - message
        role:
          type: string
          enum:
          - assistant
        status:
          type: string
          enum:
          - in_progress
          - completed
          - incomplete
        content:
          type: array
          items:
            $ref: '#/components/schemas/OutputContentPart'
          description: Array of `output_text` and/or `refusal` content parts.
    McpCallOutputItem:
      type: object
      description: MCP tool call output item (OpenAI standard)
      required:
      - id
      - type
      - server_label
      - name
      - arguments
      - status
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - mcp_call
        server_label:
          type: string
          description: Human-readable label of the MCP server
        name:
          type: string
          description: Tool name
        arguments:
          type: string
          description: JSON-encoded arguments
        output:
          type: string
          description: Tool output on success
        error:
          type: string
          description: Error message on failure
        status:
          type: string
          enum:
          - in_progress
          - calling
          - completed
          - failed
    FunctionToolDefinition:
      type: object
      required:
      - type
      - name
      - parameters
      description: 'A user-defined function tool. Mirrors OpenAI''s flat Responses-API `FunctionTool` shape: `{ type: "function", name, description?, parameters, strict? }`. Note the older Chat-Completions-style nested `{ type: "function", function: { ... } }` shape is NOT accepted on this endpoint.'
      properties:
        type:
          type: string
          enum:
          - function
        name:
          type: string
          description: The name of the function to call.
        description:
          type: string
          description: A description of the function. Used by the model to decide whether to call it.
        parameters:
          type: object
          additionalProperties: true
          description: JSON Schema describing the parameters the function accepts.
        strict:
          type: boolean
          description: Whether to enforce strict JSON-schema mode for the parameters.
    OutputTextContent:
      type: object
      required:
      - type
      - text
      - annotations
      description: An `output_text` content part inside an assistant message. Mirrors OpenAI's `OutputTextContent`.
      properties:
        type:
          type: string
          enum:
          - output_text
        text:
          type: string
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/UrlCitationAnnotation'
          description: Currently devs.ai only emits `url_citation` annotations. OpenAI's `Annotation` union also includes `file_citation` and `file_path`, which devs.ai does not currently produce.
        logprobs:
          type: array
          items:
            type: object
            additionalProperties: true
          description: '**[devs.ai extension]** Log-probability information for tokens in this output. OpenAI''s `OutputTextContent` does not include this field; populated by devs.ai when `include` requests `message.output_text.logprobs`.'
          x-devs-ai-extension: true
    InputFileContent:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - input_file
        file_id:
          type: string
        file_data:
          type: string
        filename:
          type: string
        invisible:
          type: boolean
          description: '**[devs.ai extension]** When `true`, this file is sent to the model but hidden from end-user-facing transcripts.'
          x-devs-ai-extension: true
    UrlCitationAnnotation:
      type: object
      required:
      - type
      - url
      - start_index
      - end_index
      properties:
        type:
          type: string
          enum:
          - url_citation
        url:
          type: string
        title:
          type: string
        start_index:
          type: integer
        end_index:
          type: integer
    DeepResearchControlResponse:
      type: object
      required:
      - id
      - object
      - status
      - subagentRunId
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - response.deep_research.resume
        status:
          type: string
          enum:
          - resume_requested
        subagentRunId:
          type: string
        reason:
          type: string
    FunctionCallOutputInputItem:
      type: object
      required:
      - type
      - call_id
      - output
      description: Result of a prior `function_call` submitted as input. Mirrors OpenAI's `FunctionCallOutputItemParam`, except for the `status` field — see below.
      properties:
        type:
          type: string
          enum:
          - function_call_output
        call_id:
          type: string
        output:
          type: string
        status:
          type: string
          enum:
          - success
          - error
          - cancelled
          description: '**[devs.ai extension]** Status of the tool call result. devs.ai uses `["success", "error", "cancelled"]`; OpenAI''s `FunctionCallOutputItemParam.status` uses `["in_progress", "completed", "incomplete"]`. The two enums are not compatible.'
          x-devs-ai-extension: true
    ImageGenerationToolDefinition:
      type: object
      required:
      - type
      - modelId
      description: '**[devs.ai extension]** Image generation tool. Shares the type name `image_generation` with OpenAI but the input shape (`modelId`, `samples`, `aspectRatio`, `quality`, `style`) and the emitted output shape (`server_tool_call` / `server_tool_call_output` items, `response.server_tool_call.*` events) differ from OpenAI''s `ImageGenTool` / `image_generation_call` items.'
      x-devs-ai-extension: true
      properties:
        type:
          type: string
          enum:
          - image_generation
        modelId:
          type: string
        samples:
          type: number
        size:
          type: string
        aspectRatio:
          type: string
        quality:
          type: string
        style:
          type: string
    OutputItem:
      oneOf:
      - $ref: '#/components/schemas/OutputMessage'
      - $ref: '#/components/schemas/FunctionCallOutputItem'
      - $ref: '#/components/schemas/ReasoningOutputItem'
      - $ref: '#/components/schemas/WebSearchCallOutputItem'
      - $ref: '#/components/schemas/ServerToolCallOutputItem'
      - $ref: '#/components/schemas/ServerToolCallResultOutputItem'
      - $ref: '#/components/schemas/McpCallOutputItem'
      discriminator:
        propertyName: type
        mapping:
          message: '#/components/schemas/OutputMessage'
          function_call: '#/components/schemas/FunctionCallOutputItem'
          reasoning: '#/components/schemas/ReasoningOutputItem'
          web_search_call: '#/components/schemas/WebSearchCallOutputItem'
          server_tool_call: '#/components/schemas/ServerToolCallOutputItem'
          server_tool_call_output: '#/components/schemas/ServerToolCallResultOutputItem'
          mcp_call: '#/components/schemas/McpCallOutputItem'
    PauseResponseRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
    OutputTextPart:
      type: object
      required:
      - type
      - text
      - annotations
      description: An `output_text` content part inside a streamed/persisted assistant `OutputMessage`. Mirrors OpenAI's `OutputTextContent` shape.
      properties:
        type:
          type: string
          enum:
          - output_text
        text:
          type: string
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/UrlCitationAnnotation'
          description: Currently devs.ai only emits `url_citation` annotations. OpenAI's `Annotation` union also includes `file_citation` and `file_path`, which devs.ai does not currently produce.
    MemoryToolDefinition:
      type: object
      required:
      - type
      description: '**[devs.ai extension]** Long-term memory tool. No OpenAI counterpart. Emits `server_tool_call` / `server_tool_call_output` items.'
      x-devs-ai-extension: true
      properties:
        type:
          type: string
          enum:
          - memory
    InputTextContent:
      type: object
      required:
      - type
      - text
      properties:
        type:
          type: string
          enum:
          - input_text
        text:
          type: string
        invisible:
          type: boolean
          description: '**[devs.ai extension]** When `true`, this content part is sent to the model but hidden from end-user-facing transcripts.'
          x-devs-ai-extension: true
        metadata:
          type: object
          additionalProperties: true
          description: '**[devs.ai extension]** Free-form metadata attached to this content part. Not forwarded to the model.'
          x-devs-ai-extension: true
    DeepResearchToolDefinition:
      type: object
      required:
      - type
      description: '**[devs.ai extension]** Deep research tool that spawns a child workflow to perform multi-step research. No OpenAI counterpart.'
      x-devs-ai-extension: true
      properties:
        type:
          type: string
          enum:
          - deep_research
        timeBudgetMs:
          type: integer
          minimum: 1
        maxChildren:
          type: integer
          minimum: 1
        maxRefinementRounds:
          type: integer
          minimum: 1
        visibility:
          type: string
          enum:
          - visible
          - background
        requireApproval:
          type: boolean
        clarificationAnswer:
          type: string
    ControlResponse:
      type: object
      required:
      - id
      - object
      - status
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - response.cancel
          - response.pause
          - response.resume
        status:
          type: string
          enum:
          - cancel_requested
          - pause_requested
          - resume_requested
        chatId:
          type: string
    InputMessageInputItem:
      type: object
      required:
      - role
      - content
      description: A user/system/developer message item. Mirrors OpenAI's `InputMessage` (request side). `id` is optional on the request side; the read-side `InputMessageResource` requires it.
      properties:
        type:
          type: string
          enum:
          - message
          default: message
          description: '**[devs.ai extension]** When omitted, defaults to `"message"` if `role` is present (devs.ai applies an `addDefaultMessageType` preprocess for client convenience). OpenAI''s spec requires `type` to be sent explicitly.'
          x-devs-ai-extension-behavior: optional-on-request
        id:
          type: string
          description: Stable item identifier. Optional on the request side.
        role:
          type: string
          enum:
          - user
          - system
          - developer
        content:
          description: Plain text shorthand (auto-wrapped as `input_text`) or an array of `InputContentPart` items (`input_text`, `input_image`, `input_file`).
          oneOf:
          - type: string
          - type: array
            items:
              $ref: '#/components/schemas/InputContentPart'
        status:
          type: string
          enum:
          - in_progress
          - completed
          - incomplete
          description: Item status. Optional for input messages.
  parameters:
    responseId:
      name: responseId
      in: path
      required: true
      schema:
        type: string
        minLength: 1