Quickstart

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:

export HARK_API="https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod"

Find the show

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.

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:

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.

Price it

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.

Confirm it

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.

Poll the group

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.

Read the transcript

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

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.

Start

Guides

MCP server

Reference

Billing

Trust

Where the money goes

​Where the money goes

Where the money goes