> ## Documentation Index > Fetch the complete documentation index at: https://docs.sudoapp.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Response ## OpenAPI ````yaml https://sudoapp.dev/api/openapi.json post /v1/responses openapi: 3.1.0 info: title: sudo-api description: '' license: name: '' version: 0.1.0 servers: [] security: - api_key: [] - privy_token: [] tags: - name: Sudo API description: 'Sudo: The Unified AI Developer Platform' paths: /v1/responses: post: tags: - Responses API summary: Create Response operationId: create_response requestBody: content: application/json: schema: $ref: '#/components/schemas/ResponsesRequest' required: true responses: '200': description: Response created successfully content: application/json: schema: $ref: '#/components/schemas/Response' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '502': description: Bad gateway error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - api_key: [] components: schemas: ResponsesRequest: type: object description: Request object for creating a response properties: background: type: - boolean - 'null' description: >- Whether to process the response in the background. If true, the response will be processed asynchronously. conversation: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponsesConvo' description: >- The ID of an existing conversation to add this response to, or configuration for a new conversation. include: type: - array - 'null' items: {} description: A list of items to include in the response output. input: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponsesInput' description: >- Input to the model. Can be a text string or an array of input items. instructions: type: - string - 'null' description: Instructions for the model on how to behave and respond. max_output_tokens: type: - integer - 'null' format: int32 description: The maximum number of tokens to generate in the response output. minimum: 0 max_tool_calls: type: - integer - 'null' format: int32 description: >- The maximum number of tool calls that can be made in a single response. minimum: 0 metadata: description: >- Set of key-value pairs that can be attached to an object for storing additional information. model: type: - string - 'null' description: >- The model to use for generating the response (e.g., "gpt-4o", "gpt-4o-mini"). parallel_tool_calls: type: - boolean - 'null' description: >- Whether to enable parallel tool calls. If true, the model can make multiple tool calls simultaneously. previous_response_id: type: - string - 'null' description: >- The ID of a previous response to continue from. Used for multi-turn interactions. prompt: description: Reference to a prompt template and its variables prompt_cache_key: type: - string - 'null' description: >- Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the user field. reasoning: description: Configuration for reasoning/chain-of-thought capabilities. safety_identifier: type: - string - 'null' description: An identifier for safety and content moderation purposes. service_tier: type: - string - 'null' description: The service tier to use for the request (e.g., "auto", "default"). store: type: - boolean - 'null' description: Whether to store the conversation and response for later retrieval. stream: type: - boolean - 'null' description: >- Whether to stream the response back incrementally using Server-Sent Events (SSE). stream_options: description: Options for configuring streaming behavior. temperature: type: - number - 'null' format: float description: >- Sampling temperature between 0 and 2. Higher values make output more random, lower values more focused. text: description: Configuration for text output formatting and behavior. tool_choice: oneOf: - type: 'null' - $ref: '#/components/schemas/ToolChoice' description: >- Controls which tool the model should call. Can be "none", "auto", "required", or a specific tool. tools: type: - array - 'null' items: {} description: >- A list of tools the model may call. Each tool is a function with a name, description, and parameters. top_logprobs: type: - integer - 'null' format: int32 description: >- Number of most likely tokens to return at each position, along with their log probabilities. minimum: 0 top_p: type: - number - 'null' format: float description: >- Nucleus sampling parameter. The model considers tokens with top_p probability mass. truncation: type: - string - 'null' description: >- The truncation strategy to use when the input exceeds the model's context window. Response: type: object description: A response object representing the output from a model invocation required: - id - object - created_at - model - status properties: background: type: - boolean - 'null' description: Whether the response was generated in the background conversation: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseConversation' description: The ID of the conversation this response belongs to created_at: type: integer format: int64 description: Unix timestamp (in seconds) when the response was created error: description: Error information if the response failed id: type: string description: Unique identifier for the response incomplete_details: oneOf: - type: 'null' - $ref: '#/components/schemas/IncompleteDetails' description: >- Details about why the response is incomplete (if status is "incomplete") instructions: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseInstructions' description: Instructions provided to the model max_output_tokens: type: - integer - 'null' format: int32 description: Maximum number of output tokens minimum: 0 max_tool_calls: type: - integer - 'null' format: int32 description: Maximum number of tool calls minimum: 0 metadata: description: Set of key-value pairs that can be attached to an object model: type: string description: The model used to generate the response object: type: string description: The object type, always "response" output: type: - array - 'null' items: $ref: '#/components/schemas/Item' description: The output items generated by the model parallel_tool_calls: type: - boolean - 'null' description: Whether parallel tool calls are enabled previous_response_id: type: - string - 'null' description: ID of the previous response prompt: description: Prompt configuration prompt_cache_key: type: - string - 'null' description: Prompt cache key reasoning: description: Reasoning configuration safety_identifier: type: - string - 'null' description: Safety identifier service_tier: type: - string - 'null' description: Service tier used status: type: string description: >- The status of the response (e.g., "in_progress", "completed", "failed", "cancelled", "incomplete") temperature: type: - number - 'null' format: float description: Temperature sampling parameter text: description: Text configuration tool_choice: oneOf: - type: 'null' - $ref: '#/components/schemas/ToolChoice' description: Tool choice configuration tools: type: - array - 'null' items: {} description: Tools available to the model top_logprobs: type: - integer - 'null' format: int32 description: Number of top log probabilities to return minimum: 0 top_p: type: - number - 'null' format: float description: Top-p sampling parameter truncation: type: - string - 'null' description: Truncation strategy usage: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseUsage' description: Usage statistics for the API call ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorDetail' ResponsesConvo: oneOf: - type: string description: Conversation ID as a string - description: Conversation configuration object description: >- Conversation identifier or configuration, either as a string ID or a configuration object ResponsesInput: oneOf: - type: string description: A simple text string input - type: array items: $ref: '#/components/schemas/InputItem' description: >- An array of structured input items including messages, tool calls, and other content description: >- Input to the model, either as a simple text string or as a structured array of input items ToolChoice: oneOf: - type: string description: 'String value: "none", "auto", or "required"' - description: Object specifying a particular tool to use description: Tool choice configuration, controlling which tools the model can use ResponseConversation: type: object description: Conversation information associated with the response required: - id properties: id: type: string description: The unique identifier of the conversation IncompleteDetails: type: object description: Details about why a response is incomplete required: - reason properties: reason: type: string description: >- The reason the response is incomplete (e.g., "max_tokens", "content_filter") ResponseInstructions: oneOf: - type: string description: Instructions as a single text string - type: array items: {} description: Instructions as a structured list description: >- Instructions for the model, either as a simple text string or structured list Item: oneOf: - type: object description: An input message from the user or system required: - content - role - status - type properties: content: $ref: '#/components/schemas/MessageContent' description: The content of the message role: type: string description: The role of the message sender status: type: string description: The status of the message type: type: string description: The type identifier for this item - type: object description: An output message generated by the assistant required: - content - id - role - status - type properties: content: type: array items: $ref: '#/components/schemas/OutputMessage' description: The content parts of the output message id: type: string description: Unique identifier for this message role: type: string description: The role (typically "assistant") status: type: string description: The status of the message generation type: type: string description: The type identifier for this item - type: object description: A file search tool call for searching through uploaded files required: - id - queries - status - results - type properties: id: type: string description: Unique identifier for this tool call queries: type: array items: {} description: Search queries to execute results: type: array items: {} description: Search results status: type: string description: The status of the file search type: type: string description: The type identifier for this item - type: object description: A computer use tool call for controlling computer actions required: - action - call_id - id - pending_safety_checks - status - type properties: action: description: The action to be performed call_id: type: string description: Unique identifier for this call id: type: string description: Unique identifier for this item pending_safety_checks: type: array items: {} description: Safety checks that are pending approval status: type: string description: The status of the computer tool call type: type: string description: The type identifier for this item - type: object description: Output from a computer use tool call required: - call_id - output - type properties: acknowledged_safety_checks: type: - array - 'null' items: {} description: Safety checks that were acknowledged call_id: type: string description: The call ID this output corresponds to id: type: - string - 'null' description: Unique identifier for this item output: description: The output from the computer tool status: type: - string - 'null' description: The status of the output type: type: string description: The type identifier for this item - type: object description: A web search tool call for searching the internet required: - action - id - status - type properties: action: description: The search action to perform id: type: string description: Unique identifier for this tool call status: type: string description: The status of the web search type: type: string description: The type identifier for this item - type: object description: A function tool call initiated by the model required: - arguments - call_id - name - type properties: arguments: type: string description: JSON string of arguments to pass to the function call_id: type: string description: Unique identifier for this call id: type: - string - 'null' description: Unique identifier for this item name: type: string description: Name of the function to call status: type: - string - 'null' description: The status of the function call type: type: string description: The type identifier for this item - type: object description: Output from a function tool call required: - call_id - output - type properties: call_id: type: string description: The call ID this output corresponds to id: type: - string - 'null' description: Unique identifier for this item output: $ref: '#/components/schemas/ToolCallOutput' description: The output from the function status: type: - string - 'null' description: The status of the output type: type: string description: The type identifier for this item - type: object description: Reasoning content showing the model's chain of thought required: - id - summary - type - content properties: content: type: array items: {} description: Detailed reasoning content encrypted_content: type: - string - 'null' description: Encrypted reasoning content (if applicable) id: type: string description: Unique identifier for this reasoning item status: type: - string - 'null' description: The status of the reasoning summary: type: array items: {} description: Summary of the reasoning type: type: string description: The type identifier for this item - type: object description: An image generation tool call required: - id - result - status - type properties: id: type: string description: Unique identifier for this generation call result: type: string description: The result/output of the image generation status: type: string description: The status of the image generation type: type: string description: The type identifier for this item - type: object description: A code interpreter tool call for executing code required: - code - container_id - id - outputs - status - type properties: code: type: string description: The code to be executed container_id: type: string description: The container ID where code is executed id: type: string description: Unique identifier for this tool call outputs: type: array items: {} description: Outputs from the code execution status: type: string description: The status of the code execution type: type: string description: The type identifier for this item - type: object description: A local shell command execution call required: - action - call_id - id - status - type properties: action: description: The shell action to perform call_id: type: string description: Unique identifier for this call id: type: string description: Unique identifier for this item status: type: string description: The status of the shell call type: type: string description: The type identifier for this item - type: object description: Output from a local shell command execution required: - id - output - type properties: id: type: string description: Unique identifier for this output output: type: string description: The output from the shell command status: type: - string - 'null' description: The status of the output type: type: string description: The type identifier for this item - type: object description: A list of available MCP (Model Context Protocol) tools required: - id - server_label - tools - type properties: error: type: - string - 'null' description: Error message if tool listing failed id: type: string description: Unique identifier for this list server_label: type: string description: Label of the MCP server tools: type: array items: {} description: List of available tools type: type: string description: The type identifier for this item - type: object description: A request for approval to execute an MCP tool required: - arguments - id - name - server_label - type properties: arguments: type: string description: Arguments for the tool call id: type: string description: Unique identifier for this request name: type: string description: Name of the tool requiring approval server_label: type: string description: Label of the MCP server type: type: string description: The type identifier for this item - type: object description: Response to an MCP tool approval request required: - approval_request_id - approve - type properties: approval_request_id: type: string description: The ID of the approval request this responds to approve: type: boolean description: Whether the tool execution is approved id: type: - string - 'null' description: Unique identifier for this response reason: type: - string - 'null' description: Reason for approval or rejection type: type: string description: The type identifier for this item - type: object description: An MCP tool call required: - arguments - id - name - server_label - type properties: approval_request_id: type: - string - 'null' description: ID of the approval request (if approval was required) arguments: type: string description: Arguments for the tool call error: type: - string - 'null' description: Error message if the tool call failed id: type: string description: Unique identifier for this tool call name: type: string description: Name of the tool to call output: type: - string - 'null' description: Output from the tool call server_label: type: string description: Label of the MCP server status: type: - string - 'null' description: The status of the tool call type: type: string description: The type identifier for this item - type: object description: Output from a custom tool call required: - call_id - output - type properties: call_id: type: string description: The call ID this output corresponds to id: type: - string - 'null' description: Unique identifier for this item output: $ref: '#/components/schemas/ToolCallOutput' description: The output from the custom tool type: type: string description: The type identifier for this item - type: object description: A custom tool call required: - call_id - input - name - type properties: call_id: type: string description: Unique identifier for this call id: type: - string - 'null' description: Unique identifier for this item input: type: string description: Input to the custom tool name: type: string description: Name of the custom tool type: type: string description: The type identifier for this item description: >- A structured item in the conversation, representing messages, tool calls, reasoning, and other interaction types ResponseUsage: type: object description: Token usage statistics for the response required: - input_tokens - output_tokens - total_tokens properties: input_tokens: type: integer format: int32 description: Number of tokens in the input minimum: 0 input_tokens_details: description: Breakdown of input token details output_tokens: type: integer format: int32 description: Number of tokens in the output minimum: 0 output_tokens_details: description: Breakdown of output token details total_tokens: type: integer format: int32 description: Total number of tokens used minimum: 0 ErrorDetail: type: object required: - message - type properties: message: type: string type: type: string InputItem: oneOf: - type: object description: A simple input message with content and role required: - content - role properties: content: $ref: '#/components/schemas/MessageContent' description: >- The content of the message, which can be text or structured content parts role: type: string description: >- The role of the message sender (e.g., "user", "assistant", "system") - $ref: '#/components/schemas/Item' description: A structured item with additional metadata and type information - type: object description: A reference to an existing item by ID required: - id properties: id: type: string description: The unique identifier of the referenced item type: type: - string - 'null' description: The type of the referenced item description: >- An individual item in the input array, which can be a message, structured item, or reference to an existing item MessageContent: oneOf: - type: string description: Plain text content - type: array items: $ref: '#/components/schemas/ContentPart' description: Array of structured content parts supporting multimodal inputs description: >- Message content, which can be either plain text or an array of structured content parts (text, images, files, audio) OutputMessage: oneOf: - type: object description: Text output from the assistant required: - annotations - text - type properties: annotations: type: array items: {} description: >- Annotations associated with the text (e.g., citations, file references) logprobs: type: - array - 'null' items: {} description: Log probabilities for the generated tokens text: type: string description: The generated text content type: type: string enum: - output_text - type: object description: Refusal message when the assistant declines to fulfill the request required: - refusal - type properties: refusal: type: string description: The refusal message explaining why the request was declined type: type: string enum: - refusal description: Output message content generated by the assistant ToolCallOutput: oneOf: - type: string description: Simple text output - type: array items: {} description: Structured array output description: Output from a tool call, which can be text or structured data ContentPart: oneOf: - type: object description: Text content part required: - text - type properties: text: type: string description: The text content type: type: string enum: - input_text - type: object description: Image content part required: - detail - type properties: detail: type: string description: Level of detail for image processing ("low", "high", "auto") file_id: type: - string - 'null' description: ID of a previously uploaded file containing the image image_url: type: - string - 'null' description: URL of the image to process type: type: string enum: - input_image - type: object description: File content part for document processing required: - type properties: file_data: type: - string - 'null' description: Base64-encoded file data file_id: type: - string - 'null' description: ID of a previously uploaded file file_url: type: - string - 'null' description: URL of the file to process filename: type: - string - 'null' description: Name of the file type: type: string enum: - input_file - type: object description: Audio content part required: - input_audio - type properties: input_audio: $ref: '#/components/schemas/Audio' description: Audio input data and format type: type: string enum: - input_audio description: >- A part of message content, supporting different content types (text, images, files, audio) for multimodal input Audio: type: object description: Audio input data required: - data - format properties: data: type: string description: Base64-encoded audio data format: type: string description: Audio format (e.g., "wav", "mp3") ````