> ## 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.

# Quickstart

> One episode, end to end, with curl.

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 HARK_API="https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod"
```

<Steps>
  <Step title="Find the show">
    ```bash theme={null}
    curl -G "$HARK_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.
  </Step>

  <Step title="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 "$HARK_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.
  </Step>

  <Step title="Price it">
    ```bash theme={null}
    curl -X POST "$HARK_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"'"] }
        ]
      }'
    ```

    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.
  </Step>

  <Step title="Confirm it">
    ```bash theme={null}
    curl -X POST "$HARK_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.
  </Step>

  <Step title="Poll the group">
    ```bash theme={null}
    curl "$HARK_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.
  </Step>

  <Step title="Read the transcript">
    ```bash theme={null}
    # a job that completed
    curl "$HARK_API/v1/transcripts/$JOB_ID?format=json" \
      -H "Authorization: Bearer hk_live_..."

    # a cached read the confirm already paid for
    curl "$HARK_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.
  </Step>
</Steps>

## 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.