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

Create an API key, put it in the environment as WHIPSCRIBE_API_KEY, and give the agent two URLs: https://whipscribe.com/openapi.json for the exact endpoints and https://whipscribe.com/agents/instructions.md for the rules. The whole integration is three calls: submit a link or file, poll the job, fetch the transcript. For in-editor tools, add the local MCP server.

Checked 5 October 2026. HTML version: https://whipscribe.com/agents/cursor

## Steps

1. **Create the key.** A person or a browser agent does this once: https://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.

## Questions

**Is there an SDK?**
No SDK is needed: the API is plain HTTPS with JSON. Generate a client from https://whipscribe.com/openapi.json if you want typed calls.

**Where do large files go?**
Files too big for one upload use the direct-upload pair: POST /v1/uploads/init, upload to the link it returns, then POST /v1/uploads/{job_id}/commit. Up to 10 hours or 5 GB per file.

**Can the agent check the balance before a batch?**
Yes: GET /v1/credits returns payg_hours_remaining. Compare it with the total audio length before submitting.

**Does AGENTS.md matter here?**
Put the contract block from step 3 in your repository's agent rules file (AGENTS.md, .cursorrules or similar) so every session starts with it.

## Related

- Overview: https://whipscribe.com/agents/index.md
- Instructions for agents: https://whipscribe.com/agents/instructions.md
- How does an AI agent create a WhipScribe account?: https://whipscribe.com/agents/sign-up.md
- How does an AI agent buy WhipScribe credit?: https://whipscribe.com/agents/buy-credits.md
- How does an AI agent create a WhipScribe API key and keep it topped up?: https://whipscribe.com/agents/api-key.md
- How do I get Claude or Claude Code to transcribe with WhipScribe?: https://whipscribe.com/agents/claude.md
- How do I get ChatGPT to transcribe with WhipScribe?: https://whipscribe.com/agents/chatgpt.md
- How do I get an n8n, Make or Zapier agent to transcribe with WhipScribe?: https://whipscribe.com/agents/n8n-make-zapier.md
- How do I transcribe from an Apify Actor or an Apify-based agent?: https://whipscribe.com/agents/apify.md
- API docs: https://whipscribe.com/docs
- OpenAPI: https://whipscribe.com/openapi.json
- Pricing: https://whipscribe.com/pricing