openapi: 3.1.0
info:
  title: dottxt Platform Chat API
  version: v1
  description: OpenAI-compatible structured-output API from dottxt (.txt), the makers of Outlines. The API guarantees 100% schema-compliant model output by construction using constrained decoding. It follows the OpenAI Chat Completions request/response shape, so existing OpenAI SDKs work by changing the base URL and API key. Structured output is requested with the `response_format` parameter (JSON Schema), and results can be streamed as token deltas (SSE) or field-by-field as RFC 6902 JSON Patch events. This specification is a faithful transcription of the public API reference at https://docs.dottxt.ai/api/overview ; it is not published by dottxt.
  contact:
    name: dottxt
    url: https://dottxt.ai/
    email: contact@dottxt.co
  x-provenance:
    generated: '2026-07-18'
    method: generated
    source: https://docs.dottxt.ai/api/overview.md
servers:
- url: https://api.dottxt.ai/v1
  description: dottxt production API
security:
- bearerAuth: []
tags:
- name: Chat
  description: OpenAI-compatible chat completions with structured output.
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      tags:
      - Chat
      summary: Create Chat Completion
      description: Generate a model response from a message array, with support for token streaming, JSON Patch streaming, structured output via `response_format`, and tool calling. OpenAI Chat Completions compatible.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChatCompletionRequest'
      responses:
        '200':
          description: Chat completion (or a stream of chunks when `stream` is set).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletion'
        '400':
          description: Invalid request format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '402':
          description: Insufficient credits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '403':
          description: No access to the requested model.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '404':
          description: Model not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorResponse'
components:
  schemas:
    ChatCompletionChoice:
      type: object
      properties:
        index:
          type: integer
        finish_reason:
          type: string
          example: stop
        message:
          $ref: '#/components/schemas/ChatMessage'
    ResponseFormat:
      type: object
      description: Structured-output constraint. Use `json_schema` for schema-guaranteed output.
      properties:
        type:
          type: string
          enum:
          - text
          - json_object
          - json_schema
        json_schema:
          type: object
          properties:
            name:
              type: string
            schema:
              type: object
              description: A JSON Schema document the output is guaranteed to satisfy.
    OpenAIErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            type:
              type: string
            param:
              type: string
    Usage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    CreateChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: Model ID to use.
          example: openai/gpt-oss-20b
        messages:
          type: array
          description: The conversation so far, as an array of role/content messages.
          items:
            $ref: '#/components/schemas/ChatMessage'
        response_format:
          $ref: '#/components/schemas/ResponseFormat'
        stream:
          description: '`false` (default) returns one JSON response; `true` streams token deltas as SSE; `"patch"` streams RFC 6902 JSON Patch operations per field (NDJSON by default, or SSE with `Accept: text/event-stream`).'
          oneOf:
          - type: boolean
          - type: string
            enum:
            - patch
        temperature:
          type: number
          minimum: 0
          maximum: 2
        max_tokens:
          type: integer
          format: int32
        top_p:
          type: number
        frequency_penalty:
          type: number
          minimum: -2
          maximum: 2
        presence_penalty:
          type: number
          minimum: -2
          maximum: 2
        seed:
          type: integer
          format: int64
        stop:
          type: array
          maxItems: 4
          items:
            type: string
        n:
          type: integer
          format: int32
        tools:
          type: array
          description: Functions the model may call.
          items:
            type: object
        tool_choice:
          description: Controls tool invocation.
        user:
          type: string
          description: End-user identifier.
    ChatMessage:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          type: string
    ChatCompletion:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
          format: int64
        model:
          type: string
        choices:
          type: array
          items:
            $ref: '#/components/schemas/ChatCompletionChoice'
        usage:
          $ref: '#/components/schemas/Usage'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key passed as a bearer token: `Authorization: Bearer $DOTTXT_API_KEY`. Keys use the prefix `sk-dottxt-`.'