AppDirect Responses API v2 API

openapi: 3.2.0
info:
  title: Devs.ai Responses API v2 API
  version: '1.0'
  description: OpenAI Responses-compatible API (v2).
security: []
tags:
- name: Responses API v2
  description: OpenAI Responses-compatible API (v2).
paths:
  /api/v2/responses:
    post:
      operationId: createResponse
      summary: Create a response
      description: 'Submit a prompt and receive a model response. When `stream=true` (default),

        returns an SSE event stream following the OpenAI Responses streaming format.

        When `stream=false`, returns the completed response as JSON.


        **Execution modes:**

        - **Threaded**: when `previous_response_id` or `conversation` is provided.

        Signals a long-lived Temporal `ThreadWorkflow` that processes requests sequentially.

        - **Stateless**: when neither `previous_response_id` nor `conversation` is set.

        Starts a one-shot `SingleResponseWorkflow`.


        Response headers include `x-response-id`, `x-response-status`, and, for streaming responses, `x-stream-epoch`.'
      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:
    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.
    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
    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.
    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
    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
    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'
    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
    PauseResponseRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
    CancelResponseRequest:
      type: object
      additionalProperties: false
      properties:
        reason:
          type: string
        cancelPolicy:
          $ref: '#/components/schemas/CancelPolicy'
    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
    ResponseError:
      type:
      - object
      - 'null'
      required:
      - code
      - message
      properties:
        code:
          type: string
        message:
          type: string
    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
    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
    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.
    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.
    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
    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
    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
    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
    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'
    CancelPolicy:
      type: string
      enum:
      - graceful
      - immediate
      default: graceful
    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.
    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
    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'
    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
    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
    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
    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.
    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
    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
    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
    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
          - 'null'
          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 

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appdirect/refs/heads/main/openapi/appdirect-responses-api-v2-api-openapi.yml