Nanoru API quickstart
This guide takes you from an API key to a named transcript in a few calls. Every endpoint and webhook, with its fields, examples and errors, is in the API reference.
1. Make a key
An owner or admin makes keys in the workspace, under Admin → API keys. Pick a preset (an integration that sends episodes and reads results needs full_integration), and copy the key when it's shown: Nanoru never shows it again. Send it on every call as Authorization: Bearer <key>.
2. Send an episode
Send a link Nanoru can fetch:
curl https://nanoru.example/api/v1/media \
-H "Authorization: Bearer $NANORU_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: breakfast-2026-11-12" \
-d '{"title": "The Breakfast Show, 12 November", "source_url": "https://cdn.example.com/brk/2026-11-12.mp3", "external_id": "BRK-2026-11-12"}'
The answer has the episode's media_id. The Idempotency-Key makes the call safe to repeat: if your request times out and you send it again with the same key, Nanoru answers with the episode it already made.
To send a file instead of a link, use {"title": ..., "upload": {"size": <bytes>}} and follow the upload steps in the reference.
3. Send many at once
For a back catalogue or a season, send up to 1,000 episodes in one call with POST /api/v1/batches. The batch is accepted whole or not at all, and you can follow it as one thing: GET /api/v1/batches/{id} gives its counts, what failed and why, and an estimate of when it will finish.
Sending one episode per call works too, but the API paces you (a 429 with Retry-After tells you how long to wait), so a large set goes much faster as a batch.
4. Hear when it's done
Add a webhook under Admin → Webhooks, or with POST /api/v1/webhook-endpoints, and listen for media.completed. Each delivery is signed with your endpoint's secret, so you can check it came from Nanoru. batch.completed tells you when a whole batch has finished.
If you'd rather poll, GET /api/v1/media/{id} shows status (processing, then final) and, while it works, the stage it's at. If your plan or budget doesn't allow an episode yet, it waits with stage: held and a hold that says why, and starts by itself when the reason clears.
5. Read the transcript
curl "https://nanoru.example/api/v1/media/$MEDIA_ID?include=turns,words" \
-H "Authorization: Bearer $NANORU_KEY"
Each turn has its start and end, its words, and the speaker: a named person, or an unknown speaker you can name later. Naming a voice once names it in every episode it's in. Captions are at /media/{id}/captions.vtt and /media/{id}/captions.srt.
When someone reviews an episode in the workspace, media.reviewed follows. The transcript can change after you first read it; GET /media/{id}/changes?since=<revision> gives just what changed.