Skip to content

API Documentation

Purpose

This directory contains comprehensive API documentation for podcast_scraper, including programmatic interfaces, configuration options, data models, and migration guides.

API Documentation Index

Core APIs

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

HTTP / viewer API ([dev] extra)

The FastAPI server and Vue 3 GI/KG viewer are optional. They are not imported from podcast_scraper top-level exports; stability is documented in the Server Guide and OpenAPI (/docs when uvicorn is running).

Document Description
Server Guide Endpoints under /api/*, static SPA mounting, dev workflow (make serve), testing pointers
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

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

API Reference & Guides

Document Description
API Reference Complete API reference documentation
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

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 Server Guide — Install [dev] extra, endpoint reference, CORS and static assets.

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.