# Riff API

> Riff answers the phone for plumbing and other trade businesses. The Riff API gives your software the calls Riff answered for one business: who called, their number, what they needed, how the call ended, the booked job, every event and the transcript. Read-only JSON at https://api.chattychapters.com/api/v1; each call is kept for 30 days.

Send the key as `Authorization: Bearer rk_live_…` on every request. Read it from the RIFF_API_KEY environment variable: never put it in a URL, never print it, never write it into a file or code you show, and never ask a person to paste it into a chat. Send a User-Agent header that names your app, so your requests are easy to find in logs.

To copy every call: page `GET /events` to its end and keep `next_cursor` first, then page `GET /calls?expand=transcript&limit=20`, sending `next_cursor` back as `cursor` until it is `null`. To stay up to date: send the saved cursor to `GET /events` as `after`, and fetch the call on `call.ended` or `call.claimed`. Errors are `{"error": {"code", "message"}}`; act on `code`. On 429 or 503, wait `Retry-After` seconds.

## Docs

- [Developers reference](https://whappai.com/developers.md): every route, parameter, error and header, with curl, Python and Node examples; quickstart, filters, transcripts, events, paging, limits and the 30-day rule.
- [Build your call log](https://whappai.com/developers-call-log.md): a step-by-step tutorial and a standard-library Python script that copies every call into calls.csv and transcript files, then keeps them up to date from the event feed.

## Reference

- [openapi.json](https://whappai.com/openapi.json): the contract, OpenAPI 3.1: every route, parameter, schema, error and header, with examples.
- [openapi.json on the API host](https://api.chattychapters.com/api/v1/openapi.json): the same file, served by the API itself with no key.

## Optional

- [Developers reference, web page](https://whappai.com/developers.html): the reference as HTML, with a box that puts your key into the examples.
- [Build your call log, web page](https://whappai.com/developers-call-log.html): the tutorial as HTML.
- [call_log.py](https://whappai.com/examples/call_log.py): the tutorial's script on its own, as plain text.