.txt responses-api API

openapi: 3.1.0
info:
  title: dottxt batches responses-api API
  description: The dottxt API
  version: 1.0.0
servers:
- url: https://api.dottxt.ai/v1
  description: dottxt API
tags:
- name: responses-api
  description: 'Create model responses with enhanced capabilities.


    Open Responses compatible endpoint providing advanced features:


    - **Reasoning models** - Control computational effort with `reasoning` parameter

    - **Stateful conversations** - Maintain context across turns with `previous_response_id`

    - **Flexible input** - Use simple strings or full message arrays

    - **Text output configuration** - Structured outputs via `text` parameter

    - **Context management** - Handle overflow with `truncation` parameter


    [Open Responses API Reference →](https://www.openresponses.org/reference)'
paths:
  /responses:
    post:
      tags:
      - responses-api
      summary: Create response
      description: 'Creates a model response for the given input.


        This endpoint implements the Open Responses compatible API, providing enhanced capabilities including:


        - **Reasoning models** with controllable effort via `reasoning` parameter

        - **Stateful conversations** via `previous_response_id` for maintaining context across turns

        - **Flexible input** - accepts either a string or array of messages

        - **Text output configuration** via `text` parameter for structured outputs

        - **Context window management** via `truncation` parameter


        Set `stream: true` to receive partial responses as server-sent events.


        [Open Responses API Reference →](https://www.openresponses.org/reference)'
      operationId: create_response
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseRequest'
        required: true
      responses:
        '200':
          description: Response generated successfully. When streaming, returns a series of SSE events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
        '400':
          description: Invalid request - check that your input is properly formatted and all required fields are present.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '401':
          description: Invalid or missing API key. Ensure your `Authorization` header is set to `Bearer YOUR_API_KEY`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '402':
          description: Insufficient credits. Top up your account to continue making requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '403':
          description: Your API key does not have access to the requested model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '404':
          description: The specified model does not exist. Use `GET /models` to list available models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '429':
          description: Rate limit exceeded. Back off and retry after a short delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '500':
          description: An unexpected error occurred. Retry the request or contact support if the issue persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
      security:
      - BearerAuth: []
components:
  schemas:
    ResponseObject:
      type: object
      description: Response from creating a response.
      required:
      - id
      - object
      - created_at
      - completed_at
      - model
      - status
      - output
      - usage
      - temperature
      - top_p
      properties:
        completed_at:
          type: integer
          format: int64
          description: The Unix timestamp of when the response was completed.
          example: 1703187205
        created_at:
          type: integer
          format: int64
          description: The Unix timestamp of when the response was created.
          example: 1703187200
        id:
          type: string
          description: A unique identifier for the response.
          example: resp-abc123
        metadata:
          description: Developer-defined tags and values.
        model:
          type: string
          description: The model used for generating the response.
          example: gpt-4o
        object:
          type: string
          description: The object type, always "response".
          example: response
        output:
          type: array
          items:
            $ref: '#/components/schemas/ResponseItem'
          description: The output items generated by the model.
        status:
          type: string
          description: The status of the response. Can be "completed", "incomplete", "cancelled", or "failed".
          example: completed
        temperature:
          type: number
          format: float
          description: The temperature used for sampling (echoed from request).
          example: 0.7
        top_p:
          type: number
          format: float
          description: The nucleus sampling parameter used (echoed from request).
          example: 1
        usage:
          $ref: '#/components/schemas/Usage'
          description: Usage statistics for the response request.
      example:
        completed_at: 1703187205
        created_at: 1703187200
        id: resp-abc123
        model: gpt-4o
        object: response
        output:
        - content: A doubleword is a data unit that is twice the size of a standard word in computer architecture.
          role: assistant
          type: message
        status: completed
        temperature: 0.7
        top_p: 1
        usage:
          completion_tokens: 25
          prompt_tokens: 10
          total_tokens: 35
    OpenAIErrorResponse:
      type: object
      description: OpenAI-compatible error response.
      required:
      - error
      properties:
        error:
          $ref: '#/components/schemas/OpenAIError'
          description: The error details.
      example:
        error:
          code: invalid_api_key
          message: Invalid API key provided
          type: authentication_error
    ResponseRequest:
      type: object
      description: Request body for creating a response.
      required:
      - model
      - input
      properties:
        frequency_penalty:
          type:
          - number
          - 'null'
          format: float
          description: 'Number between -2.0 and 2.0. Positive values penalize new tokens based on

            their existing frequency in the text so far.'
          example: 0
        include:
          type:
          - string
          - 'null'
          description: Include encrypted reasoning content for rehydration on subsequent requests.
        input:
          $ref: '#/components/schemas/ResponseInput'
          description: The input to generate a response for. Can be a string or array of messages.
        instructions:
          type:
          - string
          - 'null'
          description: System instructions for the model.
          example: You are a helpful assistant.
        max_output_tokens:
          type:
          - integer
          - 'null'
          format: int32
          description: The maximum number of tokens to generate in the response.
          example: 256
        metadata:
          description: Developer-defined tags and values for organizing responses.
        modalities:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Output types that you would like the model to generate (e.g., ["text"], ["text", "audio"]).
        model:
          type: string
          description: ID of the model to use.
          example: gpt-4o
        parallel_tool_calls:
          type:
          - boolean
          - 'null'
          description: Whether to enable parallel function calling during tool use.
          example: true
        presence_penalty:
          type:
          - number
          - 'null'
          format: float
          description: 'Number between -2.0 and 2.0. Positive values penalize new tokens based on

            whether they appear in the text so far.'
          example: 0
        previous_response_id:
          type:
          - string
          - 'null'
          description: The ID of a previous response to continue from (for stateful conversations).
        reasoning:
          description: Reasoning configuration for controlling reasoning behavior.
        reasoning_effort:
          type:
          - string
          - 'null'
          description: 'Constrains effort on reasoning. Supported values: "none", "minimal", "low", "medium", "high", "xhigh".'
          example: medium
        stop:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Up to 4 sequences where the API will stop generating further tokens.
        store:
          type:
          - boolean
          - 'null'
          description: Whether to store this response for future reference.
          example: false
        stream:
          type:
          - boolean
          - 'null'
          description: If set, partial message deltas will be sent as server-sent events.
          example: false
        stream_options:
          description: Options for streaming response.
        temperature:
          type:
          - number
          - 'null'
          format: float
          description: What sampling temperature to use, between 0 and 2.
          example: 0.7
        text:
          description: Text output configuration.
        tool_choice:
          description: Controls which (if any) tool is called by the model.
        tools:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/Tool'
          description: A list of tools the model may call.
        top_p:
          type:
          - number
          - 'null'
          format: float
          description: An alternative to sampling with temperature, called nucleus sampling.
          example: 1
        truncation:
          type:
          - string
          - 'null'
          description: How to handle context window overflow ("auto" or "disabled").
        user:
          type:
          - string
          - 'null'
          description: A unique identifier representing your end-user.
      example:
        input: What is a doubleword?
        max_output_tokens: 256
        model: gpt-4o
        temperature: 0.7
    FunctionDefinition:
      type: object
      description: Definition of a function that can be called by the model.
      required:
      - name
      properties:
        description:
          type:
          - string
          - 'null'
          description: A description of what the function does.
          example: Get the current weather in a location
        name:
          type: string
          description: The name of the function.
          example: get_weather
        parameters:
          description: The parameters the function accepts, as a JSON Schema object.
      example:
        description: Get the current weather in a location
        name: get_weather
        parameters:
          properties:
            location:
              description: City name
              type: string
          required:
          - location
          type: object
    ResponseInput:
      oneOf:
      - type: string
        description: A single string input.
      - type: array
        items:
          $ref: '#/components/schemas/ChatMessage'
        description: An array of messages (chat-style conversation).
      description: Input for response requests - can be a single string or array of messages.
      example: What is a doubleword?
    FunctionCall:
      type: object
      description: A function call within a tool call.
      required:
      - name
      - arguments
      properties:
        arguments:
          type: string
          description: The arguments to pass to the function, as a JSON string.
          example: '{"location": "San Francisco"}'
        name:
          type: string
          description: The name of the function to call.
          example: get_weather
      example:
        arguments: '{"location": "San Francisco"}'
        name: get_weather
    ChatMessage:
      type: object
      description: A message in a chat conversation.
      required:
      - role
      properties:
        content:
          type:
          - string
          - 'null'
          description: The content of the message.
          example: What is a doubleword?
        name:
          type:
          - string
          - 'null'
          description: The name of the author (for function/tool messages).
        role:
          type: string
          description: The role of the message author (system, user, assistant, tool, function).
          example: user
        tool_call_id:
          type:
          - string
          - 'null'
          description: The ID of the tool call this message is responding to.
        tool_calls:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ToolCall'
          description: Tool calls made by the assistant.
      example:
        content: What is a doubleword?
        role: user
    ToolCall:
      type: object
      description: A tool call made by the model.
      required:
      - id
      - type
      - function
      properties:
        function:
          $ref: '#/components/schemas/FunctionCall'
          description: The function that was called.
        id:
          type: string
          description: The ID of the tool call.
          example: call_abc123
        type:
          type: string
          description: The type of tool (currently only "function").
          example: function
      example:
        function:
          arguments: '{"location": "San Francisco"}'
          name: get_weather
        id: call_abc123
        type: function
    Tool:
      type: object
      description: A tool that the model may call.
      required:
      - type
      - function
      properties:
        function:
          $ref: '#/components/schemas/FunctionDefinition'
          description: The function definition.
        type:
          type: string
          description: The type of tool (currently only "function").
          example: function
      example:
        function:
          description: Get the current weather in a location
          name: get_weather
          parameters:
            properties:
              location:
                description: City name
                type: string
            required:
            - location
            type: object
        type: function
    ResponseItem:
      type: object
      description: A single item in the response output array.
      required:
      - type
      properties:
        content:
          type:
          - string
          - 'null'
          description: The content of the message (for message-type items).
          example: A doubleword is a data unit that is twice the size of a standard word.
        role:
          type:
          - string
          - 'null'
          description: The role of the message (for message-type items).
          example: assistant
        tool_calls:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/ToolCall'
          description: Tool calls made by the model (for message-type items with tool calls).
        type:
          type: string
          description: The type of item (e.g., "message", "function_call").
          example: message
      example:
        content: A doubleword is a data unit that is twice the size of a standard word in computer architecture.
        role: assistant
        type: message
    Usage:
      type: object
      description: Token usage statistics.
      required:
      - prompt_tokens
      - completion_tokens
      - total_tokens
      properties:
        completion_tokens:
          type: integer
          format: int32
          description: Number of tokens in the generated completion.
          example: 36
        prompt_tokens:
          type: integer
          format: int32
          description: Number of tokens in the prompt.
          example: 24
        total_tokens:
          type: integer
          format: int32
          description: Total number of tokens used in the request.
          example: 60
      example:
        completion_tokens: 36
        prompt_tokens: 24
        total_tokens: 60
    OpenAIError:
      type: object
      description: OpenAI-compatible error details.
      required:
      - message
      - type
      properties:
        code:
          type:
          - string
          - 'null'
          description: The error code.
          example: invalid_api_key
        message:
          type: string
          description: The error message.
          example: Invalid API key provided
        param:
          type:
          - string
          - 'null'
          description: The parameter that caused the error, if applicable.
        type:
          type: string
          description: The type of error.
          example: authentication_error
      example:
        code: invalid_api_key
        message: Invalid API key provided
        type: authentication_error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key authentication. Include your key in the `Authorization` header:


        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        API keys can be created and managed in the dashboard.'