spoken-md Balance API

openapi: 3.2.0
info:
  title: Podcast Transcripts Balance API
  description: Podcast transcripts as clean markdown. Built for AI agents. Use the demo key `pt_demo` to try it free (demo episode only).
  version: 1.0.0
  contact:
    url: https://spoken.md
servers:
- url: https://spoken.md
security:
- apiKey: []
- bearerApiKey: []
tags:
- name: Balance
paths:
  /balance:
    get:
      operationId: getBalance
      summary: Check credit balance and usage
      description: Returns current credit balance, account email, top-up links, and recent usage history. Use this to check remaining credits before or after fetching transcripts.
      responses:
        '200':
          description: Balance and account info
          content:
            application/json:
              schema:
                type: object
                required:
                - credits
                - top_up
                properties:
                  credits:
                    type: integer
                    description: Credits remaining
                  email:
                    type: string
                  top_up:
                    type: object
                    properties:
                      top_up_url:
                        type: string
                      top_up_packs:
                        type: object
                  usage:
                    type: object
                    description: Recent transcript access history
                    properties:
                      total:
                        type: integer
                      recent:
                        type: array
                        items:
                          type: object
                          properties:
                            episodeId:
                              type: string
                            accessedAt:
                              type: string
                              format: date-time
              example:
                credits: 96
                email: user@example.com
                top_up:
                  top_up_url: https://spoken.md/top-up
                  top_up_packs:
                    '100':
                      url: https://spoken.md/top-up?pack=100
                      price: $10
        '401':
          description: Missing or invalid API key
          headers:
            WWW-Authenticate:
              description: 'Authentication challenge (RFC 9110 15.5.2). Retry with an API key in the x-api-key header, or as an Authorization: Bearer token. The resource_metadata parameter (RFC 9728 5.1) points at the Protected Resource Metadata document.'
              schema:
                type: string
                example: Bearer realm="spoken.md", charset="UTF-8", resource_metadata="https://spoken.md/.well-known/oauth-protected-resource", ApiKey realm="spoken.md", charset="UTF-8"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Balance
components:
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - unauthorized
              - payment_required
              - not_found
              - upstream_error
              - bad_request
            message:
              type: string
            demo_key:
              type: string
            purchase_url:
              type: string
            top_up_url:
              type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key (starts with pt_). Use `pt_demo` for free trial or purchase at https://spoken.md
    bearerApiKey:
      type: http
      scheme: bearer
      description: 'The same pt_ API key sent as an RFC 6750 bearer token, for clients that only support Authorization headers. Equivalent to the x-api-key scheme — not an OAuth token. Registration: https://spoken.md/auth.md'
    basicApiKey:
      type: http
      scheme: basic
      description: The same pt_ API key as the HTTP Basic username with an empty password (or as the password with any username). Exists for feed readers subscribing to /new?format=atom, which cannot set custom headers. Equivalent to the x-api-key scheme.