openapi: 3.1.0
info:
  title: Poe API
  version: '1.0'
  summary: OpenAI-compatible API for accessing AI models and bots on Poe.
  description: >-
    The Poe API is a developer platform by Quora that provides access to hundreds
    of AI models and bots through a single OpenAI-compatible interface. Developers
    can call Chat Completions and Responses endpoints, list available models, and
    monitor point usage and balance using a single API key issued at
    https://poe.com/api/keys. The API supports text, image, video, and audio
    generation modalities and is rate-limited to 500 requests per minute.
  contact:
    name: Poe Creator Platform
    url: https://creator.poe.com/
  license:
    name: Poe Terms of Service
    url: https://poe.com/tos
servers:
  - url: https://api.poe.com/v1
    description: Poe API (OpenAI-compatible Chat Completions and Responses endpoints)
  - url: https://api.poe.com
    description: Poe API root (Usage and Balance endpoints)
tags:
  - name: Chat
    description: OpenAI-compatible chat completion endpoints.
  - name: Responses
    description: Advanced Responses API supporting reasoning, web search, and structured outputs.
  - name: Models
    description: Discover available bots and models.
  - name: Usage
    description: Track point balance and usage history.
security:
  - BearerAuth: []
paths:
  /chat/completions:
    post:
      tags:
        - Chat
      summary: Create a chat completion
      description: >-
        Create an OpenAI-compatible chat completion using any supported Poe bot
        (for example Claude-Sonnet-4.6, GPT-5.4, or Gemini-3.1-Pro). Streaming is
        supported via `stream: true`.
      operationId: createChatCompletion
      servers:
        - url: https://api.poe.com/v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: A chat completion object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /responses:
    post:
      tags:
        - Responses
      summary: Create a response
      description: >-
        Create a response using the Responses API, which supports advanced features
        such as reasoning, web search, structured outputs, and multi-turn conversations.
      operationId: createResponse
      servers:
        - url: https://api.poe.com/v1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseRequest'
      responses:
        '200':
          description: A response object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /models:
    get:
      tags:
        - Models
      summary: List models
      description: List the AI models and bots available through the Poe API.
      operationId: listModels
      servers:
        - url: https://api.poe.com/v1
      responses:
        '200':
          description: A list of available models.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /usage/current_balance:
    get:
      tags:
        - Usage
      summary: Get current point balance
      description: Returns the caller's current available Poe point balance.
      operationId: getCurrentBalance
      servers:
        - url: https://api.poe.com
      responses:
        '200':
          description: Current point balance.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentBalance'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /usage/points_history:
    get:
      tags:
        - Usage
      summary: Get points usage history
      description: >-
        Retrieve a paginated history of point usage entries. Entries up to 30 days
        old are available.
      operationId: getPointsHistory
      servers:
        - url: https://api.poe.com
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
          description: Maximum number of entries to return.
        - in: query
          name: starting_after
          schema:
            type: string
          description: Cursor (`query_id`) to paginate after.
      responses:
        '200':
          description: A page of usage history entries.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PointsHistory'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        Bearer token issued from https://poe.com/api/keys. Pass as
        `Authorization: Bearer <api_key>`.
  responses:
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded (500 requests per minute).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: Bot or model identifier (for example `Claude-Sonnet-4.6`).
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessage'
        stream:
          type: boolean
          default: false
        temperature:
          type: number
          format: float
        top_p:
          type: number
          format: float
        max_tokens:
          type: integer
        tools:
          type: array
          items:
            type: object
        tool_choice:
          oneOf:
            - type: string
            - type: object
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
            - tool
        content:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
        name:
          type: string
        tool_call_id:
          type: string
    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/ChatMessage'
              finish_reason:
                type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
    ResponseRequest:
      type: object
      required:
        - model
        - input
      properties:
        model:
          type: string
        input:
          oneOf:
            - type: string
            - type: array
              items:
                type: object
        instructions:
          type: string
        tools:
          type: array
          items:
            type: object
        response_format:
          type: object
        stream:
          type: boolean
          default: false
    ResponseObject:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: response
        created_at:
          type: integer
        model:
          type: string
        output:
          type: array
          items:
            type: object
        usage:
          type: object
    ModelList:
      type: object
      properties:
        object:
          type: string
          example: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
    Model:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: model
        created:
          type: integer
        owned_by:
          type: string
    CurrentBalance:
      type: object
      properties:
        current_point_balance:
          type: integer
          description: Available Poe points.
    PointsHistory:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PointsHistoryEntry'
        has_more:
          type: boolean
        next_cursor:
          type: string
          nullable: true
    PointsHistoryEntry:
      type: object
      properties:
        query_id:
          type: string
        bot:
          type: string
        created_at:
          type: integer
        cost_usd:
          type: number
          format: float
        cost_points:
          type: integer
        cost_breakdown:
          type: object
        usage_type:
          type: string
        chat_name:
          type: string
        api_key_name:
          type: string
        canvas_app_name:
          type: string
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
            code:
              type: string