cursor

# Cursor Cloud Agents ## Purpose Drive Cursor Cloud Agents programmatically: launch an agent on a GitHub repo with a prompt, poll its run, and collect the pull request it opens. Good for delegating well-scoped coding tasks (fixes, docs, tests, small features) to a background agent while you keep working. ## Tooling Call the REST API at `https://api.cursor.com` (v1) directly, or wrap it in a thin CLI. The core calls: ```bash BASE=https://api.cursor.com AUTH="Authorization: Bearer $CURSOR_API_KEY" curl -s -H "$AUTH" "$BASE/v1/me" # auth check curl -s -H "$AUTH" "$BASE/v1/repositories" # connected GitHub repos curl -s -H "$AUTH" "$BASE/v1/models" # available models # Launch: creates the agent AND enqueues its first run. curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" -d '{ "prompt": {"text": "Fix the failing test in tests/test_api.py"}, "repos": [{"url": "https://github.com/you/your-repo"}], "autoCreatePR": true, "skipReviewerRequest": true, "mode": "agent" }' "$BASE/v1/agents" # -> {agent: {id}, run: {id, status}} curl -s -H "$AUTH" "$BASE/v1/agents/<agent_id>/runs/<run_id>" # status, duration, PR URLs curl -s -H "$AUTH" "$BASE/v1/agents/<agent_id>/runs" # all runs for an agent curl -s -X POST -H "$AUTH" -H "Content-Type: application/json" \ -d '{"prompt": {"text": "Now add a test for the fix"}}' \ "$BASE/v1/agents/<agent_id>/runs" # follow-up run on same agent curl -s -X POST -H "$AUTH" "$BASE/v1/agents/<agent_id>/runs/<run_id>/cancel" curl -s -H "$AUTH" "$BASE/v1/agents/<agent_id>/usage" # token usage ``` The launch response carries `agent.id` and `run.id` — save both; every later call needs them. A finished run's status response includes its PR URL(s) and branch. ## Auth - Create an API key in your Cursor account settings and pass it as a Bearer token from an environment variable at runtime — never hardcoded, never written to files, logs, or memory. - `GET /v1/me` is the cheap auth check. A 401/403 with the header attached means the key itself is wrong or revoked — rotate it in settings. ## Operating Rules 1. **The GitHub repo must already be connected** to the Cursor account — check `GET /v1/repositories` before launching; there is no API-side way to connect a new repo. 2. **Don't pin a `model` unless you mean it.** Omitting it uses the account's default models and included usage pool; an explicit model can draw from a different (metered) pool. Check `GET /v1/models` first. 3. With `autoCreatePR`, a completed run opens a PR. **Agents push branches; humans merge.** Review every PR before it lands — never auto-merge agent output. 4. Keep prompts PR-sized: one task, clear acceptance criteria, named files where you know them. A follow-up run on the same agent is cheaper than a fresh launch when context carries over. 5. The API is public beta — if calls start failing in new ways, check the current endpoint docs at https://cursor.com/docs/cloud-agent/api/endpoints before blaming the key. 6. Report PR URLs and run status, never the API key. --- Also on Honeypot — a free, open index of skills for AI agents: https://honeypot-e6c.pages.dev [](https://honeypot-e6c.pages.dev)