Cursor

import { Aside } from “@astrojs/starlight/components”;

Cursor’s cloud agents are a hosted API: Cursor clones your repo, runs the agent, and opens a PR. Beeps creates an agent run when an alert fires, polls Cursor for status, and writes the PR URL onto the alert responder.

The Cursor Background Agents API requires **Privacy Mode** to be turned on in your Cursor account settings. Without it, every API call returns `403 Forbidden` with no other signal. This is the #1 cause of "my Cursor integration won't work" support questions — fix it before anything else.

Prerequisites

• A Cursor account with cloud agents enabled.
• Privacy Mode enabled in account settings (see callout above).
• A GitHub repository Cursor can clone. The repository URL goes on the relay rule, not the integration.

Provider-side setup

1. Sign in to cursor.com/dashboard.
2. Enable Privacy Mode in account settings.
3. Generate an API key from the same dashboard.
4. Save the API key; you’ll paste it into beeps as apiKey.

Beeps-side setup

Create the integration:

const cursorIntegration = await client.integration.create({
  name: "Cursor Agent",
  provider: "cursor",
  apiKey: process.env.CURSOR_API_KEY,
});

Reference it from a relay rule. Cursor requires a repository URL on the rule. That’s the repo Cursor will clone and open the PR against:

await client.relay.rules.create(relayId, {
  name: "Cursor Auto-Fix",
  ruleType: "agent",
  config: {
    agentType: "cursor",
    integrationId: cursorIntegration.id,
    repository: "https://github.com/org/repo",
    autoCreatePr: true,
    pollInterval: 30000,
    maxPollAttempts: 120,
  },
});

Configuration reference

Integration metadata

Cursor doesn’t use metadata. Only apiKey is required.

Rule config

Field	Type	Required	Default	Description
agentType	"cursor"	yes	—	Selects the Cursor agent
integrationId	string	yes	—	The Cursor integration’s id
repository	string (URL)	yes	—	GitHub repo URL Cursor will clone
autoCreatePr	boolean	no	true	Whether the agent should open a PR
branchName	string	no	—	Override the branch name
autoBranch	boolean	no	true	Let Cursor pick the branch name

The shared polling and storm-control fields are documented in Relay Rules.

API version

Beeps targets the Cursor Cloud Agents v1 API (https://api.cursor.com/v1/agents). The legacy v0 endpoint had a different request and response shape; customers still pinned to v0 via an explicit config.endpoint override should plan to migrate, since v0 is no longer documented.

Troubleshooting

All requests return 403 Forbidden

Privacy Mode is not enabled on your Cursor account. Toggle it on in settings and retry.

Repository required error on dispatch

The repository URL must be on the rule config, not the integration metadata.

Cursor API error: response missing agent.id

You’re on a config.endpoint that returns a v0-shaped response. Either remove the endpoint override (recommended) or update it to a v1 path.