> ## Documentation Index
> Fetch the complete documentation index at: https://docs.audivo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Price a selection

> Many episodes at once: quote a selection, confirm it as one group, read the results.

For one episode, [one call](https://docs.audivo.dev/quickstart.md) is all you need. A quote is for a
**selection**: the newest episode of every show in a chart, twenty episodes
of one show, a list of uploads. It prices the whole selection before
anything is spent, splits cached from uncached, tells you whether your plan
has room for the jobs, and turns into one job group when you confirm it.

Everything below sends one header, `Authorization: Bearer <your key>`, and
uses the base URL the API Reference declares. Replace `hk_live_...` with a key
from your dashboard. Set the API base URL before running the examples:

```bash theme={null}
export AUDIVO_API="https://api.audivo.dev"
```

**1. Find the show**

```bash theme={null}
curl -G "$AUDIVO_API/v1/search/shows" \
  --data-urlencode "q=The Changelog" \
  -H "Authorization: Bearer hk_live_..."
```

Results are ordered so that the show a name means comes first: an exact
title match, then the larger catalogue. Each entry carries the two values
the next steps need, `feed_url` and `itunes_id`, and a `show_id`.
Publisher-written titles are shown but never needed as input.

**2. Pick an episode (optional)**

A quote takes a show's newest episodes by default. To reach an older one,
list the show's episodes and note its `episode_id`:

```bash theme={null}
curl -G "$AUDIVO_API/v1/shows/$SHOW_ID/episodes" \
  --data-urlencode "feed_url=$FEED_URL" \
  --data-urlencode "itunes_id=$ITUNES_ID" \
  -H "Authorization: Bearer hk_live_..."
```

The feed URL travels with the request because a `show_id` is a one-way
derivation and cannot be turned back into a feed.

**3. Price it**

```bash theme={null}
curl -X POST "$AUDIVO_API/v1/quotes" \
  -H "Authorization: Bearer hk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shows": [
      { "feed_url": "'"$FEED_URL"'", "itunes_id": '"$ITUNES_ID"', "episode_ids": ["'"$EPISODE_ID"'"] }
    ]
  }'
```

A selection can also be a chart (`"chart": { "category": "Business", "size": 20 }`)
with `episodes_per_show`, or a list of your own `uploads`.

The answer lists every episode with `estimated_credits` and
`quote_ceiling_credits` — the estimate plus 25%, rounded up, which is the
most that episode can settle for — plus `total_ceiling_credits` for the
whole selection and a `quote_id`. An episode that is already transcribed
comes back `is_cached: true` at the cached-read price. Nothing is
reserved by a quote.

**4. Confirm it**

```bash theme={null}
curl -X POST "$AUDIVO_API/v1/quotes/$QUOTE_ID/confirm" \
  -H "Authorization: Bearer hk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "expected_total_credits": '"$TOTAL_CEILING_CREDITS"' }'
```

Restate the quote's `total_ceiling_credits`; a different number is refused
and nothing is spent. The `Idempotency-Key` makes a retry safe: the same
key returns the same group instead of spending twice. The response is a
**job group**: cached episodes appear as `cached_read` members with a
`read_id`, everything else as `job` members holding their reservation.

**5. Poll the group**

```bash theme={null}
curl "$AUDIVO_API/v1/groups/$GROUP_ID" \
  -H "Authorization: Bearer hk_live_..."
```

`member_counts` tells you how many jobs are queued, transcribing or
completed; `credits_reserved`, `credits_settled` and `credits_released`
tell you what the group has cost so far. A typical hour of audio finishes
in a few minutes.

**6. Read the transcript**

```bash theme={null}
# a job that completed
curl "$AUDIVO_API/v1/transcripts/$JOB_ID?format=json" \
  -H "Authorization: Bearer hk_live_..."

# a cached read the confirm already paid for
curl "$AUDIVO_API/v1/reads/$READ_ID?format=text" \
  -H "Authorization: Bearer hk_live_..."
```

`format` is one of `json`, `text`, `srt`, `vtt` or `md`. The JSON form
carries segments with start and end times, word timings where the engine
produced them, the detected language, and the source the text came from.
Reading a transcript you already paid for costs nothing.

## Where the money goes

| moment | what happens to credits |
| - | - |
| quote | nothing |
| confirm | each job reserves its ceiling; each cached read settles at once |
| completion | a job settles at the measured audio, capped at the ceiling, and releases the rest |
| failure or cancel | the whole reservation is released, exactly once |

Balance and reservations are on every quote response as `balance_credits`
and `reserved_credits`, which is how an API-key caller reads what it has left.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.