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

# Chat completion

> This endpoint proxies an OpenAI-compatible chat completion request and charges the user based on the configured monetization model (per request, per token, etc).

If the user is not connected to the paywall, the response will contain a connection link.

If the user is connected but has insufficient balance, a top-up link is returned.

On success, the request is forwarded to the underlying model provider and the result is returned.




## OpenAPI

````yaml POST /chat/completions
openapi: 3.1.0
info:
  title: Paywalls.ai API
  description: >
    The Paywalls.ai API enables developers to integrate monetization and access
    control for OpenAI-compatible LLMs.


    This proxy service supports multiple pricing strategies—including
    per-request, token-based, and subscription models—while maintaining full
    compatibility with the OpenAI API format.


    Requests are automatically checked for user authorization and balance. If
    the user is not connected to the paywall, or lacks sufficient balance, the
    API will return actionable links for onboarding or top-up.


    Use this API to monetize your AI-powered apps and services with minimal
    effort.


    Visit [paywalls.ai](https://docs.paywalls.ai) for full documentation and
    setup guides.
  version: 1.0.0
servers:
  - url: https://api.paywalls.ai/v1
    description: Primary production server
security:
  - ApiKeyAuth: []
tags:
  - name: Chat
    description: >
      OpenAI-compatible chat completion endpoint that enforces paywall logic
      before proxying the request to a model provider.


      Automatically checks user connection, balance, and performs charging.
      Supports streaming and non-streaming completions.
  - name: Models
    description: >
      Retrieve metadata and pricing information about the LLM models supported
      by the proxy.


      Includes prompt and completion pricing, per-request costs, and display
      details for UI integration.
  - name: User
    description: >
      Endpoints for managing user sessions, balance, and charging status.


      Includes functionality for connecting to or disconnecting from the
      paywall, checking balance, initiating top-ups, and issuing manual charges.
  - name: Webhooks
    description: >
      Manage webhook subscriptions and inspect delivery activity for your
      paywall integrations.
paths:
  /chat/completions:
    post:
      tags:
        - Chat
      summary: Proxy a chat completion request with automatic paywall enforcement
      description: >
        This endpoint proxies an OpenAI-compatible chat completion request and
        charges the user based on the configured monetization model (per
        request, per token, etc).


        If the user is not connected to the paywall, the response will contain a
        connection link.


        If the user is connected but has insufficient balance, a top-up link is
        returned.


        On success, the request is forwarded to the underlying model provider
        and the result is returned.
      parameters:
        - $ref: '#/components/parameters/XPaywallUser'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  description: The model to use for generating the response.
                messages:
                  type: array
                  description: A list of messages that make up the conversation.
                  items:
                    $ref: '#/components/schemas/Message'
                  minItems: 1
                user:
                  type: string
                  description: The unique identifier of the user making the request.
                stream:
                  type: boolean
                  description: Whether to stream the response back to the client.
                  default: false
              required:
                - model
                - messages
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: chatcmpl-123
                    description: The completion identifier.
                  object:
                    type: string
                    example: chat.completion
                    description: The type of the returned object.
                  created:
                    type: integer
                    example: 1677652288
                    description: The creation timestamp of the completion.
                  choices:
                    type: array
                    description: The list of choices returned by the model.
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                          example: 0
                          description: The index of the choice in the list.
                        message:
                          $ref: '#/components/schemas/Message'
                        finish_reason:
                          type: string
                          example: stop
                          description: >-
                            The reason why the model stopped generating further
                            tokens.
components:
  parameters:
    XPaywallUser:
      name: X-Paywall-User
      in: header
      required: false
      schema:
        type: string
      description: >
        Optional user identifier provided by the developer.

        Can be used instead of the `user` property in the request body to
        associate the API call with a specific end user.
  schemas:
    Message:
      type: object
      description: A single message exchanged in a chat conversation.
      properties:
        role:
          $ref: '#/components/schemas/MessageRole'
        content:
          type: string
          description: The text content of the message.
        name:
          type: string
          pattern: ^[a-zA-Z0-9_]{1,64}$
          description: >
            Optional name of the message author (e.g. function or tool name).

            Can contain letters, numbers, and underscores; max length is 64
            characters.
    MessageRole:
      type: string
      description: The role of the message author in the conversation.
      enum:
        - system
        - user
        - assistant
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer

````