spoken-md Search API

openapi: 3.2.0
info:
  title: Podcast Transcripts Search 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: Search
paths:
  /search:
    get:
      operationId: searchEpisodes
      summary: Search podcast episodes
      description: Search by text query or paste a URL (Spotify, YouTube, etc.) to find matching podcast episodes. Returns episode IDs for use with /transcripts/{id}. Requires API key but does not charge credits.
      parameters:
      - name: q
        in: query
        required: true
        description: Search query (text) or a podcast episode URL from any platform
        schema:
          type: string
          example: huberman sleep
      responses:
        '200':
          description: Matching episodes
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchResult'
              example:
                results:
                - id: '1000651996090'
                  title: 'Dr. Matt Walker: Protocols to Improve Your Sleep'
                  podcast: Huberman Lab
                  podcastId: '1545953110'
                  date: '2024-04-10T00:00:00Z'
        '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:
      - Search
components:
  schemas:
    SearchResult:
      type: object
      required:
      - id
      - title
      - podcast
      - podcastId
      - date
      properties:
        id:
          type: string
          description: Episode ID for use with /transcripts/{id}
        title:
          type: string
        podcast:
          type: string
        podcastId:
          type: string
          description: Show ID for use with /podcasts/{podcastId}/episodes
        date:
          type: string
          format: date-time
    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.