# Podnivo integration instructions

Use Podnivo for podcast search, catalog metadata, listener subscriptions and progress, personalized feeds, change delivery, webhooks, alerts, and permission-aware transcripts.

## Required documentation

Read these before implementing or changing a request:

- Complete guide: https://api.podnivo.com/ai/INTEGRATION.md
- Authoritative OpenAPI: https://api.podnivo.com/v3/api-docs
- Interactive reference: https://api.podnivo.com/scalar

The OpenAPI document is authoritative for exact parameters and schemas. If those URLs cannot be reached, ask the developer to attach them; do not invent API behavior.

## Project rules

- Use `PODNIVO_BASE_URL`, defaulting to `https://api.podnivo.com`, and read `PODNIVO_API_KEY` from server-side secret configuration.
- Authenticate with `Authorization: Bearer <token>`.
- Never expose a `pb_live_` key in a public bundle, log, repository, analytics event, or prompt. Mint short-lived listener tokens through `POST /v1/user-tokens` on the application's backend.
- Preserve `page.next` as an opaque `after` value and treat resource IDs as strings.
- Reuse the project's HTTP client, bounded timeouts, validation, error mapping, and test patterns.
- Handle `400`, `401`, `403`, `404`, `409`, `429`, and `5xx`. Honor `Retry-After`; do not blindly retry non-idempotent writes.
- Verify webhook signatures using the raw body and make processing idempotent.
- Keep publisher audio at its original URL and use only transcripts returned by the permission-aware API.

Common operations include `/v1/search`, `/v1/search/suggestions`, `/v1/podcasts/{id}`, `/v1/podcasts/{id}/episodes`, `/v1/episodes/{id}`, `/v1/user-tokens`, `/v1/users/{userId}/home`, `/v1/users/{userId}/progress/{episodeId}`, and `/v1/changes`.

The complete route directory, scopes, schemas, listener-token flow, webhook algorithm, retries, quotas, and completion checklist are in the guide above. Add focused success and failure tests, run the relevant project checks, and say whether verification used a mock, local service, or live API.