# Podnivo agent instructions

Use these instructions with coding agents that discover repository-level `AGENTS.md` files, including Codex and compatible agent harnesses.

## Documentation to load

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

Read the guide and the relevant OpenAPI operation before coding. OpenAPI wins if the sources differ. If the URLs are unavailable, ask the developer to attach them; do not guess fields, enum values, routes, or status codes.

## Required behavior

- Use `PODNIVO_BASE_URL`, default `https://api.podnivo.com`, and load server-only `PODNIVO_API_KEY` from secret configuration.
- Authenticate with `Authorization: Bearer <token>`.
- Never expose a `pb_live_` key in public clients, source control, logs, analytics, or prompts. Mint listener tokens from the application's backend with `POST /v1/user-tokens`.
- Preserve `page.next` unchanged as `after`; treat IDs and cursors as opaque strings.
- Reuse the project's HTTP, validation, error, secret, and test patterns with bounded timeouts.
- Handle `400`, `401`, `403`, `404`, `409`, `429`, and `5xx`; honor `Retry-After` and do not blindly retry `POST` requests.
- Verify webhook HMAC signatures from raw bytes and deduplicate event IDs before side effects.
- Do not mirror publisher audio without explicit rights. Use only permission-aware transcripts returned by the API.

The integration guide contains the full public route directory, scopes, schemas, listener token flow, webhook algorithm, quota headers, privacy rules, and completion checklist. Test the success and relevant failure paths, run repository checks, and report which environment was actually verified.