How do I get Cursor or a coding agent to use the WhipScribe API?

Steps

1. Create the key. A person or a browser agent does this once: whipscribe.com/agents/api-key. The account needs API access (the $24 pack or Workspace).
2. Put the key in the environment. Never in the repository. Add the variable name, not the value, to .env.example.

   # .env (git-ignored)
   WHIPSCRIBE_API_KEY=paste-the-key

3. Give the agent the contract. Paste this into the task, or into the project's agent rules file.

   Use the WhipScribe API for transcription.
   Spec: https://whipscribe.com/openapi.json
   Rules: https://whipscribe.com/agents/instructions.md
   Auth: header X-API-Key from the WHIPSCRIBE_API_KEY environment variable.
   Flow: POST /v1/transcribe/url (or /v1/transcribe for a file) -> poll GET /v1/jobs/{job_id} every 3 s until status is done or failed -> GET /v1/jobs/{job_id}/result?format=srt.
   If a job has "locked": true or a call returns 402, stop and tell me to add credit at https://whipscribe.com/credits?sku=mini-4.

4. Optional: add the local MCP server. For Cursor (.cursor/mcp.json), Windsurf or Claude Desktop. It reads the same key.

   {
     "mcpServers": {
       "whipscribe": {
         "command": "uvx",
         "args": ["--with", "mcp<2", "whipscribe-mcp"],
         "env": { "WHIPSCRIBE_API_KEY": "paste-the-key" }
       }
     }
   }

5. Smoke-test from the terminal. The agent can run this itself to prove the key works before writing code.

   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 the curl sequence above ran end to end with a fresh key: balance, submit, poll, transcript. The local MCP server started with that exact command and config, listed its six tools and transcribed a link. Without --with "mcp<2" the current package fails at start-up, so keep that argument.

Things coding agents get wrong

• Calling the API from front-end code. Browsers are blocked; call from a server, a script or a function.
• Waiting on the submit call. It returns a job_id at once; the transcript comes from polling.
• Polling in a tight loop. Every 3 seconds or slower; the limit is 60 requests a minute per account.
• Retrying a failed submit without an Idempotency-Key and starting two jobs.
• Printing the key in logs or committing it. Read it from the environment.
• Treating 402 as a bug. It means the balance is empty; the transcript is kept and opens when credit is added.

What needs a person

• Creating the account: sign-in is Google, or an email address plus a 6-digit code sent to that inbox. An agent with no access to the inbox has to ask the person for the code.
• Paying: the checkout asks for a card or PayPal. The person enters those details or approves the payment; an agent should hand this step over, not type card numbers.
• Keeping the key: an API key is shown once, when it is created. Whoever creates it stores it; nobody can look it up later.