Skip to content

Podcasts

List podcast recommendations

GET /api/podcasts.json

Markdown · Authoritative OpenAPI

Request policy

Operation
getPodcasts
Access
anonymous
Automatic retries
None
Redirects
Returned to the caller without following
Request body limit
No request body
Pagination
One page per call. Explicit iteration defaults to at most 10 pages, 1,000 items, and 32 MiB; reaching a bound reports incomplete execution.

Parameters

limit number

Requested page size (default 50). Numeric values are floored and clamped to 1–100.

cursor string

Opaque cursor copied from a returned pagination link. Arbitrary strings are rejected with 400; windowed feed cursors must retain their original filters.

sort string

Sort field and direction (e.g., "year:desc", "addedAt:asc")

facets string

Include facet metadata in response meta (set to 1)

show string

Filter by podcast show name

q string

Case-insensitive search across podcast text fields

Request headers

  • API-Version (optional) — Header-based API version selection. Omit it, send an empty value, or send 1.0.0; surrounding whitespace is ignored.
  • Idempotency-Key (optional) — Accepted for clients that attach a key uniformly. GET, HEAD, and OPTIONS are already safe and intrinsically idempotent, so read responses are not stored in an idempotency replay cache.

Responses

200

List response for podcasts

Response headers
{
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  },
  "ETag": {
    "description": "Entity tag for conditional requests",
    "schema": {
      "type": "string"
    }
  },
  "Cache-Control": {
    "description": "Caching directives",
    "schema": {
      "type": "string"
    }
  },
  "X-Total-Count": {
    "description": "Total number of items",
    "schema": {
      "type": "integer"
    }
  },
  "Link": {
    "description": "RFC 8288 Web Linking header with pagination links",
    "schema": {
      "type": "string"
    }
  },
  "Link-Template": {
    "description": "RFC 9652 Link-Template header with query parameter templates",
    "schema": {
      "type": "string"
    }
  },
  "Deprecation": {
    "description": "RFC 9745 lifecycle deprecation signal",
    "schema": {
      "type": "string"
    }
  },
  "Sunset": {
    "description": "RFC 8594 lifecycle sunset date (HTTP IMF-fixdate)",
    "schema": {
      "type": "string",
      "pattern": "^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-9]{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) [0-9]{4} [0-9]{2}:[0-9]{2}:[0-9]{2} GMT$",
      "examples": [
        "Sun, 06 Sep 2026 17:40:13 GMT"
      ]
    }
  }
}

application/json

object

Schema details

data Podcast[] required

Schema details

Podcast

Schema details

topics string[] required

Schema details

string

Allowed: "architecture" | "art" | "artificial intelligence" | "basketball" | "business" | "cities" | "creativity" | "culture" | "design" | "food" | "health" | "history" | "internet" | "leadership" | "music" | "nature" | "politics" | "product development" | "science" | "sports" | "technology" | "urbanism" | "work"

themes string[] required

Schema details

string

Allowed: "ambition" | "belonging" | "change" | "community" | "connection" | "craft" | "discovery" | "freedom" | "friendship" | "identity" | "loss" | "memory" | "power" | "resilience" | "transformation"

moods string[] required

Schema details

string

Allowed: "atmospheric" | "calm" | "contemplative" | "energizing" | "hopeful" | "intimate" | "joyful" | "melancholic" | "playful" | "tense" | "warm"

tones string[] required

Schema details

string

Allowed: "analytical" | "earnest" | "humorous" | "irreverent" | "observational" | "optimistic" | "provocative" | "reflective" | "suspenseful"

styles string[] required

Schema details

string

Allowed: "cinematic" | "conversational" | "documentary" | "experimental" | "immersive" | "minimalist" | "narrative" | "practical" | "technical" | "visual"

pace string required

Allowed: "slow" | "measured" | "moderate" | "brisk" | "fast" | "varied"

id string required

canonicalId string required

itemPath string required

title string required

showName string required

description string required

appleUrl string required (uri)

spotifyUrl string required (uri)

releaseDate string required (date-time)

addedAt string required (date-time)

notes string required

guests object[] required

Schema details

object

Schema details

