spoken-md Following API

openapi: 3.2.0
info:
  title: Podcast Transcripts Following 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: Following
paths:
  /following:
    get:
      operationId: listFollowing
      summary: List the shows you follow
      description: 'The shows this account is kept current on. Every charged fetch makes its show a follow; the five most-fetched shows from the last 180 days are followed automatically (`source: fetch`), and up to 25 more can be declared with PUT /following/{podcastId} (`source: explicit`). Muted shows are listed separately. Requires a real key, charges nothing, never cached.'
      responses:
        '200':
          description: Followed and muted shows
          content:
            application/json:
              schema:
                type: object
                required:
                - following
                - muted
                - limits
                properties:
                  following:
                    type: array
                    items:
                      $ref: '#/components/schemas/Follow'
                  muted:
                    type: array
                    items:
                      type: object
                      properties:
                        podcast_id:
                          type: string
                        podcast:
                          type: string
                  limits:
                    type: object
                    properties:
                      explicit:
                        type: integer
                        description: Maximum declared follows
                      inferred:
                        type: integer
                        description: Maximum automatic follows
                      inferred_window_days:
                        type: integer
                        description: How long a fetch keeps an automatic follow alive
              example:
                following:
                - podcast_id: '1469759170'
                  podcast: All-In with Chamath, Jason, Sacks & Friedberg
                  source: fetch
                  fetch_count: 42
                  last_fetched_at: '2026-09-20T14:02:11.000Z'
                  newest_fetched_id: '1000780992629'
                muted:
                - podcast_id: '1200361736'
                  podcast: The Daily
                limits:
                  explicit: 25
                  inferred: 5
                  inferred_window_days: 180
        '401':
          description: Missing or invalid API key (the `pt_demo` key has nothing to follow with)
      tags:
      - Following
  /following/{podcastId}:
    parameters:
    - name: podcastId
      in: path
      required: true
      description: Show ID (a `podcastId` from /search)
      schema:
        type: string
    put:
      operationId: followPodcast
      summary: Follow a show
      description: Declare a follow, or clear a mute. A declared follow stays active until you DELETE it, regardless of fetch activity, and does not use one of the five automatic slots. For a show you have never fetched, what counts as new starts from its newest episode at the time you follow it. Charges nothing.
      responses:
        '200':
          description: Now following
          content:
            application/json:
              schema:
                type: object
                properties:
                  podcast_id:
                    type: string
                  podcast:
                    type: string
                  state:
                    type: string
                    enum:
                    - following
                  source:
                    type: string
                    enum:
                    - explicit
              example:
                podcast_id: '1469759170'
                podcast: All-In with Chamath, Jason, Sacks & Friedberg
                state: following
                source: explicit
        '401':
          description: Missing or invalid API key
        '404':
          description: No podcast with that ID
        '409':
          description: Declared-follow limit reached; unfollow one first. Body carries `limit`.
        '502':
          description: Upstream error resolving the show; safe to retry
      tags:
      - Following
    delete:
      operationId: unfollowPodcast
      summary: Stop following a show
      description: 'Mutes the show: it leaves your follows and is not re-added by later fetches. PUT /following/{podcastId} reverses it. Charges nothing.'
      responses:
        '200':
          description: 'Muted: the show no longer appears in your follows and is not re-added by later fetches'
          content:
            application/json:
              schema:
                type: object
                properties:
                  podcast_id:
                    type: string
                  podcast:
                    type: string
                  state:
                    type: string
                    enum:
                    - muted
              example:
                podcast_id: '1200361736'
                podcast: The Daily
                state: muted
        '401':
          description: Missing or invalid API key
        '404':
          description: You are not following that show (error code `not_following`)
      tags:
      - Following
components:
  schemas:
    Follow:
      type: object
      required:
      - podcast_id
      - podcast
      - source
      - fetch_count
      properties:
        podcast_id:
          type: string
          description: Show ID, for /podcasts/{podcastId}/episodes and /following/{podcastId}
        podcast:
          type: string
        source:
          type: string
          enum:
          - fetch
          - explicit
          description: '`fetch`: inferred from your fetch history. `explicit`: declared with PUT /following/{podcastId}.'
        fetch_count:
          type: integer
          description: Charged fetches from this show, across every key on the account
        last_fetched_at:
          type: string
          format: date-time
          description: Absent on a declared follow of a show never fetched
        newest_fetched_id:
          type: string
          description: 'Highest episode ID fetched — the floor for what counts as new to you. Not the most recently fetched episode: a backfill of old episodes does not move it.'
  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.