API reference · API keys

Get a public podcast

• Method: GET
• Path: /v1/podcasts/{slug}
• Operation ID: getPodcast
• Tags: Podcasts (public)

A public podcast by its UUID or slug. No key needed; responses are cached publicly.

Make a request

Set these environment variables before running a sample. Each language reads the same values; no identifier needs replacing inside the code.

Variable	Value to supply
PODCAST_SLUG	The podcast UUID or the slug from its public listen-page address.

Samples run on your server: curl 7.76+, Node.js 22+ (TypeScript via your TypeScript runner), Python 3, or PHP 8 with the cURL extension.

curl

: "${PODCAST_SLUG:?Set PODCAST_SLUG in your environment}"

curl --fail-with-body --silent --show-error --get \
  "https://api.show.fm/v1/podcasts/${PODCAST_SLUG}"

TypeScript

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} in your environment`);
  return value;
}

async function main() {
  const url = new URL(`https://api.show.fm/v1/podcasts/${encodeURIComponent(env("PODCAST_SLUG"))}`);

  const response = await fetch(url, {
    signal: AbortSignal.timeout(30_000)
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  console.log(JSON.stringify(await response.json(), null, 2));
}

main().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

JavaScript

function env(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} in your environment`);
  return value;
}

async function main() {
  const url = new URL(`https://api.show.fm/v1/podcasts/${encodeURIComponent(env("PODCAST_SLUG"))}`);

  const response = await fetch(url, {
    signal: AbortSignal.timeout(30_000)
  });
  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  console.log(JSON.stringify(await response.json(), null, 2));
}

main().catch(error => {
  console.error(error);
  process.exitCode = 1;
});

Python

import os
import json
from urllib.parse import quote, urlencode
from urllib.request import Request, urlopen
from urllib.error import HTTPError

url = f'https://api.show.fm/v1/podcasts/{quote(os.environ["PODCAST_SLUG"], safe="")}'
request = Request(url)
try:
    with urlopen(request, timeout=30) as response:
        print(json.dumps(json.load(response), indent=2))
except HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode()}") from error

PHP

<?php
function requiredEnv(string $name): string {
    $value = getenv($name);
    if ($value === false || $value === '') {
        throw new RuntimeException("Set $name in your environment");
    }
    return $value;
}

$url = "https://api.show.fm" . "/v1/podcasts/" . rawurlencode(requiredEnv("PODCAST_SLUG"));
$curl = curl_init($url);
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($curl);
if ($body === false) {
    throw new RuntimeException(curl_error($curl));
}
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
if ($status < 200 || $status >= 300) {
    throw new RuntimeException("HTTP $status: $body");
}
echo json_encode(json_decode($body, false, 512, JSON_THROW_ON_ERROR), JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;

Base URL

• https://api.show.fm

Authentication

No authentication required.

Path parameters

• slug (required): string

  The podcast UUID or slug (its show.fm address). UUIDs resolve to the current slug and share its cached payload. Malformed references return HTTP 400; well-formed unknown references return HTTP 404.

Responses

200400403404429

Browse the documented response statuses, headers and body fields.

200 OK

Response body

Content type: application/json

no additional properties

• data (required): Podcast

Example response

Illustrative data; your identifiers and figures will differ.

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "slug": "example-show",
    "guid": null,
    "title": "Example Show",
    "subtitle": null,
    "author": "Example Host",
    "description": "An illustrative podcast.",
    "language": "en",
    "category": null,
    "subcategory": null,
    "explicit": false,
    "artwork": {
      "url": null
    },
    "brand_color": null,
    "player_color": null,
    "player_theme": "light",
    "player_waveform": false,
    "website_url": null,
    "episode_count": 1,
    "links": {
      "listen": "https://example-show.show.fm",
      "feed": "https://rss.cdn.media/123e4567-e89b-12d3-a456-426614174000"
    },
    "branding": {
      "show_powered_by": true
    }
  }
}

400, 403, 404, 429

• 400 invalid_request.
• 403 unavailable: This episode can't be played right now. Returned only for an overage-suspended show whose requested content otherwise passes every visibility gate. Scheduled and unknown episodes still return the identical 404. Cache-Control: no-store.
• 404 not_found. Unknown or non-public content, including scheduled, unpublished, archived or deleted episodes.
• 429 rate_limited.

Response body

Content type: application/json

schema: Error, no additional properties

• error (required): object, no additional properties

  • code (required): string, possible values: "invalid_request", "not_found", "unavailable", "unauthorized", "invalid_api_key", "insufficient_scope", "forbidden", "plan_upgrade_required", "rate_limited", "service_unavailable", "internal_error", "not_implemented"

  • message (required): string

  • details: array

    Items:

    no additional properties

    • field (required): string

    • message (required): string

    • reason: string

      A stable reason a client may branch on, for example outside_retention.

  • docs_url: string

  • request_id: string