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:

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 Image: Indexed on Honeypot