> ## 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.

# Chat Completions

> Generate chat-based completions using the OpenAI-compatible chat endpoint.

## Server tools

`/v1/chat/completions` 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/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-nano",
    "stream": false,
    "messages": [
      { "role": "user", "content": "What is the current datetime in Europe/London?" }
    ],
    "tools": [
      {
        "type": "gateway:datetime",
        "parameters": { "timezone": "Europe/London" }
      }
    ],
    "tool_choice": "auto"
  }'
```

When a server tool is used, usage includes:

```json theme={null}
{
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 34,
    "total_tokens": 46,
    "server_tool_use": {
      "datetime_requests": 1
    }
  }
}
```

Use `stream: false` when tools are present.


## OpenAPI

````yaml POST /chat/completions
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:
  /chat/completions:
    post:
      tags:
        - Gateway
      summary: Create chat completion
      description: Creates a completion for the chat message.
      operationId: createChatCompletion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionsRequest'
            examples:
              datetimeServerTool:
                summary: Built-in datetime server tool
                value:
                  model: openai/gpt-5-nano
                  stream: false
                  messages:
                    - role: user
                      content: What is the current datetime in Europe/London?
                  tools:
                    - type: gateway:datetime
                      parameters:
                        timezone: Europe/London
                  tool_choice: auto
      responses:
        '200':
          description: Chat completion response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionsResponse'
components:
  schemas:
    ChatCompletionsRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
        messages:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ChatMessage'
        reasoning:
          $ref: '#/components/schemas/ReasoningConfig'
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
        logit_bias:
          type: object
          additionalProperties:
            type: number
        max_completion_tokens:
          type: integer
          minimum: 1
        max_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.
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
        seed:
          type: integer
          minimum: -9223372036854776000
          maximum: 9223372036854776000
        store:
          type: boolean
        stream:
          type: boolean
          default: false
        stream_options:
          type: object
        temperature:
          type: number
          minimum: 0
          maximum: 2
          default: 1
        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'
        max_tool_calls:
          type: integer
          minimum: 1
        parallel_tool_calls:
          type: boolean
          default: true
        tool_choice:
          $ref: '#/components/schemas/TextToolChoice'
        logprobs:
          type: boolean
          default: false
        top_logprobs:
          type: integer
          minimum: 0
          maximum: 20
        top_p:
          type: number
          minimum: 0
          maximum: 1
        stop:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        response_format:
          oneOf:
            - type: string
            - type: object
              properties:
                type:
                  type: string
                schema:
                  type: object
        modalities:
          type: array
          items:
            type: string
            enum:
              - text
              - image
              - audio
        image_config:
          $ref: '#/components/schemas/ImageConfig'
        usage:
          type: boolean
        provider:
          $ref: '#/components/schemas/ProviderRoutingOptions'
        provider_options:
          $ref: '#/components/schemas/ProviderOptions'
        user_id:
          type: string
        user:
          type: string
        service_tier:
          type: string
          enum:
            - auto
            - default
            - flex
            - standard
            - priority
        prompt_cache_key:
          type: string
          nullable: true
        safety_identifier:
          type: string
          nullable: true
        meta:
          type: boolean
          default: false
        echo_upstream_request:
          type: boolean
        debug:
          $ref: '#/components/schemas/DebugOptions'
    ChatCompletionsResponse:
      type: object
      properties:
        id:
          type: string
        nativeResponseId:
          type: string
          nullable: true
        object:
          type: string
        created:
          type: integer
        model:
          type: string
        provider:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatChoice'
        usage:
          $ref: '#/components/schemas/Usage'
    ChatMessage:
      type: object
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - system
            - developer
            - user
            - assistant
            - tool
        content:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/MessageContentPart'
        name:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        images:
          type: array
          items:
            $ref: '#/components/schemas/ChatImageOutputPart'
        audios:
          type: array
          items:
            $ref: '#/components/schemas/ChatAudioOutputPart'
        tool_call_id:
          type: string
      discriminator:
        propertyName: role
    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
    TextGenerateTool:
      oneOf:
        - $ref: '#/components/schemas/FunctionToolDefinition'
        - $ref: '#/components/schemas/GatewayDatetimeToolDefinition'
    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
    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
    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).
    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
    ChatChoice:
      type: object
      properties:
        index:
          type: integer
        message:
          $ref: '#/components/schemas/ChatMessage'
        finish_reason:
          type: string
          enum:
            - stop
            - length
            - tool_calls
            - content_filter
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        server_tool_use:
          $ref: '#/components/schemas/ServerToolUsage'
    MessageContentPart:
      oneOf:
        - $ref: '#/components/schemas/TextContentPart'
        - $ref: '#/components/schemas/ImageContentPart'
        - $ref: '#/components/schemas/AudioContentPart'
        - $ref: '#/components/schemas/VideoContentPart'
        - $ref: '#/components/schemas/ToolCallContentPart'
    ToolCall:
      type: object
      required:
        - id
        - type
        - function
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
            description:
              type: string
            parameters:
              type: object
    ChatImageOutputPart:
      type: object
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          enum:
            - image_url
        image_url:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              description: HTTP(S) URL or data URI.
        mime_type:
          type: string
    ChatAudioOutputPart:
      type: object
      required:
        - type
        - audio_url
      properties:
        type:
          type: string
          enum:
            - audio_url
        audio_url:
          type: object
          required:
            - url
          properties:
            url:
              type: string
              description: HTTP(S) URL or data URI.
        mime_type:
          type: string
        format:
          type: string
          enum:
            - wav
            - mp3
            - flac
            - m4a
            - ogg
            - pcm16
            - pcm24
    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
    ServerToolUsage:
      type: object
      properties:
        datetime_requests:
          type: integer
          minimum: 0
      additionalProperties: false
    TextContentPart:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
    ImageContentPart:
      type: object
      required:
        - type
        - image_url
      properties:
        type:
          type: string
          enum:
            - image_url
        image_url:
          type: object
          properties:
            url:
              type: string
              description: HTTP(S) URL or data URI.
    AudioContentPart:
      type: object
      required:
        - type
        - input_audio
      properties:
        type:
          type: string
          enum:
            - input_audio
        input_audio:
          type: object
          properties:
            data:
              type: string
            format:
              type: string
              enum:
                - wav
                - mp3
                - flac
                - m4a
                - ogg
                - pcm16
                - pcm24
    VideoContentPart:
      type: object
      required:
        - type
        - video_url
      properties:
        type:
          type: string
          enum:
            - input_video
        video_url:
          type: string
          format: uri
    ToolCallContentPart:
      type: object
      required:
        - type
        - id
        - function
      properties:
        type:
          type: string
          enum:
            - tool_call
        id:
          type: string
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````