spoken-md New API

openapi: 3.2.0
info:
  title: Podcast Transcripts New 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: New
paths:
  /new:
    get:
      operationId: listNew
      summary: What is new on the shows you follow
      description: 'Every followed show (see /following) with the episodes released in the last 90 days that are newer than the newest episode you have fetched from it, up to the 10 newest per show, each with its transcript URL. Episodes with no transcript are left out. Reads a cache refreshed hourly; a show followed moments ago may list with no episodes until its first poll. Polling this route is free; fetching a transcript_url costs the normal credit. Send `Accept: application/atom+xml` or `?format=atom` for an Atom feed of the same episodes, which any feed reader or automation tool can subscribe to using HTTP Basic auth with the key as the username. Requires a real key, never cached.'
      parameters:
      - name: format
        in: query
        required: false
        description: '`atom` for an Atom feed instead of JSON'
        schema:
          type: string
          enum:
          - atom
      responses:
        '200':
          description: New episodes, grouped by show
          content:
            application/json:
              schema:
                type: object
                required:
                - as_of
                - count
                - shows
                properties:
                  as_of:
                    type: string
                    format: date-time
                  count:
                    type: integer
                    description: Episodes across all shows
                  shows:
                    type: array
                    items:
                      type: object
                      required:
                      - podcast_id
                      - podcast
                      - source
                      - episodes
                      properties:
                        podcast_id:
                          type: string
                        podcast:
                          type: string
                        source:
                          type: string
                          enum:
                          - fetch
                          - explicit
                        episodes:
                          type: array
                          items:
                            $ref: '#/components/schemas/NewEpisode'
              example:
                as_of: '2026-09-24T14:00:00.000Z'
                count: 1
                shows:
                - podcast_id: '1469759170'
                  podcast: All-In with Chamath, Jason, Sacks & Friedberg
                  source: fetch
                  episodes:
                  - id: '1000780992629'
                    title: 'E245: The AI capex debate'
                    date: '2026-09-23T04:00:00Z'
                    transcript_url: https://spoken.md/transcripts/1000780992629
            application/atom+xml:
              schema:
                type: string
                description: 'An Atom 1.0 feed: one entry per episode, the entry link is the transcript URL'
        '401':
          description: Missing or invalid API key
      tags:
      - New
components:
  schemas:
    NewEpisode:
      type: object
      required:
      - id
      - title
      - date
      - transcript_url
      properties:
        id:
          type: string
          description: Episode ID
        title:
          type: string
        date:
          type: string
          format: date-time
          description: Release date
        transcript_url:
          type: string
          description: 'GET it with your key to fetch the transcript: one credit on first fetch, free after that'
  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.