OpenAPI Specification
openapi: 3.0.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:
FunctionAndCustomToolCallOutput:
discriminator:
propertyName: type
anyOf:
- $ref: '#/components/schemas/InputTextContent'
- $ref: '#/components/schemas/InputImageContent'
- $ref: '#/components/schemas/InputFileContent'
ModelIdsCompaction:
type: string
description: Model ID used to generate the response, like `gpt-5` or `o3`.
ApproximateLocation:
properties:
type:
type: string
enum:
- approximate
description: The type of location approximation. Always `approximate`.
default: approximate
country:
type: string
description: The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.
nullable: true
region:
type: string
description: Free text input for the region of the user, e.g. `California`.
nullable: true
city:
type: string
description: Free text input for the city of the user, e.g. `San Francisco`.
nullable: true
timezone:
type: string
description: The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.
nullable: true
type: object
required:
- type
ReasoningEffort:
type: string
nullable: true
enum:
- none
- minimal
- low
- medium
- high
default: medium
description: 'Controls how much reasoning effort the model uses. Lower settings are faster and use fewer tokens; higher settings provide more detailed reasoning.
'
LocalShellToolCall:
type: object
title: Local shell call
description: 'A tool call to run a command on the local shell.
'
properties:
type:
type: string
enum:
- local_shell_call
default: local_shell_call
description: 'The type of the local shell call. Always `local_shell_call`.
'
id:
type: string
description: 'The unique ID of the local shell call.
'
call_id:
type: string
description: 'The unique ID of the local shell tool call generated by the model.
'
action:
$ref: '#/components/schemas/LocalShellExecAction'
status:
type: string
enum:
- in_progress
- completed
- incomplete
description: 'The status of the local shell call.
'
required:
- type
- id
- call_id
- action
- status
OutputTextContent:
properties:
type:
type: string
enum:
- output_text
description: The type of the output text. Always `output_text`.
default: output_text
text:
type: string
description: The text output from the model.
annotations:
items:
$ref: '#/components/schemas/responses_Annotation'
type: array
description: The annotations of the text output.
logprobs:
items:
$ref: '#/components/schemas/LogProb'
type: array
type: object
required:
- type
- text
- annotations
title: Output text
description: A text output from the model.
ApplyPatchToolCall:
properties:
type:
type: string
enum:
- apply_patch_call
description: The type of the item. Always `apply_patch_call`.
default: apply_patch_call
id:
type: string
description: The unique ID of the apply patch tool call. Populated when this item is returned via API.
call_id:
type: string
description: The unique ID of the apply patch tool call generated by the model.
status:
$ref: '#/components/schemas/ApplyPatchCallStatus'
description: The status of the apply patch tool call. One of `in_progress` or `completed`.
operation:
title: Apply patch operation
description: One of the create_file, delete_file, or update_file operations applied via apply_patch.
discriminator:
propertyName: type
anyOf:
- $ref: '#/components/schemas/ApplyPatchCreateFileOperation'
- $ref: '#/components/schemas/ApplyPatchDeleteFileOperation'
- $ref: '#/components/schemas/ApplyPatchUpdateFileOperation'
created_by:
type: string
description: The ID of the entity that created this tool call.
type: object
required:
- type
- id
- call_id
- status
- operation
title: Apply patch tool call
description: A tool call that applies file diffs by creating, deleting, or updating files.
Type:
type: object
title: Type
description: 'An action to type in text.
'
properties:
type:
type: string
enum:
- type
default: type
description: "Specifies the event type. For a type action, this property is \nalways set to `type`.\n"
text:
type: string
description: 'The text to type.
'
required:
- type
- text
FunctionShellCallOutputContent:
properties:
stdout:
type: string
stderr:
type: string
outcome:
title: Function shell call outcome
description: Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk.
discriminator:
propertyName: type
anyOf:
- $ref: '#/components/schemas/FunctionShellCallOutputTimeoutOutcome'
- $ref: '#/components/schemas/FunctionShellCallOutputExitOutcome'
created_by:
type: string
type: object
required:
- stdout
- stderr
- outcome
title: Shell call output content
description: The content of a shell call output.
ResponseProperties:
type: object
required:
- model
properties:
previous_response_id:
type: string
description: 'The unique ID of the previous response to the model. Use this to create multi-turn conversations. Cannot be used with `conversation`.
'
nullable: true
model:
description: 'Model ID used to generate the response (e.g., `gpt-4o` or `o3`). See your provider''s model guide for available options.
'
type: string
reasoning:
$ref: '#/components/schemas/Reasoning'
nullable: true
background:
type: boolean
description: 'Whether to run the model response in the background.
'
default: false
nullable: true
max_output_tokens:
description: 'An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.
'
type: integer
nullable: true
max_tool_calls:
description: 'The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored.
'
type: integer
nullable: true
text:
$ref: '#/components/schemas/ResponseTextParam'
tools:
$ref: '#/components/schemas/ToolsArray'
tool_choice:
$ref: '#/components/schemas/ToolChoiceParam'
prompt:
$ref: '#/components/schemas/Prompt'
truncation:
type: string
description: "The truncation strategy to use for the model response.\n- `auto`: If the input to this Response exceeds\n the model's context window size, the model will truncate the\n response to fit the context window by dropping items from the beginning of the conversation.\n- `disabled` (default): If the input size will exceed the context window\n size for a model, the request will fail with a 400 error.\n"
enum:
- auto
- disabled
default: disabled
nullable: true
ResponseCustomToolCallInputDeltaEvent:
title: ResponseCustomToolCallInputDelta
type: object
description: 'Event representing a delta (partial update) to the input of a custom tool call.
'
properties:
type:
type: string
enum:
- response.custom_tool_call_input.delta
description: The event type identifier.
sequence_number:
type: integer
description: The sequence number of this event.
output_index:
type: integer
description: The index of the output this delta applies to.
item_id:
type: string
description: Unique identifier for the API item associated with this event.
delta:
type: string
description: The incremental input data (delta) for the custom tool call.
required:
- type
- output_index
- item_id
- delta
- sequence_number
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
nullable: true
description: Optional timeout in milliseconds for the command.
working_directory:
type: string
nullable: true
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
nullable: true
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.
ContainerFileCitationBody:
properties:
type:
type: string
enum:
- container_file_citation
description: The type of the container file citation. Always `container_file_citation`.
default: container_file_citation
container_id:
type: string
description: The ID of the container file.
file_id:
type: string
description: The ID of the file.
start_index:
type: integer
description: The index of the first character of the container file citation in the message.
end_index:
type: integer
description: The index of the last character of the container file citation in the message.
filename:
type: string
description: The filename of the container file cited.
type: object
required:
- type
- container_id
- file_id
- start_index
- end_index
- filename
title: Container file citation
description: A citation for a container file used to generate a model response.
WebSearchActionFind:
type: object
title: Find action
description: 'Action type "find": Searches for a pattern within a loaded page.
'
properties:
type:
type: string
enum:
- find
description: 'The action type.
'
url:
type: string
format: uri
description: 'The URL of the page searched for the pattern.
'
pattern:
type: string
description: 'The pattern or text to search for within the page.
'
required:
- type
- url
- pattern
CodeInterpreterToolCall:
type: object
title: Code interpreter tool call
description: 'A tool call to run code.
'
properties:
type:
type: string
enum:
- code_interpreter_call
default: code_interpreter_call
description: 'The type of the code interpreter tool call. Always `code_interpreter_call`.
'
id:
type: string
description: 'The unique ID of the code interpreter tool call.
'
status:
type: string
enum:
- in_progress
- completed
- incomplete
- interpreting
- failed
description: 'The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`.
'
container_id:
type: string
description: 'The ID of the container used to run the code.
'
code:
type: string
description: 'The code to run, or null if not available.
'
nullable: true
outputs:
type: array
items:
discriminator:
propertyName: type
anyOf:
- $ref: '#/components/schemas/CodeInterpreterOutputLogs'
- $ref: '#/components/schemas/CodeInterpreterOutputImage'
discriminator:
propertyName: type
description: 'The outputs generated by the code interpreter, such as logs or images.
Can be null if no outputs are available.
'
nullable: true
required:
- type
- id
- status
- container_id
- code
- outputs
CustomToolCallOutput:
type: object
title: Custom tool call output
description: 'The output of a custom tool call from your code, being sent back to the model.
'
properties:
type:
type: string
enum:
- custom_tool_call_output
default: custom_tool_call_output
description: 'The type of the custom tool call output. Always `custom_tool_call_output`.
'
id:
type: string
description: 'The unique ID of the custom tool call output in the platform.
'
call_id:
type: string
description: 'The call ID, used to map this custom tool call output to a custom tool call.
'
output:
description: 'The output from the custom tool call generated by your code.
Can be a string or an list of output content.
'
anyOf:
- type: string
description: 'A string of the output of the custom tool call.
'
title: string output
- type: array
items:
$ref: '#/components/schemas/FunctionAndCustomToolCallOutput'
title: output content list
description: 'Text, image, or file output of the custom tool call.
'
required:
- type
- call_id
- output
ContainerMemoryLimit:
type: string
enum:
- 1g
- 4g
- 16g
- 64g
ResponseMCPListToolsFailedEvent:
type: object
title: ResponseMCPListToolsFailedEvent
description: 'Emitted when the attempt to list available MCP tools has failed.
'
properties:
type:
type: string
enum:
- response.mcp_list_tools.failed
description: The type of the event. Always 'response.mcp_list_tools.failed'.
item_id:
type: string
description: The ID of the MCP tool call item that failed.
output_index:
type: integer
description: The index of the output item that failed.
sequence_number:
type: integer
description: The sequence number of this event.
required:
- type
- item_id
- output_index
- sequence_number
Summary:
properties:
type:
type: string
enum:
- summary_text
description: The type of the object. Always `summary_text`.
default: summary_text
text:
type: string
description: A summary of the reasoning output from the model so far.
type: object
required:
- type
- text
title: Summary text
description: A summary text from the model.
ResponseMCPCallArgumentsDeltaEvent:
type: object
title: ResponseMCPCallArgumentsDeltaEvent
description: 'Emitted when there is a delta (partial update) to the arguments of an MCP tool call.
'
properties:
type:
type: string
enum:
- response.mcp_call_arguments.delta
description: The type of the event. Always 'response.mcp_call_arguments.delta'.
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.
delta:
type: string
description: 'A JSON string containing the partial update to the arguments for the MCP tool call.
'
sequence_number:
type: integer
description: The sequence number of this event.
required:
- type
- output_index
- item_id
- delta
- sequence_number
FunctionShellCallOutputItemParam:
properties:
id:
type: string
description: The unique ID of the function shell tool call output. Populated when this item is returned via API.
nullable: true
call_id:
type: string
maxLength: 64
minLength: 1
description: The unique ID of the function shell tool call generated by the model.
type:
type: string
enum:
- shell_call_output
description: The type of the item. Always `function_shell_call_output`.
default: shell_call_output
output:
items:
$ref: '#/components/schemas/FunctionShellCallOutputContentParam'
type: array
description: Captured chunks of stdout and stderr output, along with their associated outcomes.
max_output_length:
type: integer
description: The maximum number of UTF-8 characters captured for this shell call's combined output.
nullable: true
type: object
required:
- call_id
- type
- output
title: Function shell tool call output
description: The streamed output items emitted by a function shell tool call.
ComputerToolCallOutput:
type: object
title: Computer tool call output
description: 'The output of a computer tool call.
'
properties:
type:
type: string
description: 'The type of the computer tool call output. Always `computer_call_output`.
'
enum:
- computer_call_output
default: computer_call_output
id:
type: string
description: 'The ID of the computer tool call output.
'
call_id:
type: string
description: 'The ID of the computer tool call that produced the output.
'
acknowledged_safety_checks:
type: array
description: 'The safety checks reported by the API that have been acknowledged by the
developer.
'
items:
$ref: '#/components/schemas/ComputerCallSafetyCheckParam'
output:
$ref: '#/components/schemas/ComputerScreenshotImage'
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:
- type
- call_id
- output
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
description: 'Error message if the server could not list tools.
'
nullable: true
required:
- type
- id
- server_label
- tools
FunctionShellCallOutputContentParam:
properties:
stdout:
type: string
maxLength: 10485760
description: Captured stdout output for this chunk of the shell call.
stderr:
type: string
maxLength: 10485760
description: Captured stderr output for this chunk of the shell call.
outcome:
$ref: '#/components/schemas/FunctionShellCallOutputOutcomeParam'
description: The exit or timeout outcome associated with this chunk.
type: object
required:
- stdout
- stderr
- outcome
title: Function shell output chunk
description: Captured stdout and stderr for a portion of a function shell tool call output.
ReasoningTextContent:
properties:
type:
type: string
enum:
- reasoning_text
description: The type of the reasoning text. Always `reasoning_text`.
default: reasoning_text
text:
type: string
description: The reasoning text from the model.
type: object
required:
- type
- text
title: ReasoningTextContent
description: Reasoning text from the model.
ItemReferenceParam:
properties:
type:
type: string
nullable: true
enum:
- item_reference
description: The type of item to reference. Always `item_reference`.
default: item_reference
id:
type: string
description: The ID of the item to reference.
type: object
required:
- id
title: Item reference
description: An internal identifier for an item to reference.
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.
FunctionToolCall:
type: object
title: Function tool call
description: 'A tool call to run a function. Used when the model requests your code to execute a function.
'
properties:
id:
type: string
description: 'The unique ID of the function tool call.
'
type:
type: string
enum:
- function_call
default: function_call
description: 'The type of the function tool call. Always `function_call`.
'
call_id:
type: string
description: 'The unique ID of the function tool call generated by the model.
'
name:
type: string
description: 'The name of the function to run.
'
arguments:
type: string
description: 'A JSON string of the arguments to pass to the function.
'
status:
type: string
description: 'The status of the item. One of `in_progress`, `completed`, or
`incomplete`. Populated when items are returned via API.
'
enum:
- in_progress
- completed
- incomplete
required:
- type
# --- 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