---
name: podnivo
description: Integrate Podnivo podcast search, catalog, listener state, webhooks, alerts, and permission-aware transcripts. Use when building or reviewing an application that calls the Podnivo REST API.
---

# Podnivo

Use Podnivo as the server-side podcast catalog and listener-state backend for the current project.

## Read the contract first

Before coding, read both authoritative sources:

- Complete integration guide: https://api.podnivo.com/ai/INTEGRATION.md
- Live OpenAPI 3 contract: https://api.podnivo.com/v3/api-docs
- Interactive reference: https://api.podnivo.com/scalar

OpenAPI is the source of truth for exact operations and schemas. If network access is unavailable, ask the user to attach the guide and OpenAPI document. Do not guess fields, enum values, or endpoints.

## Non-negotiable rules

- Read `PODNIVO_BASE_URL` (default `https://api.podnivo.com`) and server-only `PODNIVO_API_KEY` from the project's secret configuration.
- Send credentials as `Authorization: Bearer <token>`.
- Never expose a `pb_live_` key in browser, mobile, desktop, logs, source control, or prompts. Mint short-lived listener tokens server-side with `POST /v1/user-tokens` for untrusted clients.
- Preserve `page.next` exactly and return it as `after`. Treat all IDs and cursors as opaque strings.
- Use bounded timeouts. Handle `400`, `401`, `403`, `404`, `409`, `429`, and `5xx`; honor `Retry-After` and never blindly retry a `POST`.
- Verify webhook HMAC signatures against raw bytes and deduplicate events before side effects.
- Do not mirror publisher audio without rights. Use only transcripts returned by the permission-aware API.

## Core operations

```http
GET  /v1/search?q=climate&type=podcast&sort=relevance&limit=20
GET  /v1/search/suggestions?q=clim&type=all&limit=8
GET  /v1/podcasts/{id}
GET  /v1/podcasts/{id}/episodes
GET  /v1/episodes/{id}
POST /v1/user-tokens
GET  /v1/users/{userId}/home
PUT  /v1/users/{userId}/progress/{episodeId}
GET  /v1/changes
```

The complete route directory, listener-token flow, pagination contract, webhook verification algorithm, error model, scopes, quotas, and test checklist are in the integration guide linked above.

## Workflow

1. Inspect the repository's language, HTTP client, secret loading, error types, and test conventions.
2. Read the relevant OpenAPI operation and schemas.
3. Implement the smallest requested server-side integration using existing project patterns.
4. Add focused tests for success, invalid input, auth/scope failure, conflicts or quotas where relevant, and timeout behavior.
5. Run the repository's checks and report the exact environment and API behaviors verified.