openapi: 3.1.0 info: title: ChatGPT Responses API description: | OpenAI's Responses API is the recommended API primitive for building with OpenAI models. It is an evolution of the Chat Completions API with built-in tools such as web search, file search, computer use, and code interpreter. The Responses API supports multi-turn conversations, streaming, and agentic workflows with a simplified interface. version: 1.0.0 contact: name: OpenAI Support url: https://help.openai.com license: name: OpenAI Terms of Use url: https://openai.com/terms x-logo: url: https://openai.com/content/images/2023/05/openai-avatar.png servers: - url: https://api.openai.com/v1 description: OpenAI Production Server security: - BearerAuth: [] tags: - name: Responses description: Create, retrieve, and manage model responses paths: /responses: post: summary: Chatgpt Create Response description: | Creates a model response. Provide text or image inputs to generate text or JSON outputs. The Responses API supports built-in tools for web search, file search, computer use, and code interpreter, as well as custom function tools. It can also handle multi-turn conversations using the previous_response_id parameter. operationId: createResponse tags: - Responses requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateResponseRequest' examples: BasicTextInput: summary: Basic text input value: model: gpt-4o input: Tell me a three sentence bedtime story about a unicorn. WithSystemInstructions: summary: With system instructions value: model: gpt-4o instructions: You are a helpful coding assistant. input: - role: user content: How do I sort a list in Python? WithWebSearch: summary: With web search tool value: model: gpt-4o tools: - type: web_search_preview input: What was the score of the latest Super Bowl? WithFunctionTool: summary: With function calling value: model: gpt-4o tools: - type: function name: get_weather description: Get the current weather for a location parameters: type: object properties: location: type: string description: The city and state required: - location input: What is the weather in San Francisco? MultiTurn: summary: Multi-turn conversation value: model: gpt-4o previous_response_id: resp_abc123 input: - role: user content: Tell me more about that. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: BasicResponse: summary: Basic text response value: id: resp_abc123def456 object: response created_at: 1709123456 model: gpt-4o-2024-08-06 status: completed output: - type: message id: msg_abc123 role: assistant status: completed content: - type: output_text text: Once upon a time, a sparkly unicorn named Luna danced across rainbow bridges every night. She sprinkled stardust on sleeping children to give them the sweetest dreams. And every morning, she returned to her cloud castle to rest until the next magical evening. annotations: [] usage: input_tokens: 36 output_tokens: 52 total_tokens: 88 '400': description: Bad Request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Createresponse400Example: summary: Default createResponse 400 response x-microcks-default: true value: error: message: example_value type: example_value param: example_value code: example_value '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Createresponse401Example: summary: Default createResponse 401 response x-microcks-default: true value: error: message: example_value type: example_value param: example_value code: example_value '429': description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Createresponse429Example: summary: Default createResponse 429 response x-microcks-default: true value: error: message: example_value type: example_value param: example_value code: example_value '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Createresponse500Example: summary: Default createResponse 500 response x-microcks-default: true value: error: message: example_value type: example_value param: example_value code: example_value x-microcks-operation: delay: 0 dispatcher: FALLBACK /responses/{response_id}: get: summary: Chatgpt Retrieve Response description: | Retrieves a model response with the given ID. operationId: getResponse tags: - Responses parameters: - name: response_id in: path required: true description: The ID of the response to retrieve. schema: type: string example: '500123' - name: include in: query required: false description: | Additional fields to include in the response. Use file_search_call.results to include file search results, message.input_image.image_url to include image URLs, or computer_call_output.output.image_url to include computer call output images. schema: type: array items: type: string enum: - file_search_call.results - message.input_image.image_url - computer_call_output.output.image_url example: [] responses: '200': description: Successful retrieval content: application/json: schema: $ref: '#/components/schemas/ResponseObject' examples: Getresponse200Example: summary: Default getResponse 200 response x-microcks-default: true value: id: abc123 object: response created_at: '2026-01-15T10:30:00Z' model: example_value status: completed output: - type: message id: abc123 role: assistant status: completed content: {} name: Example Title call_id: '500123' arguments: example_value summary: {} usage: input_tokens: 10 input_tokens_details: cached_tokens: 10 output_tokens: 10 output_tokens_details: reasoning_tokens: 10 total_tokens: 10 error: code: example_value message: example_value incomplete_details: reason: max_output_tokens instructions: example_value metadata: example_value temperature: 42.5 top_p: 42.5 max_output_tokens: 10 previous_response_id: '500123' reasoning: effort: low summary: example_value text: example_value tools: - type: function name: Example Title description: A sample description. parameters: example_value strict: true vector_store_ids: {} max_num_results: 10 ranking_options: {} container: {} display_width: 10 display_height: 10 environment: browser server_label: example_value server_url: https://www.example.com allowed_tools: {} headers: example_value tool_choice: example_value truncation: example_value user: example_value service_tier: example_value '404': description: Not Found - Response does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Getresponse404Example: summary: Default getResponse 404 response x-microcks-default: true value: error: message: example_value type: example_value param: example_value code: example_value x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: summary: Chatgpt Delete Response description: | Deletes a model response with the given ID. operationId: deleteResponse tags: - Responses parameters: - name: response_id in: path required: true description: The ID of the response to delete. schema: type: string example: '500123' responses: '200': description: Response deleted successfully content: application/json: schema: type: object properties: id: type: string description: The ID of the deleted response. object: type: string enum: - response.deleted deleted: type: boolean description: Whether the response was deleted. examples: Deleteresponse200Example: summary: Default deleteResponse 200 response x-microcks-default: true value: id: abc123 object: response.deleted deleted: true '404': description: Not Found - Response does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Deleteresponse404Example: summary: Default deleteResponse 404 response x-microcks-default: true value: error: message: example_value type: example_value param: example_value code: example_value x-microcks-operation: delay: 0 dispatcher: FALLBACK /responses/{response_id}/input_items: get: summary: Chatgpt List Input Items description: | Returns a list of input items for a given response. operationId: listResponseInputItems tags: - Responses parameters: - name: response_id in: path required: true description: The ID of the response to retrieve input items for. schema: type: string example: '500123' - name: limit in: query required: false description: | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. schema: type: integer minimum: 1 maximum: 100 default: 20 example: 10 - name: order in: query required: false description: Sort order by the created_at timestamp. schema: type: string enum: - asc - desc default: asc example: asc - name: after in: query required: false description: | A cursor for use in pagination. An object ID that defines your place in the list. schema: type: string example: example_value - name: before in: query required: false description: | A cursor for use in pagination. An object ID that defines your place in the list. schema: type: string example: example_value responses: '200': description: Successful retrieval of input items content: application/json: schema: $ref: '#/components/schemas/ResponseInputItemList' examples: Listresponseinputitems200Example: summary: Default listResponseInputItems 200 response x-microcks-default: true value: object: list data: - role: user content: example_value type: message id: abc123 call_id: '500123' output: example_value status: completed has_more: true first_id: '500123' last_id: '500123' '404': description: Not Found - Response does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: Listresponseinputitems404Example: summary: Default listResponseInputItems 404 response x-microcks-default: true value: error: message: example_value type: example_value param: example_value code: example_value x-microcks-operation: delay: 0 dispatcher: FALLBACK components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | API key authentication using Bearer token. Pass your OpenAI API key as a Bearer token in the Authorization header. schemas: CreateResponseRequest: type: object required: - model - input properties: model: type: string description: | Model ID used to generate the response, like gpt-4o or o3. OpenAI offers a wide range of models with different capabilities, performance characteristics, and price points. examples: - gpt-4o - gpt-4o-mini - o1 - o3 - o3-mini - gpt-4.1 - gpt-4.1-mini - gpt-4.1-nano input: description: | Text, image, or file inputs to the model, used to generate a response. Can be a string for simple text input, or an array of input items for multi-turn and multimodal inputs. oneOf: - type: string description: A text input to the model. - type: array description: A list of input items to the model. items: $ref: '#/components/schemas/ResponseInputItem' example: example_value instructions: type: string description: | A system (or developer) message inserted at the beginning of the model's context. Use this for top-level guidance on the model's behavior, tone, or constraints. nullable: true example: example_value previous_response_id: type: string description: | The unique ID of the previous response to the model. Use this to create multi-turn conversations. The model will use the previous response as context. nullable: true example: '500123' max_output_tokens: type: integer description: | An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens. nullable: true example: 10 temperature: type: number description: | What sampling temperature to use, between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic. minimum: 0 maximum: 2 default: 1 example: 42.5 top_p: type: number description: | An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. minimum: 0 maximum: 1 default: 1 example: 42.5 tools: type: array description: | An array of tools the model may use to generate a response. Supports built-in tools (web_search_preview, file_search, code_interpreter, computer_use_preview) and custom function tools. items: $ref: '#/components/schemas/ResponseTool' example: [] tool_choice: description: | How the model should select which tool to use. auto allows the model to decide, required forces the model to use a tool, none disables tool use. oneOf: - type: string enum: - auto - required - none - $ref: '#/components/schemas/ResponseToolChoice' example: example_value truncation: type: string description: | The truncation strategy to use for the model context. auto will use the model-defined default truncation strategy. disabled will error if the context exceeds the model's context window. enum: - auto - disabled default: disabled nullable: true example: auto text: type: object description: Configuration for text response format. properties: format: type: object description: | An object specifying the format of the response text. properties: type: type: string description: The format type. enum: - text - json_object - json_schema name: type: string description: | The name of the response format. Required when type is json_schema. description: type: string description: Description of the response format. schema: type: object description: | The JSON schema for the response. Required when type is json_schema. strict: type: boolean description: Whether strict schema adherence is enabled. example: example_value reasoning: type: object description: | Configuration for reasoning models (o-series). Controls how much reasoning effort the model uses. nullable: true properties: effort: type: string description: | Constrains effort on reasoning for reasoning models. enum: - low - medium - high default: medium summary: type: string description: | A summary of the reasoning performed by the model. Can be useful for debugging or understanding model behavior. Supported values are auto, concise, and detailed. enum: - auto - concise - detailed nullable: true example: example_value store: type: boolean description: | Whether to store the generated response for later retrieval via the GET /responses endpoint. Defaults to true. default: true example: true metadata: type: object description: | Set of 16 key-value pairs that can be attached to an object. Useful for storing additional information in a structured format. nullable: true additionalProperties: type: string maxProperties: 16 example: example_value stream: type: boolean description: | If set to true, the model response data will be streamed as server-sent events to the client. default: false example: true parallel_tool_calls: type: boolean description: Whether to allow the model to run tool calls in parallel. default: true example: true user: type: string description: | A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. example: example_value ResponseInputItem: type: object required: - role properties: role: type: string description: The role of the input item. enum: - user - assistant - system - developer example: user content: description: | The content of the input item. Can be a string or an array of content parts for multimodal input. oneOf: - type: string - type: array items: $ref: '#/components/schemas/ResponseInputContentPart' example: example_value type: type: string description: | The type of the input item. Typically message for conversation messages, or specialized types like function_call_output. enum: - message - function_call_output - item_reference example: message id: type: string description: | The unique ID of the input item. Used for item_reference type. example: abc123 call_id: type: string description: | The ID of the function call this output corresponds to. Required for function_call_output type. example: '500123' output: type: string description: | The output of the function call. Required for function_call_output type. example: example_value status: type: string description: The status of the input item. enum: - completed - incomplete example: completed ResponseInputContentPart: type: object required: - type properties: type: type: string description: The type of the content part. enum: - input_text - input_image - input_file example: input_text text: type: string description: The text content. Used when type is input_text. example: example_value image_url: type: string format: uri description: | The URL of the image. Used when type is input_image. example: https://www.example.com detail: type: string description: | The detail level for image inputs. enum: - auto - low - high default: auto example: auto file_id: type: string description: | The ID of the uploaded file. Used when type is input_file. example: '500123' filename: type: string description: The name of the file. example: example_value ResponseTool: type: object required: - type properties: type: type: string description: The type of the tool. enum: - function - web_search_preview - file_search - code_interpreter - computer_use_preview - mcp - image_generation example: function name: type: string description: | The name of the function. Required for function type tools. example: Example Title description: type: string description: A description of what the function does. example: A sample description. parameters: type: object description: | The parameters the function accepts, described as a JSON Schema object. Required for function type tools. example: example_value strict: type: boolean description: | Whether strict schema adherence is enabled for function tools. default: false example: true vector_store_ids: type: array description: | The IDs of the vector stores to search. Required for file_search type tools. items: type: string example: [] max_num_results: type: integer description: | The maximum number of results to return from file search. minimum: 1 maximum: 50 default: 20 example: 10 ranking_options: type: object description: Ranking options for file search results. properties: ranker: type: string description: The ranker to use. enum: - auto - default_2024_11_15 score_threshold: type: number description: | The minimum relevance score for results. minimum: 0 maximum: 1 example: example_value container: type: object description: | The container for the code interpreter tool. Specifies the sandbox environment. properties: type: type: string description: The container type. file_ids: type: array description: IDs of files available in the container. items: type: string example: example_value display_width: type: integer description: | The width of the computer display in pixels. Required for computer_use_preview type. example: 10 display_height: type: integer description: | The height of the computer display in pixels. Required for computer_use_preview type. example: 10 environment: type: string description: | The environment of the computer. Required for computer_use_preview type. enum: - browser - mac - windows - linux example: browser server_label: type: string description: | A label for the MCP server. Required for mcp type tools. example: example_value server_url: type: string format: uri description: | The URL of the MCP server. Required for mcp type tools. example: https://www.example.com allowed_tools: type: array description: | The list of allowed tool names from the MCP server. items: type: string example: [] headers: type: object description: | Headers to pass to the MCP server for authentication. additionalProperties: type: string example: example_value ResponseToolChoice: type: object required: - type properties: type: type: string description: The type of tool to force. enum: - function - file_search - web_search_preview - computer_use_preview - code_interpreter example: function name: type: string description: | The name of the function to call. Required when type is function. example: Example Title ResponseObject: type: object required: - id - object - created_at - model - status - output - usage properties: id: type: string description: Unique identifier for the response. example: abc123 object: type: string description: The object type, always response. enum: - response example: response created_at: type: integer description: | Unix timestamp (in seconds) of when the response was created. example: '2026-01-15T10:30:00Z' model: type: string description: The model used to generate the response. example: example_value status: type: string description: | The status of the response generation. One of completed, failed, in_progress, or incomplete. enum: - completed - failed - in_progress - incomplete example: completed output: type: array description: | An array of content items generated by the model. Can include messages, function calls, web search calls, file search calls, computer actions, and reasoning items. items: $ref: '#/components/schemas/ResponseOutputItem' example: [] usage: $ref: '#/components/schemas/ResponseUsage' error: type: object description: | An error object if the response generation failed. nullable: true properties: code: type: string description: The error code. message: type: string description: A human-readable error message. example: example_value incomplete_details: type: object description: | Details about why the response is incomplete. nullable: true properties: reason: type: string description: The reason the response is incomplete. enum: - max_output_tokens - content_filter example: example_value instructions: type: string description: The instructions provided for the response. nullable: true example: example_value metadata: type: object description: Metadata attached to the response. nullable: true additionalProperties: type: string example: example_value temperature: type: number description: The sampling temperature used. nullable: true example: 42.5 top_p: type: number description: The nucleus sampling value used. nullable: true example: 42.5 max_output_tokens: type: integer description: The maximum output tokens setting. nullable: true example: 10 previous_response_id: type: string description: The ID of the previous response in the conversation. nullable: true example: '500123' reasoning: type: object description: The reasoning configuration used. nullable: true properties: effort: type: string enum: - low - medium - high summary: type: string nullable: true example: example_value text: type: object description: The text format configuration used. nullable: true example: example_value tools: type: array description: The tools available during response generation. items: $ref: '#/components/schemas/ResponseTool' example: [] tool_choice: description: The tool choice setting used. example: example_value truncation: type: string description: The truncation strategy used. nullable: true example: example_value user: type: string description: The end-user identifier. nullable: true example: example_value service_tier: type: string description: The service tier used. nullable: true example: example_value ResponseOutputItem: type: object required: - type properties: type: type: string description: The type of the output item. enum: - message - function_call - web_search_call - file_search_call - computer_call - code_interpreter_call - reasoning - mcp_call - image_generation_call - mcp_list_tools - mcp_approval_request example: message id: type: string description: The unique ID of the output item. example: abc123 role: type: string description: The role of the output item. enum: - assistant example: assistant status: type: string description: The status of the output item. enum: - completed - in_progress - incomplete example: completed content: type: array description: | The content of the output message. Present when type is message. items: $ref: '#/components/schemas/ResponseOutputContentPart' example: [] name: type: string description: | The name of the function being called. Present when type is function_call. example: Example Title call_id: type: string description: | The unique ID of the function call. Present when type is function_call. example: '500123' arguments: type: string description: | The arguments to the function call in JSON format. Present when type is function_call. example: example_value summary: type: array description: | A summary of the reasoning performed by the model. Present when type is reasoning. items: type: object properties: type: type: string enum: - summary_text text: type: string example: [] ResponseOutputContentPart: type: object required: - type properties: type: type: string description: The type of the content part. enum: - output_text - refusal example: output_text text: type: string description: The text content. example: example_value refusal: type: string description: The refusal text. example: example_value annotations: type: array description: | Annotations on the text, such as citations from file search or web search. items: $ref: '#/components/schemas/Annotation' example: [] Annotation: type: object required: - type properties: type: type: string description: The type of annotation. enum: - url_citation - file_citation - file_path example: url_citation start_index: type: integer description: The start index of the annotation in the text. example: 10 end_index: type: integer description: The end index of the annotation in the text. example: 10 url: type: string format: uri description: The URL cited. Present for url_citation type. example: https://www.example.com title: type: string description: The title of the cited resource. example: Example Title file_id: type: string description: | The ID of the cited file. Present for file_citation and file_path types. example: '500123' quote: type: string description: The relevant quote from the file. example: example_value ResponseUsage: type: object required: - input_tokens - output_tokens - total_tokens properties: input_tokens: type: integer description: The number of input tokens used. example: 10 input_tokens_details: type: object description: A detailed breakdown of input token usage. properties: cached_tokens: type: integer description: The number of cached input tokens. example: example_value output_tokens: type: integer description: The number of output tokens generated. example: 10 output_tokens_details: type: object description: A detailed breakdown of output token usage. properties: reasoning_tokens: type: integer description: The number of reasoning tokens generated. example: example_value total_tokens: type: integer description: The total number of tokens used. example: 10 ResponseInputItemList: type: object required: - object - data properties: object: type: string description: The object type. enum: - list example: list data: type: array description: The list of input items. items: $ref: '#/components/schemas/ResponseInputItem' example: [] has_more: type: boolean description: Whether there are more items to retrieve. example: true first_id: type: string description: The ID of the first item in the list. example: '500123' last_id: type: string description: The ID of the last item in the list. example: '500123' ErrorResponse: type: object required: - error properties: error: type: object required: - message - type properties: message: type: string description: A human-readable error message. type: type: string description: The type of error. param: type: string description: The parameter that caused the error. nullable: true code: type: string description: The error code. nullable: true example: example_value