name string required

role string

canonicalPersonId string

feed object required

Schema details

url string required (uri)

guid string

guidSource string

Allowed: "publisher" | "derived"

medium string

updateFrequency object

Schema details

description string required

complete boolean

startsAt string

Schema details

string (date)

string (date-time)

recurrenceRule string

usesPodping boolean

episodeGuid string required

episodeUrl string required (uri)

credits object[] required

Schema details

object

Schema details

name string required

role string

group string

canonicalPersonId string

sourceUrl string (uri)

imageUrl string (uri)

transcripts object[] required

Schema details

object

Schema details

url string required (uri)

type string required

language string

rel unknown

chapters object required

Schema details

url string required (uri)

type unknown required

images object[] required

Schema details

object

Schema details

url string required (uri)

alt string

aspectRatio string

width number

height number

type string

purposes string[]

Schema details

string

license object required

Schema details

identifier string required

url string (uri)

funding object[] required

Schema details

object

Schema details

url string required (uri)

label string required

soundbites object[] required

Schema details

object

Schema details

startTime number required

duration number required

title string

season object required

Schema details

number number required

name string

episode object required

Schema details

number number required

display string

meta PaginationMeta required

Schema details

totalCount number required

pageSize number required

timestamp string required (date-time)

rowsRead number

Rows materialized by the bounded D1 list window, when available.

boundedD1Window boolean

The list was served through a bounded D1 window.

facets object

correction object

Schema details

original string required

resolved string required

applied boolean required

kind string required

Allowed: "alias" | "fuzzy"

links PaginationLinks required

Schema details

self string required (uri)

first string required (uri)

next string (uri)

prev string (uri)

last string required (uri)

text/csv

string

304

Not Modified

400

Bad Request

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

406

Not Acceptable

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

429

Public REST request limit exceeded

Response headers
{
  "Retry-After": {
    "description": "Seconds before the request should be retried",
    "schema": {
      "type": "integer",
      "enum": [
        60
      ]
    }
  },
  "RateLimit": {
    "description": "Current quota state for the exhausted public-rest policy",
    "schema": {
      "type": "string"
    }
  },
  "Content-Usage": {
    "description": "IETF AIPREF usage preferences for this public content",
    "schema": {
      "type": "string",
      "examples": [
        "train-ai=y, search=y"
      ]
    }
  },
  "Content-Signal": {
    "description": "Compatibility AI usage preferences for deployed crawlers",
    "schema": {
      "type": "string",
      "examples": [
        "ai-train=yes, search=yes, ai-input=yes"
      ]
    }
  },
  "API-Version": {
    "description": "Selected public REST contract version",
    "schema": {
      "type": "string",
      "enum": [
        "1.0.0"
      ]
    }
  },
  "RateLimit-Policy": {
    "description": "Public REST quota policy: 1000 Worker requests per 60 seconds for each source and Cloudflare location",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Compatibility form of the current public REST request limit",
    "schema": {
      "type": "integer",
      "enum": [
        1000
      ]
    }
  }
}

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

503

Portable location provenance is incomplete, so the export is unavailable

application/problem+json

ProblemDetails

Schema details

type string required (uri)

Problem type URI (see /problems/)

title string required

Short human-readable summary

status number required

HTTP status code

detail string required

Human-readable explanation

instance string (uri)

URI reference for this occurrence

Examples

Examples use synthetic fixture values. Replace fixture identifiers with public IDs returned by the service. Request bodies and precise locations are transient; keep them out of logs.

curl

curl --fail-with-body --max-time 30 --max-filesize 16777216 --request GET 'https://irvinebroque.com/api/podcasts.json' --header 'Accept: application/json'

TypeScript

import { PublicApi } from '@irvinebroque/public-api';
const api = new PublicApi();
const result = await api.podcasts.list({});
console.log(result.status, result.headers.get('content-type')); // Keep transient capabilities in memory.

CLI

irvinebroque podcasts list

The SDK preserves status, headers, and the server envelope. A 304 has no fresh body. Errors retain structured problem details; ordinary error messages omit response details. Responses are limited to 16 MiB and requests time out after 30 seconds by default.