spoken-md Transcripts API

openapi: 3.2.0
info:
  title: Podcast Transcripts 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: Transcripts
paths:
  /transcripts/{episodeId}:
    get:
      operationId: getTranscript
      summary: Get podcast episode transcript
      description: Returns a clean markdown transcript with speaker names and timestamps for any podcast episode. Use the demo key `pt_demo` to try the demo episode for free. All other episodes require a paid API key and cost 1 credit on first fetch — repeat fetches of the same episode are free.
      parameters:
      - name: episodeId
        in: path
        required: true
        description: Podcast episode ID (numeric)
        schema:
          type: string
          pattern: ^\d+$
          example: '1000651996090'
      responses:
        '200':
          description: Transcript as markdown with speaker names and timestamps
          headers:
            X-Credits-Remaining:
              description: Number of credits remaining on this API key
              schema:
                type: integer
            X-Credits-Charged:
              description: Credits charged for this request (0 for demo episode or repeat fetch, 1 for first fetch)
              schema:
                type: integer
                enum:
                - 0
                - 1
            X-Top-Up-Url:
              description: Direct top-up URL, present when credits are low (10 or fewer)
              schema:
                type: string
                format: uri
          content:
            text/markdown:
              schema:
                type: string
              example: '**John Smith** (0:00)

                Welcome to the show. Today we''re talking about...


                **Jane Doe** (0:15)

                Thanks for having me.

                '
        '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'
              example:
                error:
                  code: unauthorized
                  message: API key required. Pass it via the X-Api-Key header. Try the demo key to get started.
                  demo_key: pt_demo
                  purchase_url: https://spoken.md/
        '402':
          description: No credits remaining. POST to the top_up_url, with the key in the header as usual, to purchase more.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: payment_required
                  message: No credits remaining. Your API key and cached transcripts are preserved — top up to resume.
                  top_up_url: https://spoken.md/top-up
        '404':
          description: Episode not found or has no transcript
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Upstream error. No credit charged. Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Transcripts
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.