openapi: 3.0.1
info:
  title: Keywords AI Datasets Gateway API
  description: 'Keywords AI is an LLM observability and gateway platform. This specification documents the publicly documented REST surface served from https://api.keywordsai.co/api: the OpenAI-compatible chat completions proxy, the asynchronous request-logging endpoint, prompt and prompt-version management, threads, traces, evaluators, users (customers), datasets, and experiments. All endpoints authenticate with a Bearer API key. (Keywords AI is rebranding to Respan; the keywordsai.co host and API remain active.)'
  termsOfService: https://www.keywordsai.co/terms-of-service
  contact:
    name: Keywords AI Support
    url: https://www.keywordsai.co
    email: team@keywordsai.co
  version: '1.0'
servers:
- url: https://api.keywordsai.co/api
  description: Keywords AI production API base.
security:
- bearerAuth: []
tags:
- name: Gateway
  description: OpenAI-compatible LLM proxy (chat completions).
paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      tags:
      - Gateway
      summary: Create a chat completion
      description: OpenAI-compatible chat completions through the Keywords AI gateway. Routes to 250+ models behind a single endpoint, with optional streaming (Server-Sent Events when `stream` is true), tool calling, structured outputs, fallbacks, load balancing, caching, and automatic logging.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            example:
              model: gpt-4o-mini
              messages:
              - role: user
                content: Reply with exactly ok.
              max_tokens: 16
              temperature: 0
      responses:
        '200':
          description: A chat completion (or, when stream=true, an SSE stream of chunks).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
            text/event-stream:
              schema:
                type: string
                description: data-only Server-Sent Events terminated by a [DONE] sentinel.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                $ref: '#/components/schemas/Message'
              finish_reason:
                type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type: string
    ChatCompletionRequest:
      type: object
      required:
      - model
      - messages
      properties:
        model:
          type: string
          description: Model identifier (any of the 250+ supported models).
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        stream:
          type: boolean
          description: Stream the response token-by-token via Server-Sent Events.
          default: false
        temperature:
          type: number
          minimum: 0
          maximum: 2
        max_tokens:
          type: integer
        top_p:
          type: number
        frequency_penalty:
          type: number
        presence_penalty:
          type: number
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
        response_format:
          type: object
          additionalProperties: true
        customer_identifier:
          type: string
          description: End-user identifier for per-user analytics and logging.
        fallback_models:
          type: array
          items:
            type: string
        metadata:
          type: object
          additionalProperties: true
    Message:
      type: object
      required:
      - role
      - content
      properties:
        role:
          type: string
          enum:
          - system
          - user
          - assistant
          - tool
        content:
          type: string
        name:
          type: string
        tool_calls:
          type: array
          items:
            type: object
            additionalProperties: true
  responses:
    RateLimited:
      description: Too many requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Keywords AI API key supplied as the Authorization Bearer header (Authorization: Bearer <KEYWORDSAI_API_KEY>).'