openapi: 3.0.3
info:
  title: Sinth prepaid API
  version: 2026.09.23
  description: >-
    Prepaid Sinth API. Create a checkout, complete Stripe-hosted payment, then use the sinth_live_ key from
    your purchase email with Authorization: Bearer YOUR_KEY. Successful starter-chat replies cost $0.02. No
    tenant setup is required. Sandbox keys work only in their isolated test environment. Supported
    self-service contract: checkout, starter chat and balance. Broader backend capabilities require separate
    provisioning. Quickstart: https://sinth.ai/start. Agent discovery: https://sinth.ai/llms.txt.
  contact:
    name: Sinth support
    email: support@sinth.ai
servers:
  - url: https://sinth.ai
    description: Production prepaid gateway
security:
  - SinthKey: []
tags:
  - name: Checkout
    description: Buy prepaid credit and receive your key by email
  - name: Chat
    description: General-purpose starter assistant through Locust
  - name: Balance
    description: Your prepaid balance and recent usage
paths:
  /api/stripe/checkout:
    post:
      tags:
        - Checkout
      operationId: createCheckout
      summary: Create a hosted checkout for prepaid credit
      security: []
      description: >-
        Creates a Stripe-hosted checkout URL, not a charge. Open the entire returned URL and complete payment
        there. On the first successful purchase, the key is emailed to the checkout email address. Subsequent
        purchases using that email top up the existing key. No key or customer session is returned by this
        endpoint. Payment brand: Scions Tech. Minimum $10; maximum $5,000. Live endpoint accepts real
        payments, not test cards.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  required:
                    - bundle
                  properties:
                    bundle:
                      type: string
                      enum:
                        - start
                  additionalProperties: false
                - type: object
                  required:
                    - amount_cents
                  properties:
                    amount_cents:
                      type: integer
                      minimum: 1000
                      maximum: 500000
                  additionalProperties: false
            examples:
              starter:
                value:
                  bundle: start
              custom:
                value:
                  amount_cents: 2500
      responses:
        '200':
          description: Open the complete checkout URL, including its fragment.
          content:
            application/json:
              schema:
                type: object
                required:
                  - url
                properties:
                  url:
                    type: string
                    format: uri
        '400':
          description: Invalid bundle or amount
        '500':
          description: Checkout could not be created
        '503':
          description: Checkout temporarily unavailable
  /api/v1/chat:
    post:
      tags:
        - Chat
      operationId: starterChat
      summary: Send a message to the starter assistant
      description: >-
        Omit persona_id to use the configured starter assistant. end_user identifies a conversation within
        your account; other customers cannot share it. Custom-persona inference requires a separate engine and
        is not part of this starter contract. A 2-cent debit is refunded on upstream failure when refunded is
        true. Requests have no idempotency-key contract; retrying a successful request is another billable
        call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - message
              properties:
                message:
                  type: string
                  minLength: 1
                  maxLength: 8000
                  example: What is two plus two?
                end_user:
                  type: string
                  minLength: 1
                  maxLength: 200
                  default: default
                  example: customer-123
      responses:
        '200':
          description: Reply and remaining balance in USD cents
          content:
            application/json:
              schema:
                type: object
                required:
                  - reply
                  - cost_cents
                  - balance_cents
                properties:
                  reply:
                    type: string
                    example: '4'
                  cost_cents:
                    type: integer
                    example: 2
                  balance_cents:
                    type: integer
                    example: 998
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
        '401':
          description: Invalid or inactive Sinth key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
        '402':
          description: Insufficient prepaid balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
        '502':
          description: Upstream request failed; refunded is true when credit was returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  refunded:
                    type: boolean
                  balance_cents:
                    type: integer
        '503':
          description: Chat configuration unavailable or refund pending; inspect error before retrying
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
  /api/v1/usage:
    get:
      tags:
        - Balance
      operationId: getUsage
      summary: Check balance and recent usage
      responses:
        '200':
          description: Balance in USD cents and up to 100 recent usage events
          content:
            application/json:
              schema:
                type: object
                properties:
                  account:
                    type: string
                    format: email
                  balance_cents:
                    type: integer
                    example: 998
                  recent_cost_cents:
                    type: integer
                  recent:
                    type: array
                    items:
                      type: object
                      properties:
                        product:
                          type: string
                        unit_type:
                          type: string
                        quantity:
                          type: integer
                        cost_cents:
                          type: integer
                        created_at:
                          type: string
                          format: date-time
        '401':
          description: Invalid or inactive Sinth key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  detail:
                    type: string
components:
  securitySchemes:
    SinthKey:
      type: http
      scheme: bearer
      description: Your purchased Sinth API key. Never use the shared backend credential in client code.