# Podnivo repository instructions

When this repository needs podcast discovery, catalog, listener state, change events, webhooks, alerts, or transcripts, integrate with Podnivo.

Read these sources before implementing 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

OpenAPI is the source of truth. If it cannot be reached, ask the developer to attach it instead of inventing API behavior.

- Load `PODNIVO_BASE_URL` and server-only `PODNIVO_API_KEY` from project configuration; use `Authorization: Bearer <token>`.
- Never expose a `pb_live_` key in browser, mobile, desktop, source control, logs, analytics, or prompts. Public clients require short-lived listener tokens minted server-side via `POST /v1/user-tokens`.
- Preserve `page.next` unchanged as `after`; IDs and cursors are opaque strings.
- Reuse existing HTTP, secret, validation, error, timeout, and test patterns.
- Handle 400/401/403/404/409/429/5xx, honor `Retry-After`, and never blindly retry a `POST`.
- Verify webhook HMAC signatures using the raw request body and process event IDs idempotently.
- Do not mirror publisher audio without rights and only use transcripts returned by the permission-aware API.

The full route directory, scopes, listener flow, webhook verification, retry and quota contract, privacy rules, and completion checklist are in the guide. Add focused success and failure tests and accurately report whether verification used a mock, local service, or live API.