> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-stats.phaseo.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses

> Creates a response using the Responses API.

## Server tools

`/v1/responses` supports regular function tools and one gateway-managed server tool:

* `gateway:datetime`

Web-search tool types are temporarily disabled at the gateway request layer.

### Datetime example

```bash theme={null}
curl https://api.phaseo.app/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "stream": false,
    "input": [
      { "role": "user", "content": "Give me the current datetime in Asia/Tokyo." }
    ],
    "tools": [
      {
        "type": "gateway:datetime",
        "parameters": { "timezone": "Asia/Tokyo" }
      }
    ],
    "tool_choice": "auto"
  }'
```

When a server tool is used, usage includes `usage.server_tool_use.datetime_requests`.

Use `stream: false` when tools are present.


## OpenAPI

````yaml POST /responses
openapi: 3.0.3
info:
  title: AI Stats Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: AI Stats
    url: https://docs.ai-stats.phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core AI Stats Gateway operations.
paths:
  /responses:
    post:
      tags:
        - Gateway
      summary: Create response
      description: Creates a response using the Responses API.
      operationId: createResponse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponsesRequest'
            examples:
              datetimeServerTool:
                summary: Built-in datetime server tool
                value:
                  model: openai/gpt-5-nano
                  stream: false
                  input:
                    - role: user
                      content: Give me the current datetime in Asia/Tokyo.
                  tools:
                    - type: gateway:datetime
                      parameters:
                        timezone: Asia/Tokyo
                  tool_choice: auto
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesResponse'
components:
  schemas:
    ResponsesRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
        input:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ResponsesInputItem'
            - type: object
        background:
          type: boolean
        include:
          type: array
          items:
            type: string
        instructions:
          type: string
        max_output_tokens:
          type: integer
          minimum: 1
        metadata:
          type: object
          additionalProperties:
            type: string
        session_id:
          type: string
          maxLength: 256
          description: >-
            Unique identifier for grouping related requests (for example, a
            conversation or agent workflow) for observability.
        parallel_tool_calls:
          type: boolean
        previous_response_id:
          type: string
        reasoning:
          $ref: '#/components/schemas/ReasoningConfig'
        service_tier:
          type: string
          enum:
            - auto
            - default
            - flex
            - standard
            - priority
        store:
          type: boolean
        stream:
          type: boolean
        temperature:
          type: number
          minimum: 0
          maximum: 2
        text:
          type: object
        tool_choice:
          $ref: '#/components/schemas/TextToolChoice'
        tools:
          type: array
          description: >
            Tool definitions for model function calls and gateway server tools.
            The only built-in gateway server tool is `gateway:datetime`.
            Web-search tool types (for example `web_search_preview`) are
            temporarily disabled by the gateway.
          items:
            $ref: '#/components/schemas/TextGenerateTool'
        top_p:
          type: number
          minimum: 0
          maximum: 1
        truncation:
          type: string
          enum:
            - auto
            - disabled
        user:
          type: string
        prompt_cache_key:
          type: string
          nullable: true
        safety_identifier:
          type: string
          nullable: true
        modalities:
          type: array
          items:
            type: string
            enum:
              - text
              - image
              - audio
        image_config:
          $ref: '#/components/schemas/ImageConfig'
        provider_options:
          $ref: '#/components/schemas/ProviderOptions'
        usage:
          type: boolean
        meta:
          type: boolean
        echo_upstream_request:
          type: boolean
        debug:
          $ref: '#/components/schemas/DebugOptions'
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
    ResponsesResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        output:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        output_items:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputItem'
        content:
          type: array
          items:
            type: object
        role:
          type: string
        stop_reason:
          type: string
        type:
          type: string
        usage:
          $ref: '#/components/schemas/Usage'
    ResponsesInputItem:
      type: object
      description: Responses API input item.
      properties:
        type:
          type: string
        role:
          type: string
          enum:
            - user
            - assistant
            - system
            - developer
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
            - type: object
    ReasoningConfig:
      type: object
      properties:
        effort:
          type: string
          enum:
            - none
            - minimal
            - low
            - medium
            - high
            - xhigh
          default: medium
        summary:
          type: string
          enum:
            - auto
            - concise
            - detailed
          default: auto
        enabled:
          type: boolean
        max_tokens:
          type: integer
          minimum: 0
    TextToolChoice:
      description: >
        Tool selection strategy. `gateway:datetime` is accepted and rewritten by
        the gateway into an upstream function/tool target.
      oneOf:
        - type: string
          enum:
            - auto
            - none
            - required
            - gateway:datetime
        - type: object
    TextGenerateTool:
      oneOf:
        - $ref: '#/components/schemas/FunctionToolDefinition'
        - $ref: '#/components/schemas/GatewayDatetimeToolDefinition'
    ImageConfig:
      type: object
      properties:
        aspect_ratio:
          type: string
        image_size:
          type: string
          enum:
            - 0.5K
            - 1K
            - 2K
            - 4K
        include_rai_reason:
          type: boolean
        font_inputs:
          type: array
          items:
            type: object
            properties:
              font_url:
                type: string
                format: uri
              text:
                type: string
        super_resolution_references:
          type: array
          items:
            type: string
        reference_images:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    ProviderOptions:
      type: object
      description: Optional provider-specific options.
      properties:
        openai:
          type: object
          properties:
            context_management:
              type: object
              description: Optional OpenAI context management configuration.
              properties:
                type:
                  type: string
                  enum:
                    - compaction
                compact_threshold:
                  type: number
              required:
                - type
            prompt_cache_retention:
              type: string
        anthropic:
          type: object
          properties:
            cache_control:
              $ref: '#/components/schemas/CacheControl'
        google:
          type: object
          properties:
            cache_control:
              $ref: '#/components/schemas/CacheControl'
            cached_content:
              type: string
            cache_ttl:
              type: string
    DebugOptions:
      type: object
      description: Gateway debug controls. These flags are never forwarded upstream.
      properties:
        enabled:
          type: boolean
        return_upstream_request:
          type: boolean
        return_upstream_response:
          type: boolean
        trace:
          type: boolean
        trace_level:
          type: string
          enum:
            - summary
            - full
    ProviderRoutingOptions:
      type: object
      description: Provider routing preferences for gateway selection.
      properties:
        order:
          type: array
          items:
            type: string
        only:
          type: array
          items:
            type: string
        ignore:
          type: array
          items:
            type: string
        include_alpha:
          type: boolean
          description: Include alpha providers in routing (off by default).
    ResponsesOutputItem:
      type: object
      description: Responses API output item.
      properties:
        type:
          type: string
        role:
          type: string
        content:
          type: array
          items:
            $ref: '#/components/schemas/ResponsesOutputContentPart'
        call_id:
          type: string
        name:
          type: string
        arguments:
          type: string
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        server_tool_use:
          $ref: '#/components/schemas/ServerToolUsage'
    FunctionToolDefinition:
      type: object
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum:
            - function
        function:
          type: object
          required:
            - name
            - parameters
          properties:
            name:
              type: string
            description:
              type: string
            parameters:
              type: object
      additionalProperties: true
    GatewayDatetimeToolDefinition:
      type: object
      description: >
        Gateway-managed server tool. The gateway executes the datetime lookup
        and injects the result back into the model tool loop.
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - gateway:datetime
        parameters:
          type: object
          properties:
            timezone:
              type: string
              description: IANA timezone name (for example Europe/London).
          additionalProperties: false
        timezone:
          type: string
          description: Legacy shortcut for default timezone (IANA).
      additionalProperties: false
    CacheControl:
      type: object
      properties:
        type:
          type: string
        ttl:
          type: string
        scope:
          type: string
      additionalProperties: true
    ResponsesOutputContentPart:
      oneOf:
        - $ref: '#/components/schemas/ResponsesOutputTextPart'
        - $ref: '#/components/schemas/ResponsesOutputImagePart'
        - $ref: '#/components/schemas/ResponsesOutputAudioPart'
    ServerToolUsage:
      type: object
      properties:
        datetime_requests:
          type: integer
          minimum: 0
      additionalProperties: false
    ResponsesOutputTextPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - output_text
        text:
          type: string
        annotations:
          type: array
          items:
            type: object
    ResponsesOutputImagePart:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - output_image
        b64_json:
          type: string
        image_url:
          type: object
          properties:
            url:
              type: string
        mime_type:
          type: string
      anyOf:
        - required:
            - b64_json
        - required:
            - image_url
    ResponsesOutputAudioPart:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - output_audio
        b64_json:
          type: string
        audio_url:
          type: object
          properties:
            url:
              type: string
        mime_type:
          type: string
        format:
          type: string
          enum:
            - wav
            - mp3
            - flac
            - m4a
            - ogg
            - pcm16
            - pcm24
      anyOf:
        - required:
            - b64_json
        - required:
            - audio_url
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````