Skip to content

API Documentation

Purpose

podcast_scraper exposes three API surfaces, documented here:

  1. Programmatic (library) API — the public Python package: run_pipeline, Config, the data models, the CLI, and the non-interactive service interface. Importable from podcast_scraper, with stability guarantees.
  2. HTTP / Viewer API — the optional FastAPI server (podcast serve, all routes under /api/*) that backs the Vue 3 GI/KG viewer. Not part of the importable package surface; ships with the [dev] extra.
  3. MCP / Agent tools — the optional generic MCP server (podcast mcp) exposing the platform's read capabilities (search, the relational-query layer, CIL, catalog) as composable, read-only tools for agentic clients. Library-wrapped, stdio transport. Spec: PRD-034 / RFC-095; usage: Server Guide — MCP server.

Programmatic (library) API

Document Description
Core API Primary public API (run_pipeline, Config, package information)
Service API Non-interactive service interface for daemons and process management
CLI Interface Command-line interface documentation
Configuration API Configuration model, environment variables, and file formats
Data Models Core data structures (Episode, RssFeed, TranscriptionJob)
Multi-feed corpus artifacts corpus_manifest.json / corpus_run_summary.json contracts (#506); links to RFC-063
API Reference Complete public-API reference (run_pipeline, Config, Service)
API Boundaries Public vs. private API boundaries and stability guarantees
API Versioning API versioning strategy and compatibility policies
API Migration Guide Migration guides for API changes and breaking changes

HTTP / Viewer API ([dev] extra)

The FastAPI server and Vue 3 GI/KG viewer are optional and not imported from podcast_scraper top-level exports. The HTTP API Reference is the endpoint catalogue; the live, always-current spec is the server's own OpenAPI at /docs (when uvicorn is running).

Document Description
HTTP API Reference Endpoint catalogue + response models for all /api/* routes (the source of truth alongside live OpenAPI)
Server Guide Running the server (make serve), web/gi-kg-viewer/ route architecture, CORS, static SPA mounting, and extending it
RFC-062: GI/KG viewer v2 Viewer milestones and architecture
RFC-067: Corpus Library /api/corpus/* catalog, Library tab, search handoffs
RFC-068: Corpus Digest GET /api/corpus/digest, Digest tab, Library 24h glance (PRD-023); capability flag corpus_digest_api on GET /api/health
RFC-094: Search-powered surfaces query layer /api/relational/* relational-query layer (#882) + /api/corpus/query-activity (FR6.2); consumed by the PRD-033 surfaces

v2.6.0 ships Corpus Library routes, index rebuild, and related viewer UX; see Release v2.6.0.

Quick Start

For programmatic usage:

  1. Start with Core API — Main entry point and functions.
  2. Review Configuration API — Setup and configuration options.
  3. See Data Models — Understand data structures.

For command-line usage:

  1. See CLI Interface — Command-line options and examples.

For service/daemon usage:

  1. See Service API — Non-interactive service interface.

For the HTTP viewer (podcast serve, /api/*):

  1. See the HTTP API Reference — the endpoint catalogue and response models.
  2. See the Server Guide — install the [dev] extra, run the server, CORS/static assets, and add routes.

For API stability and migration:

  1. See API Boundaries — What's public vs. private.
  2. See API Versioning — Versioning strategy.
  3. See API Migration Guide — Breaking changes.