openapi: 3.1.0
info:
  title: SeenPDF AI API
  version: 1.2.0
  description: API for AI agents to interact with SeenPDF's document conversion service, featuring x402 autonomous payments via Solana, Base, Polygon, and Arbitrum.
  contact:
    name: Support
    url: https://seenpdf.com
servers:
  - url: https://api.seenpdf.com
    description: Production API
  - url: https://seenpdf.com
    description: Frontend (proxied in development)
x-pricing:
  model: pay-per-use
  price: 1.00
  currency_equivalent: USD
  supported_assets: [USDC, USDT]
  networks:
    - solana
    - base
    - polygon
    - arbitrum
  protocol: x402
paths:
  /api/documents/upload:
    post:
      summary: Upload and convert a document to PDF.
      description: |
        Uploads a DOC/DOCX/PDF file. For AI agents without a paid subscription, this endpoint requires an x402 payment proof.
        
        If no valid `Authorization` is provided, the server responds with a `402 Payment Required` and details for the USDC/USDT transfer on multiple networks (Solana, Base, Polygon, Arbitrum).
        The AI agent must send 1.00 USD equivalent to the provided address and resubmit the request with the `Authorization: x402 <TX_ID>` header.
      operationId: uploadDocument
      security:
        - x402Auth: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The document file to upload (DOC, DOCX, or PDF).
      responses:
        '200':
          description: Document successfully converted and uploaded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  id:
                    type: string
                    description: Unique Document ID.
                  url:
                    type: string
                    description: URL to access the PDF.
        '402':
          description: Payment Required. The AI agent must fulfill the x402 challenge.
          headers:
            WWW-Authenticate:
              schema:
                type: string
                example: x402 amount="1.00", currency="USD_EQUIV", networks="solana, base, polygon, arbitrum"
              description: x402 challenge header with payment details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  options:
                    type: object
                    description: Payment options per network and asset.
        '400':
          description: Bad Request.
        '403':
          description: Forbidden.
        '500':
          description: Internal Server Error.

components:
  securitySchemes:
    x402Auth:
      type: http
      scheme: x402
      description: x402 payment protocol using Transaction ID as proof. Format `Authorization: x402 <TX_ID>`.
    BearerAuth:
      type: http
      scheme: bearer
      description: Standard Bearer token for authenticated users.