nexos.ai Responses API

openapi: 3.2.0
info:
  title: Nexos AI Public API Production Agent Management Responses API
  version: 1.0.0
  description: Manage agents.
servers:
- url: https://api.nexos.ai
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Responses
  description: Create and manage model responses.
paths:
  /v1/responses:
    post:
      operationId: createResponse
      tags:
      - Responses
      summary: Create a model response
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ResponseStreamEvent'
      description: Creates a model response.
  /v1/responses/{response_id}:
    get:
      operationId: getResponse
      tags:
      - Responses
      summary: Get a model response
      parameters:
      - in: path
        name: response_id
        required: true
        schema:
          type: string
        description: The ID of the response to retrieve.
      - in: query
        name: include
        schema:
          type: array
          items:
            $ref: '#/components/schemas/IncludeEnum'
        description: 'Additional fields to include in the response. See the `include`

          parameter for Response creation above for more information.

          '
      - in: query
        name: stream
        schema:
          type: boolean
        description: 'If set to true, the model response data will be streamed to the client

          as it is generated using [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).

          '
      - in: query
        name: starting_after
        schema:
          type: integer
        description: 'The sequence number of the event after which to start streaming.

          '
      - in: query
        name: include_obfuscation
        schema:
          type: boolean
        description: 'When true, stream obfuscation will be enabled. Stream obfuscation adds

          random characters to an `obfuscation` field on streaming delta events

          to normalize payload sizes as a mitigation to certain side-channel

          attacks. These obfuscation fields are included by default, but add a

          small amount of overhead to the data stream.

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
      description: 'Retrieves a model response with the given ID.

        '
    delete:
      operationId: deleteResponse
      tags:
      - Responses
      summary: Delete a model response
      parameters:
      - in: path
        name: response_id
        required: true
        schema:
          type: string
        description: The ID of the response to delete.
      responses:
        '200':
          description: OK
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Deletes a model response with the given ID.

        '
  /v1/responses/{response_id}/input_items:
    get:
      operationId: listInputItems
      tags:
      - Responses
      summary: List input items
      parameters:
      - in: path
        name: response_id
        required: true
        schema:
          type: string
        description: The ID of the response to retrieve input items for.
      - name: limit
        in: query
        description: 'A limit on the number of objects to be returned. Limit can range between

          1 and 100, and the default is 20.

          '
        required: false
        schema:
          type: integer
          default: 20
      - in: query
        name: order
        schema:
          type: string
          enum:
          - asc
          - desc
        description: 'The order to return the input items in. Default is `desc`.

          - `asc`: Return the input items in ascending order.

          - `desc`: Return the input items in descending order.

          '
      - in: query
        name: after
        schema:
          type: string
        description: 'An item ID to list items after, used in pagination.

          '
      - in: query
        name: include
        schema:
          type: array
          items:
            $ref: '#/components/schemas/IncludeEnum'
        description: 'Additional fields to include in the response. See the `include`

          parameter for Response creation above for more information.

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseItemList'
      description: Returns a list of input items for a given response.
  /v1/responses/{response_id}/cancel:
    post:
      operationId: cancelResponse
      tags:
      - Responses
      summary: Cancel a response
      parameters:
      - in: path
        name: response_id
        required: true
        schema:
          type: string
        description: The ID of the response to cancel.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: "Cancels a model response with the given ID. Only responses created with\nthe `background` parameter set to `true` can be cancelled. \n"
  /v1/responses/compact:
    post:
      tags:
      - Responses
      summary: Compact a response
      description: Compact conversation
      operationId: CompactConversation
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompactResponseMethodPublicBody'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CompactResponseMethodPublicBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompactResource'
  /v1/responses/input_tokens:
    post:
      tags:
      - Responses
      summary: Get input token counts
      description: Get input token counts
      operationId: GetInputTokenCounts
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenCountsBody'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenCountsBody'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCountsResource'
components:
  schemas:
    FunctionShellActionParam:
      properties:
        commands:
          items:
            type: string
          type: array
          description: Ordered shell commands for the execution environment to run.
        timeout_ms:
          type:
          - integer
          - 'null'
          description: Maximum wall-clock time in milliseconds to allow the shell commands to run.
        max_output_length:
          type:
          - integer
          - 'null'
          description: Maximum number of UTF-8 characters to capture from combined stdout and stderr output.
      type: object
      required:
      - commands
      title: Function shell action
      description: Commands and limits describing how to run the function shell tool call.
    ServiceTier:
      type:
      - string
      - 'null'
      description: 'Specifies the processing tier for the request.

        The response includes the actual tier used, which may differ from the requested value.

        '
      enum:
      - auto
      - default
      - flex
      - scale
      - priority
      default: auto
    ResponseReasoningTextDoneEvent:
      type: object
      description: Emitted when a reasoning text is completed.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.reasoning_text.done`.

            '
          enum:
          - response.reasoning_text.done
        item_id:
          type: string
          description: 'The ID of the item this reasoning text is associated with.

            '
        output_index:
          type: integer
          description: 'The index of the output item this reasoning text is associated with.

            '
        content_index:
          type: integer
          description: 'The index of the reasoning content part.

            '
        text:
          type: string
          description: 'The full text of the completed reasoning content.

            '
        sequence_number:
          type: integer
          description: 'The sequence number of this event.

            '
      required:
      - type
      - item_id
      - output_index
      - content_index
      - text
      - sequence_number
    ResponseMCPCallInProgressEvent:
      type: object
      title: ResponseMCPCallInProgressEvent
      description: 'Emitted when an MCP  tool call is in progress.

        '
      properties:
        type:
          type: string
          enum:
          - response.mcp_call.in_progress
          description: The type of the event. Always 'response.mcp_call.in_progress'.
        sequence_number:
          type: integer
          description: The sequence number of this event.
        output_index:
          type: integer
          description: The index of the output item in the response's output array.
        item_id:
          type: string
          description: The unique identifier of the MCP tool call item being processed.
      required:
      - type
      - output_index
      - item_id
      - sequence_number
    ApplyPatchCallOutputStatusParam:
      type: string
      enum:
      - completed
      - failed
      title: Apply patch call output status
      description: Outcome values reported for apply_patch tool call outputs.
    LocalShellToolParam:
      properties:
        type:
          type: string
          enum:
          - local_shell
          description: The type of the local shell tool. Always `local_shell`.
          default: local_shell
      type: object
      required:
      - type
      title: Local shell tool
      description: A tool that allows the model to execute shell commands in a local environment.
    MCPToolFilter:
      type: object
      title: MCP tool filter
      description: 'A filter object to specify which tools are allowed.

        '
      properties:
        tool_names:
          type: array
          title: MCP allowed tools
          items:
            type: string
          description: List of allowed tool names.
        read_only:
          type: boolean
          description: 'Indicates whether or not a tool modifies data or is read-only. If an

            MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

            it will match this filter.

            '
      required: []
      additionalProperties: false
    FunctionShellToolParam:
      properties:
        type:
          type: string
          enum:
          - shell
          description: The type of the shell tool. Always `shell`.
          default: shell
      type: object
      required:
      - type
      title: Shell tool
      description: A tool that allows the model to execute shell commands.
    SearchContextSize:
      type: string
      enum:
      - low
      - medium
      - high
    ResponseFileSearchCallCompletedEvent:
      type: object
      description: Emitted when a file search call is completed (results found).
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.file_search_call.completed`.

            '
          enum:
          - response.file_search_call.completed
        output_index:
          type: integer
          description: 'The index of the output item that the file search call is initiated.

            '
        item_id:
          type: string
          description: 'The ID of the output item that the file search call is initiated.

            '
        sequence_number:
          type: integer
          description: The sequence number of this event.
      required:
      - type
      - output_index
      - item_id
      - sequence_number
    ResponseFileSearchCallInProgressEvent:
      type: object
      description: Emitted when a file search call is initiated.
      properties:
        type:
          type: string
          description: 'The type of the event. Always `response.file_search_call.in_progress`.

            '
          enum:
          - response.file_search_call.in_progress
        output_index:
          type: integer
          description: 'The index of the output item that the file search call is initiated.

            '
        item_id:
          type: string
          description: 'The ID of the output item that the file search call is initiated.

            '
        sequence_number:
          type: integer
          description: The sequence number of this event.
      required:
      - type
      - output_index
      - item_id
      - sequence_number
    ComputerUsePreviewTool:
      properties:
        type:
          type: string
          enum:
          - computer_use_preview
          description: The type of the computer use tool. Always `computer_use_preview`.
          default: computer_use_preview
        environment:
          $ref: '#/components/schemas/ComputerEnvironment'
          description: The type of computer environment to control.
        display_width:
          type: integer
          description: The width of the computer display.
        display_height:
          type: integer
          description: The height of the computer display.
      type: object
      required:
      - type
      - environment
      - display_width
      - display_height
      title: Computer use preview
      description: A tool that controls a virtual computer. Learn more in the computer tool guide.
    TextResponseFormatConfiguration:
      description: 'Specifies the required output format. Use `type: json_schema` to enforce a schema; `type: text` is the default.

        '
      anyOf:
      - $ref: '#/components/schemas/responses_ResponseFormatText'
      - $ref: '#/components/schemas/TextResponseFormatJsonSchema'
      - $ref: '#/components/schemas/responses_ResponseFormatJsonObject'
      discriminator:
        propertyName: type
    WebSearchActionSearch:
      type: object
      title: Search action
      description: 'Action type "search" - Performs a web search query.

        '
      properties:
        type:
          type: string
          enum:
          - search
          description: 'The action type.

            '
        query:
          type: string
          description: 'The search query.

            '
        sources:
          type: array
          title: Web search sources
          description: 'The sources used in the search.

            '
          items:
            type: object
            title: Web search source
            description: 'A source used in the search.

              '
            properties:
              type:
                type: string
                enum:
                - url
                description: 'The type of source. Always `url`.

                  '
              url:
                type: string
                description: 'The URL of the source.

                  '
            required:
            - type
            - url
      required:
      - type
      - query
    DragPoint:
      properties:
        x:
          type: integer
          description: The x-coordinate.
        y:
          type: integer
          description: The y-coordinate.
      type: object
      required:
      - x
      - y
      title: Coordinate
      description: 'An x/y coordinate pair, e.g. `{ x: 100, y: 200 }`.'
    ResponseCodeInterpreterCallCodeDoneEvent:
      type: object
      description: Emitted when the code snippet is finalized by the code interpreter.
      properties:
        type:
          type: string
          description: The type of the event. Always `response.code_interpreter_call_code.done`.
          enum:
          - response.code_interpreter_call_code.done
        output_index:
          type: integer
          description: The index of the output item in the response for which the code is finalized.
        item_id:
          type: string
          description: The unique identifier of the code interpreter tool call item.
        code:
          type: string
          description: The final code snippet output by the code interpreter.
        sequence_number:
          type: integer
          description: The sequence number of this event, used to order streaming events.
      required:
      - type
      - output_index
      - item_id
      - code
      - sequence_number
    OutputMessage:
      type: object
      title: Output message
      description: 'An output message from the model.

        '
      properties:
        id:
          type: string
          description: 'The unique ID of the output message.

            '
        type:
          type: string
          description: 'The type of the output message. Always `message`.

            '
          enum:
          - message
          default: message
        role:
          type: string
          description: 'The role of the output message. Always `assistant`.

            '
          enum:
          - assistant
        content:
          type: array
          description: 'The content of the output message.

            '
          items:
            $ref: '#/components/schemas/OutputMessageContent'
        status:
          type: string
          description: 'The status of the message input. One of `in_progress`, `completed`, or

            `incomplete`. Populated when input items are returned via API.

            '
          enum:
          - in_progress
          - completed
          - incomplete
      required:
      - id
      - type
      - role
      - content
      - status
    CodeInterpreterOutputLogs:
      properties:
        type:
          type: string
          enum:
          - logs
          description: The type of the output. Always `logs`.
          default: logs
        logs:
          type: string
          description: The logs output from the code interpreter.
      type: object
      required:
      - type
      - logs
      title: Code interpreter output logs
      description: The logs output from the code interpreter.
    MCPListToolsTool:
      type: object
      title: MCP list tools tool
      description: 'A tool available on an MCP server.

        '
      properties:
        name:
          type: string
          description: 'The name of the tool.

            '
        description:
          type:
          - string
          - 'null'
          description: 'The description of the tool.

            '
        input_schema:
          type: object
          description: 'The JSON schema describing the tool''s input.

            '
        annotations:
          type:
          - object
          - 'null'
          description: 'Additional annotations about the tool.

            '
      required:
      - name
      - input_schema
    ResponseImageGenCallInProgressEvent:
      type: object
      title: ResponseImageGenCallInProgressEvent
      description: 'Emitted when an image generation tool call is in progress.

        '
      properties:
        type:
          type: string
          enum:
          - response.image_generation_call.in_progress
          description: The type of the event. Always 'response.image_generation_call.in_progress'.
        output_index:
          type: integer
          description: The index of the output item in the response's output array.
        item_id:
          type: string
          description: The unique identifier of the image generation item being processed.
        sequence_number:
          type: integer
          description: The sequence number of the image generation item being processed.
      required:
      - type
      - output_index
      - item_id
      - sequence_number
    TextResponseFormatJsonSchema:
      type: object
      title: JSON schema
      description: 'JSON Schema response format used to generate structured JSON responses.

        Learn more in the Structured Outputs guide.

        '
      properties:
        type:
          type: string
          description: The type of response format being defined. Always `json_schema`.
          enum:
          - json_schema
        description:
          type: string
          description: 'A description of what the response format is for, used by the model to

            determine how to respond in the format.

            '
        name:
          type: string
          description: 'The name of the response format. Must be a-z, A-Z, 0-9, or contain

            underscores and dashes, with a maximum length of 64.

            '
        schema:
          $ref: '#/components/schemas/responses_ResponseFormatJsonSchemaSchema'
        strict:
          type:
          - boolean
          - 'null'
          default: false
          description: 'Whether to enable strict schema adherence when generating the output.

            If true, the model will follow the exact schema; only a subset of JSON Schema is supported.

            '
      required:
      - type
      - schema
      - name
    ResponseOutputTextAnnotationAddedEvent:
      type: object
      title: ResponseOutputTextAnnotationAddedEvent
      description: 'Emitted when an annotation is added to output text content.

        '
      properties:
        type:
          type: string
          enum:
          - response.output_text.annotation.added
          description: The type of the event. Always 'response.output_text.annotation.added'.
        item_id:
          type: string
          description: The unique identifier of the item to which the annotation is being added.
        output_index:
          type: integer
          description: The index of the output item in the response's output array.
        content_index:
          type: integer
          description: The index of the content part within the output item.
        annotation_index:
          type: integer
          description: The index of the annotation within the content part.
        sequence_number:
          type: integer
          description: The sequence number of this event.
        annotation:
          type: object
          description: The annotation object being added. (See annotation schema for details.)
      required:
      - type
      - item_id
      - output_index
      - content_index
      - annotation_index
      - annotation
      - sequence_number
    MCPApprovalRequest:
      type: object
      title: MCP approval request
      description: 'A request for human approval of a tool invocation.

        '
      properties:
        type:
          type: string
          enum:
          - mcp_approval_request
          default: mcp_approval_request
          description: 'The type of the item. Always `mcp_approval_request`.

            '
        id:
          type: string
          description: 'The unique ID of the approval request.

            '
        server_label:
          type: string
          description: 'The label of the MCP server making the request.

            '
        name:
          type: string
          description: 'The name of the tool to run.

            '
        arguments:
          type: string
          description: 'A JSON string of arguments for the tool.

            '
      required:
      - type
      - id
      - server_label
      - name
      - arguments
    ImageDetail:
      type: string
      enum:
      - low
      - high
      - auto
    Scroll:
      type: object
      title: Scroll
      description: 'A scroll action.

        '
      properties:
        type:
          type: string
          enum:
          - scroll
          default: scroll
          description: "Specifies the event type. For a scroll action, this property is \nalways set to `scroll`.\n"
        x:
          type: integer
          description: 'The x-coordinate where the scroll occurred.

            '
        y:
          type: integer
          description: 'The y-coordinate where the scroll occurred.

            '
        scroll_x:
          type: integer
          description: 'The horizontal scroll distance.

            '
        scroll_y:
          type: integer
          description: 'The vertical scroll distance.

            '
      required:
      - type
      - x
      - y
      - scroll_x
      - scroll_y
    Drag:
      type: object
      title: Drag
      description: 'A drag action.

        '
      properties:
        type:
          type: string
          enum:
          - drag
          default: drag
          description: "Specifies the event type. For a drag action, this property is \nalways set to `drag`.\n"
        path:
          type: array
          description: "An array of coordinates representing the path of the drag action. Coordinates will appear as an array\nof objects, eg\n```\n[\n  { x: 100, y: 200 },\n  { x: 200, y: 300 }\n]\n```\n"
          items:
            $ref: '#/components/schemas/DragPoint'
      required:
      - type
      - path
    CompactionSummaryItemParam:
      properties:
        id:
          type:
          - string
          - 'null'
          description: The ID of the compaction item.
        type:
          type: string
          enum:
          - compaction
          description: The type of the item. Always `compaction`.
          default: compaction
        encrypted_content:
          type: string
          maxLength: 10485760
      type: object
      required:
      - type
      - encrypted_content
      title: Compaction item
      description: A compaction item generated by the `v1/responses/compact` API.
    ResponseLogProb:
      type: object
      description: "A logprob is the logarithmic probability that the model assigns to producing \na particular token at a given position in the sequence. Less-negative (higher) \nlogprob values indicate greater model confidence in that token choice.\n"
      properties:
        token:
          description: A possible text token.
          type: string
        logprob:
          description: 'The log probability of this token.

            '
          type: number
        top_logprobs:
          description: 'The log probability of the top 20 most likely tokens.

            '
          type: array
          items:
            type: object
            properties:
              token:
                description: A possible text token.
                type: string
              logprob:
                description: The log probability of this token.
                type: number
      required:
      - token
      - logprob
    InputFidelity:
      type: string
      enum:
      - high
      - low
      description: Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
    ConversationParam:
      description: 'The conversation that this response belongs to. Items from this conversation are prepended to `input_items` for this response request.

        Input items and output items from this response are automatically added to this conversation after this response completes.

        '
      anyOf:
      - type: string
        title: Conversation ID
        description: 'The unique ID of the conversation.

          '
      - $ref: '#/components/schemas/ConversationParam-2'
    LocalShellExecAction:
      properties:
        type:
          type: string
          enum:
          - exec
          description: The type of the local shell action. Always `exec`.
          default: exec
        command:
          items:
            type: string
          type: array
          description: The command to run.
        timeout_ms:
          type:
          - integer
          - 'null'
          description: Optional timeout in milliseconds for the command.
        working_directory:
          type:
          - string
          - 'null'
          description: Optional working directory to run the command in.
        env:
          additionalProperties:
            type: string
          type: object
          description: Environment variables to set for the command.
        user:
          type:
          - string
          - 'null'
          description: Optional user to run the command as.
      type: object
      required:
      - type
      - command
      - env
      title: Local shell exec action
      description: Execute a shell command on the server.
    MCPListTools:
      type: object
      title: MCP list tools
      description: 'A list of tools available on an MCP server.

        '
      properties:
        type:
          type: string
          enum:
          - mcp_list_tools
          default: mcp_list_tools
          description: 'The type of the item. Always `mcp_list_tools`.

            '
        id:
          type: string
          description: 'The unique ID of the list.

            '
        server_label:
          type: string
          description: 'The label of the MCP server.

            '
        tools:
          type: array
          items:
            $ref: '#/components/schemas/MCPListToolsTool'
          description: 'The tools available on the server.

            '
        error:
          type:
          - string
          - 'null'
          description: 'Error message if the server could not list tools.

            '
      required:
      - type
      - id
      - server_label
      - tools
    HybridSearchOptions:
      properties:
        embedding_weight:
          type: number
          description: The weight of the embedding in the reciprocal ranking fusion.
        text_weight:
          type: number
          description: The weight of the text in the reciprocal ranking fusion.
      type: object
      required:
      - embedding_weight
      - text_weight
    Response:
      title: The response object
      allOf:
      - $ref: '#/components/schemas/ModelResponseProperties'
      - $ref: '#/components/schemas/ResponseProperties'
      - type: object
        properties:
          id:
            type: string
            description: 'Unique identifier for this Response.

              '
          object:
            type: string
            description: 'The object type of this resource - always set to `response`.

              '
            enum:
            - response
          status:
            type: string
            description: 'The status of the response generation. One of `completed`, `failed`,

              `in_progress`, `cancelled`, `queued`, or `incomplete`.

              '
            enum:
            - completed
            - failed
            - in_progress
            - cancelled
            - queued
            - incomplete
          created_at:
            type: number
            description: 'Unix timestamp (in seconds) of when this Response was created.

              '
          error:
            $ref: '#/components/schemas/ResponseError'
          incomplete_details:
            type:
            - object
            - 'null'
            description: 'Details about why the response is incomplete.

              '
            properties:
              reason:
                type: string
                description: The reason why the response is incomplete.
                enum:
                - max_output_tokens
                

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