Podcast API

Sources Of Truth

• Use the live OpenAPI YAML for exact methods, parameters, request bodies, response schemas, and endpoint restrictions.
• Use the tutorial index for supported application workflows.
• Use the live API FAQ, billing FAQ, pricing, and terms for policies and facts that may change.

Workflow

1. Inspect the target repository before changing it.
   • Identify the language, framework, server-side boundary, HTTP client, environment-variable convention, and test setup.
   • Reuse an installed official SDK or the project's existing HTTP client. Otherwise prefer the language's native HTTP facilities instead of adding a dependency.
2. Select the operation.
   • Read endpoint-selection.md.
   • Load only the use-case reference relevant to the request.
   • Confirm the operation in the live OpenAPI document, including plan restrictions and pagination fields.
3. Design the security boundary.
   • Read

     LISTEN_API_KEY

     only in server-side code or a serverless function.
   • Send it as

     X-ListenAPI-Key

     to the production API.
   • Never place it in browser or mobile bundles, public environment variables, source control, URLs, fixtures, logs, or error messages.
   • If the current architecture cannot protect the key, add a server-side proxy before integrating the API.
4. Implement in the project's style.
   • Keep the production base URL configurable and default it to

     https://listen-api.listennotes.com/api/v2

     .
   • Encode query parameters and request bodies with structured APIs.
   • Validate inputs at the application's boundary and handle non-2xx responses explicitly.
   • Follow integration-rules.md for pagination, usage headers, caching, attribution, and error handling.
5. Test without spending quota.
   • Follow testing.md.
   • Use

     https://listen-api-test.listennotes.com/api/v2

     without an API key only for HTTP transport and response-shape tests.
   • Use local mocks or fixtures for parameter behavior, error paths, and pagination logic.
6. Verify the result.
   • Confirm no secret crosses a client boundary or appears in generated output.
   • Confirm the selected endpoint and every field used still exist in OpenAPI.
   • Confirm pagination terminates and does not issue unbounded requests.
   • Confirm UI using API data satisfies the applicable attribution rules.

Reference Routing

• Endpoint choice and current API surface: endpoint-selection.md
• Authentication, errors, pagination, caching, and attribution: integration-rules.md
• Mock server and test strategy: testing.md
• Search, typeahead, genres, charts, and discovery: search-and-discovery.md
• Podcast lookup, episode sync, subscriptions, OPML, and webhooks: library-and-sync.md
• Playlists, curation, audio, embeds, and transcripts: playlists-and-media.md
• API keys, usage monitoring, and account operations: account-and-usage.md
• Product, policy, support, rate-limit, and data questions: api-faq.md
• Plans, quotas, charges, cancellation, and payments: billing-faq.md

Answering Questions

hello@listennotes.com