cursor

Cursor

Cursor Cloud Agents (formerly Background Agents) run autonomous coding tasks on your GitHub repositories in the cloud. The REST API lets you launch an agent with a prompt, stream or poll its runs, send follow-up instructions, inspect artifacts, and manage the agent lifecycle.

Official docs: https://cursor.com/docs/background-agent/api/overview

When to Use

Use this skill when you need to:

Launch a Cursor agent to work on a GitHub repository from a natural-language prompt
List your agents and check their status
Send a follow-up prompt to an active agent
Poll or stream the runs an agent produces
List the models and repositories available to your account
Archive, unarchive, or permanently delete an agent

Prerequisites

Connect the Cursor connector at app.vm0.ai/connectors.

The API key is created from the Cursor Dashboard → API Keys.

Troubleshooting: If requests fail, run zero doctor check-connector --env-name CURSOR_TOKEN or zero doctor check-connector --url https://api.cursor.com/v1/me --method GET

How to Use

All requests go to https://api.cursor.com and authenticate with a Bearer token: Authorization: Bearer $CURSOR_TOKEN.

1. Check the API Key

Confirm the connector works and see which account the key belongs to:

curl -s "https://api.cursor.com/v1/me" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

2. List Available Models

Model IDs change as new models launch — confirm an exact ID before launching an agent:

curl -s "https://api.cursor.com/v1/models" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

3. List Accessible Repositories

curl -s "https://api.cursor.com/v1/repositories" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

4. Launch an Agent

Write the request body to /tmp/cursor_agent.json:

{
  "prompt": {
    "text": "Add input validation to the signup form and write tests."
  },
  "source": {
    "repository": "https://github.com/your-org/your-repo",
    "ref": "main"
  }
}

Then create the agent (this enqueues the initial run):

curl -s -X POST "https://api.cursor.com/v1/agents" --header "Content-Type: application/json" --header "Authorization: Bearer $CURSOR_TOKEN" -d @/tmp/cursor_agent.json | jq

The response includes the agent id — use it in the calls below.

5. List Agents

curl -s "https://api.cursor.com/v1/agents" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

6. Get Agent Status

Replace <agent-id> with the id from step 4:

curl -s "https://api.cursor.com/v1/agents/<agent-id>" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

7. List and Inspect Runs

List the runs for an agent:

curl -s "https://api.cursor.com/v1/agents/<agent-id>/runs" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

Get a single run's status and results. Replace <run-id>:

curl -s "https://api.cursor.com/v1/agents/<agent-id>/runs/<run-id>" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

8. Send a Follow-up Prompt

Active agents accept follow-up prompts as new runs. Write to /tmp/cursor_followup.json:

{
  "prompt": {
    "text": "Also update the README to document the new validation rules."
  }
}

Then submit it:

curl -s -X POST "https://api.cursor.com/v1/agents/<agent-id>/runs" --header "Content-Type: application/json" --header "Authorization: Bearer $CURSOR_TOKEN" -d @/tmp/cursor_followup.json | jq

9. Cancel an Active Run

curl -s -X POST "https://api.cursor.com/v1/agents/<agent-id>/runs/<run-id>/cancel" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

10. List Artifacts

curl -s "https://api.cursor.com/v1/agents/<agent-id>/artifacts" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

11. Manage the Agent Lifecycle

Archive, unarchive, or permanently delete an agent:

curl -s -X POST "https://api.cursor.com/v1/agents/<agent-id>/archive" --header "Authorization: Bearer $CURSOR_TOKEN" | jq
curl -s -X POST "https://api.cursor.com/v1/agents/<agent-id>/unarchive" --header "Authorization: Bearer $CURSOR_TOKEN" | jq
curl -s -X DELETE "https://api.cursor.com/v1/agents/<agent-id>" --header "Authorization: Bearer $CURSOR_TOKEN" | jq

Guidelines

Bearer auth: every request needs Authorization: Bearer $CURSOR_TOKEN; the same key also works as Basic auth (-u $CURSOR_TOKEN:) but prefer Bearer here
Agent then runs: creating an agent (POST /v1/agents) enqueues the first run automatically; subsequent instructions are added as new runs under that agent
Confirm IDs first: call the models (example 2) and repositories (example 3) endpoints to confirm valid values before launching an agent
Async work: agents run asynchronously — poll GET /v1/agents/{id}/runs/{runId} until the run reports a terminal status before reading results
Artifact URLs expire: presigned download URLs from the artifacts endpoint are short-lived (about 15 minutes) — fetch them just before downloading
401 Unauthorized: the key is missing or invalid — reconnect the Cursor connector at app.vm0.ai/connectors