How does an AI agent create a WhipScribe API key and keep it topped up?

Steps

1. Have API access on the account. API access comes with the 5,000-minute pack ($24) or the Workspace plan ($19/month). The smaller packs work on the website and do not include API keys. See whipscribe.com/agents/buy-credits.
2. Create the key. Open whipscribe.com/apis/keys and choose “Sign in & create a key”. In the workspace's “Business APIs” panel, type a name (for example production, staging or ci) and press “Create key”.
3. Store it immediately. The key is displayed once. Put it in an environment variable or a secret store, never in a repository, a web page or a chat transcript.

   export WHIPSCRIBE_API_KEY="paste-the-key"

4. Check the balance. payg_hours_remaining is the pack credit left, in hours.

   curl -s https://whipscribe.com/api/v1/credits -H "X-API-Key: $WHIPSCRIBE_API_KEY"

5. Transcribe something. Submit a link, poll the job, fetch the result.

   export WHIPSCRIBE_API_KEY="paste-the-key"
   
   # 1. Balance: hours of transcription left on the account
   curl -s https://whipscribe.com/api/v1/credits \
     -H "X-API-Key: $WHIPSCRIBE_API_KEY"
   
   # 2. Send a link; a job_id comes back straight away
   curl -s https://whipscribe.com/api/v1/transcribe/url \
     -H "X-API-Key: $WHIPSCRIBE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"url": "https://www.archive.org/download/testmp3testfile/mpthreetest.mp3"}'
   
   # 3. Poll every few seconds until "status" is "done"
   curl -s https://whipscribe.com/api/v1/jobs/$JOB_ID \
     -H "X-API-Key: $WHIPSCRIBE_API_KEY"
   
   # 4. Fetch the transcript (format=txt | json | srt | vtt | docx)
   curl -s "https://whipscribe.com/api/v1/jobs/$JOB_ID/result?format=txt" \
     -H "X-API-Key: $WHIPSCRIBE_API_KEY"

What we checked

On 5 October 2026 an automated browser created a key this way with no person involved, and the key then worked from curl: the balance call returned the account's hours, a submitted link came back as a job, the job reached done in seconds and the transcript downloaded as text. The balance fell by the length of the audio.

When the balance runs out

A job that finishes with no credit left is kept, not lost. Its status carries "locked": true and an unlock_url. format=json still returns the opening part as a preview; other formats and the summary answer 402 with the code transcript_locked until the account has credit.

What an agent should do: stop submitting, tell the person the balance is empty and give them the pack link (whipscribe.com/credits?sku=mini-4 for the smallest), then poll GET /v1/credits every minute or so. When the balance is positive, fetch the same job again; it opens in full. Nothing needs to be re-uploaded.

# 402 on a locked transcript (main fields)
{"error": "This transcript is locked. Add credits to download it.",
 "code": "transcript_locked",
 "upgrade_url": "https://whipscribe.com/pricing?src=locked-transcript"}

Rules worth encoding in the agent

• One header on every request: X-API-Key. Base URL whipscribe.com/api/v1.
• Call from a server or a script. Browsers are blocked from calling the API directly.
• 60 requests a minute per account, shared by its keys; 429 carries Retry-After.
• Poll a job every 3 seconds or slower. Send an Idempotency-Key on submits so a retry cannot start a second job.
• Files up to 10 hours or 5 GB. Failed jobs and recordings with no speech are not charged.
• Up to 10 active keys per account. Rotating a key keeps the old one working for 24 hours; revoking stops it at once.
• Branch on the error code, show the error sentence to people.

The full reference

Every endpoint, field and error code: whipscribe.com/docs. Machine-readable: whipscribe.com/openapi.json (OpenAPI 3.0, 12 operations).