Cursor
App · 25 actions
Create and manage Cursor Cloud Agents, follow their runs, and manage saved environments and builds.
Actions
| Action | What it does |
|---|---|
| Archive agent | Archive an agent. |
| Cancel run | Stop an agent's run that is still going. |
| Create environment | Save an environment agents can start from. |
| Delete agent | Delete an agent for good. |
| Delete environment | Delete a saved environment for good. |
| Get active environment build | Find out what an agent started on this environment starts from: one of its builds, or Cursor's own. |
| Get agent | Get an agent's details: its name, status and repositories. |
| Get agent usage | Get how much an agent has used, run by run. |
| Get API key details | Get the name of the API key this connection uses, and when it was made. |
| Get environment | Get a saved environment, its setup and how it is built. |
| Get environment build | Get one of an environment's builds. |
| Get run | Get a run's status, and when it started and finished. |
| List agents | List your agents, newest first. |
| List artifacts | List the files an agent made. |
| List environment builds | List an environment's builds, newest first. |
| List environment history | List the changes made to an environment, newest first. |
| List environments | List your saved environments, most recently changed first. |
| List models | List the models an agent can use. |
| List repositories | List the GitHub repositories Cursor can work in. |
| List runs | List an agent's runs, newest first. |
| Send follow-up | Give a running agent another instruction. |
| Start agent | Start a Cursor agent on a coding task in a repository. |
| Start environment build | Build an environment. |
| Unarchive agent | Bring an archived agent back, so it can be given work again. |
| Update environment | Rename an environment, or change its setup or repositories. |
Archive agent
Archive an agent.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"id": "example"
},
"has_more": false,
"next_cursor": null
}Cancel run
Stop an agent's run that is still going.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
- Run ID
run_idtextRequired - Unique identifier for the run.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"id": "example"
},
"has_more": false,
"next_cursor": null
}Create environment
Save an environment agents can start from.
Inputs
- Owner
ownertextRequired - `personal` creates an environment for the API key's user, and `team` creates one for the team.One of:
personal,team. - Name
nametextRequired - Display name. It must differ from the names of the owner's other environments; a name the owner already uses returns `409 environment_name_conflict`.
- Repos
reposlistRequired - Repositories for the environment, or an empty array for an environment without repositories. Cursor must be able to reach each one through your source control integration; otherwise the request returns `400 repository_access`.
- Environment JSON
environment_jsonobjectRequired - The environment's `environment.json`, as a JSON-encoded string, using the same schema as a `.cursor/environment.json` file. An invalid configuration returns `400 validation_error`.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"createdAt": "example",
"id": "example",
"name": "example",
"owner": "example",
"repos": [],
"updatedAt": "example"
},
"has_more": false,
"next_cursor": null
}Delete agent
Delete an agent for good.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"id": "example"
},
"has_more": false,
"next_cursor": null
}Delete environment
Delete a saved environment for good.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"id": "example"
},
"has_more": false,
"next_cursor": null
}Get active environment build
Find out what an agent started on this environment starts from: one of its builds, or Cursor's own.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"buildId": "example",
"type": "example"
},
"has_more": false,
"next_cursor": null
}Get agent
Get an agent's details: its name, status and repositories.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"autoCreatePR": false,
"createdAt": "example",
"customSubagents": [],
"env": {
"name": "example",
"type": "example"
},
"id": "example",
"latestRunId": "example",
"name": "example",
"repos": [],
"skipReviewerRequest": false,
"status": "example",
"updatedAt": "example",
"url": "example",
"workOnCurrentBranch": false
},
"has_more": false,
"next_cursor": null
}Get agent usage
Get how much an agent has used, run by run.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
- Run ID
run_idtext - Scope usage to a single run. Omit to return usage for every run on the agent.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"runs": [],
"totalUsage": {
"cacheReadTokens": 0,
"cacheWriteTokens": 0,
"inputTokens": 0,
"outputTokens": 0,
"totalTokens": 0
}
},
"has_more": false,
"next_cursor": null
}Get API key details
Get the name of the API key this connection uses, and when it was made.
Inputs
None.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"apiKeyName": "example",
"createdAt": "example",
"userEmail": "example",
"userFirstName": "example",
"userId": 0,
"userLastName": "example"
},
"has_more": false,
"next_cursor": null
}Get environment
Get a saved environment, its setup and how it is built.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"buildSettings": {
"installTimeoutMinutes": null,
"pullLatestCode": "example",
"stalenessThresholdHours": null
},
"createdAt": "example",
"environmentJson": "example",
"id": "example",
"name": "example",
"owner": "example",
"repoFile": {
"path": "example",
"url": "example"
},
"repos": [],
"updatedAt": "example",
"versionId": "example"
},
"has_more": false,
"next_cursor": null
}Get environment build
Get one of an environment's builds.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
- Build ID
build_idtextRequired - Unique identifier for the build.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"completedAt": "example",
"createdAt": "example",
"draft": false,
"environmentId": "example",
"failure": {
"code": "example",
"type": "example"
},
"id": "example",
"repoCommits": [],
"requestedRefs": [],
"snapshotState": "example",
"source": "example",
"status": "example",
"trigger": "example",
"updatedAt": "example"
},
"has_more": false,
"next_cursor": null
}Get run
Get a run's status, and when it started and finished.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
- Run ID
run_idtextRequired - Unique identifier for the run.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"agentId": "example",
"createdAt": "example",
"durationMs": 0,
"git": {
"branches": []
},
"id": "example",
"result": "example",
"status": "example",
"updatedAt": "example"
},
"has_more": false,
"next_cursor": null
}List agents
List your agents, newest first. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Limit
limitnumber - Number of agents to return.From 1 to 100.
- Cursor
cursortext - Pagination cursor from the previous response.
- Pr URL
pr_urltext - Filter agents by GitHub pull request URL.
- Include archived
include_archivedtrue/false - Whether to include archived agents.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": [],
"nextCursor": "example"
},
"has_more": false,
"next_cursor": null
}List artifacts
List the files an agent made.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": []
},
"has_more": false,
"next_cursor": null
}List environment builds
List an environment's builds, newest first. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
- Status
statustext - Only builds with this status.One of:
IN_PROGRESS,SUCCEEDED,FAILED,CANCELLED,SKIPPED. - Created after
created_afterdate and time - Only builds created at or after this time. Use an ISO 8601 timestamp with `Z` or a UTC offset and at most millisecond precision.
- Created before
created_beforedate and time - Only builds created before this time, in the same format as `createdAfter`. It must be later than `createdAfter`.
- Limit
limitnumber - Number of builds to return.From 1 to 100.
- Cursor
cursortext - Pagination cursor from `nextCursor` on the previous response. Send the same filters with it.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": [],
"nextCursor": "example"
},
"has_more": false,
"next_cursor": null
}List environment history
List the changes made to an environment, newest first. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
- Limit
limitnumber - Number of events to return.From 1 to 100.
- Cursor
cursortext - Pagination cursor from `nextCursor` on the previous response.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": [],
"nextCursor": "example"
},
"has_more": false,
"next_cursor": null
}List environments
List your saved environments, most recently changed first. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Query
querytext - Only environments whose name contains this text, ignoring case.
- Owner
ownertext - Only environments with this `owner`.One of:
personal,team. - Named
namedtrue/false - `true` for only environments with a `name`, or `false` for only environments without one.
- Repo
repolist - Only environments that include this repository. Repeat it, up to 100 times, to list environments that include any of the repositories.
- Target user ID
target_user_idtext - Only one user's personal environments, by the numeric `userId` from GET /v1/me or the `user_` ID from the Admin API's team members list. Your own ID lists your personal environments. A team admin's user API key can also pass a current team member's ID, and gets that member's personal environments that have at least one repository, all of which the admin can read. A valid ID for a user you aren't allowed to list returns `items: []` with no `nextCursor`, not an error. Combining `userId` with `owner=team` returns `400 validation_error`.
- Limit
limitnumber - Number of environments to return.From 1 to 100.
- Cursor
cursortext - Pagination cursor from the previous response. Send the same filters with each `cursor`.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": [],
"nextCursor": "example"
},
"has_more": false,
"next_cursor": null
}List models
List the models an agent can use.
Inputs
None.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": []
},
"has_more": false,
"next_cursor": null
}List repositories
List the GitHub repositories Cursor can work in.
Inputs
None.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": []
},
"has_more": false,
"next_cursor": null
}List runs
List an agent's runs, newest first. Gets one page; to see more, run it again with the next page it gives.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
- Limit
limitnumber - Limit.From 1 to 100.
- Cursor
cursortext - Pagination cursor from the previous response.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"items": [],
"nextCursor": "example"
},
"has_more": false,
"next_cursor": null
}Send follow-up
Give a running agent another instruction. It counts towards your Cursor usage.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
- Prompt
prompttextRequired - The task or follow-up instructions.
- Model
model_idtext - Choose a model, or leave empty to use your configured default.
- Mcp servers
mcp_serverslist - Inline MCP server definitions for this follow-up run. When provided, these definitions replace any create-time inline MCP servers for this run.
- Env vars
env_varsobject - Environment variables for this follow-up run only, applied while it executes. Names and values follow the `EnvVars` rules.
- Mode
modetext - Conversation mode. `plan` explores and drafts a plan before coding; `agent` implements changes directly. On follow-up runs, omit to keep the conversation's current mode; set explicitly to switch modes for that run.One of:
agent,plan. - Delivery
deliverytext - Choose steer to interrupt an active run with this prompt; leave empty to start a follow-up run. Steering accepts only the prompt, without model, mode, environment variables or MCP servers.One of:
steer.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"run": {
"agentId": "example",
"createdAt": "example",
"durationMs": 0,
"git": {
"branches": []
},
"id": "example",
"result": "example",
"status": "example",
"updatedAt": "example"
}
},
"has_more": false,
"next_cursor": null
}Start agent
Start a Cursor agent on a coding task in a repository. It runs in the cloud and counts towards your Cursor usage.
Inputs
- Prompt
prompttextRequired - The task or follow-up instructions.
- Model
model_idtext - Choose a model, or leave empty to use your configured default.
- Name
nametext - Display name for the agent. Auto-derived from the prompt when omitted.
- Agent
agent_idtext - Optional client-supplied agent identifier in `bc- ` form. Re-POSTing the same `agentId` returns `409 agent_id_conflict` instead of creating a duplicate. Cannot be combined with `envVars`; omit `agentId` so the server mints one when you need session secrets.
- Env
envobject - Env.
- Repos
reposlist - Repository configuration. Mutually exclusive with a named cloud environment. Omit both `repos` and `env` (or pass `repos: []`) to start a no-repo agent. On self-hosted targets, only a named any-repo pool takes more than one entry. `machine`, the `default` pool, and repo-backed pools take one and return `400` for more.
- Work on current branch
work_on_current_branchtrue/false - When `false` (the default), Cursor pushes commits to a new auto-generated branch (`cursor/...`) based on `repos[0].startingRef` (or the PR base ref when `prUrl` is set). When `true`, Cursor pushes directly to that starting ref , for a non-PR create, that's the branch you passed in `startingRef`; for a `prUrl` create, that's the PR's head branch.
- Auto create pr
auto_create_prtrue/false - Whether Cursor should open a pull request when the run completes.
- Skip reviewer request
skip_reviewer_requesttrue/false - Whether to skip requesting the user as a reviewer when Cursor opens a PR. Only applies when `autoCreatePR` is true.
- Env vars
env_varsobject - Session-scoped environment variables for the cloud agent. Values are encrypted at rest, injected into the agent's shell, and deleted with the agent. Names and values follow the `EnvVars` rules. Cannot be combined with a client-supplied `agentId`. Beta: `envVars` is rolling out. If it isn't enabled for your account yet, the field is silently ignored on create rather than failing the request , verify the values are present on a first run before relying on them in production.
- Mcp servers
mcp_serverslist - Inline MCP server definitions available to the initial run. Remote servers support `headers` or OAuth `auth`; stdio servers run inside the cloud agent VM and can receive `env`. Server names must be unique.
- Custom subagents
custom_subagentslist - Custom subagents the main agent can delegate to. Names must be unique and not collide with built-ins.
- Mode
modetext - Initial conversation mode for the agent's first run.One of:
agent,plan.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"agent": {
"autoCreatePR": false,
"createdAt": "example",
"customSubagents": [],
"env": {
"name": "example",
"type": "example"
},
"id": "example",
"latestRunId": "example",
"name": "example",
"repos": [],
"skipReviewerRequest": false,
"status": "example",
"updatedAt": "example",
"url": "example",
"workOnCurrentBranch": false
},
"run": {
"agentId": "example",
"createdAt": "example",
"durationMs": 0,
"git": {
"branches": []
},
"id": "example",
"result": "example",
"status": "example",
"updatedAt": "example"
}
},
"has_more": false,
"next_cursor": null
}Start environment build
Build an environment. It counts towards your Cursor usage.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
- Draft
drafttrue/false - `true` for a draft build, which agents don't start from until it's activated. A non-draft build is what agents start from once it succeeds.
- Refs
refslist - Branches to build instead of the default branches. Repositories without an entry build their default branch, and a ref that names the default branch counts as no entry. Any other branch requires `draft` set to `true`; without it, and for a repository that isn't in the environment or a second ref for the same repository, the request returns `400 validation_error`. Cursor doesn't check that the branch exists, so a missing branch fails the build, not the request.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"environmentId": "example",
"id": "example"
},
"has_more": false,
"next_cursor": null
}Unarchive agent
Bring an archived agent back, so it can be given work again.
Inputs
- Agent
agent_idtextRequired - Unique identifier for the agent.
Outputs
Result.
dataobject- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": {
"id": "example"
},
"has_more": false,
"next_cursor": null
}Update environment
Rename an environment, or change its setup or repositories.
Inputs
- Environment
environment_idtextRequired - Unique identifier for the environment.
- Name
nametext - New display name. It must differ from the names of the owner's other environments; a name the owner already uses returns `409 environment_name_conflict`.
- Environment JSON
environment_jsonobject - Replacement `environment.json`, as a JSON-encoded string, using the same schema as a `.cursor/environment.json` file. It replaces the whole configuration. An invalid configuration returns `400 validation_error`. If the environment reads its configuration from a file in its only repository, the request returns `409 repo_file_environment_locked`.
- Repos
reposlist - The environment's full list of repositories, replacing the current list. It follows the same rules as `repos` on POST /v1/environments. Send `environmentJson` with it, because a repository change saves the whole configuration; `repos` without `environmentJson` returns `400 validation_error`. To keep the current configuration, send the `environmentJson` from GET /v1/environments/{id}. Only environments with two or more repositories can change them, and they must keep at least two. Sending the current list unchanged doesn't count as a change. Otherwise an environment without repositories, a single-repository environment, or a list with fewer th
- Build settings
build_settingsobject - New values for any of the build settings GET /v1/environments/{id} returns. Fields you leave out stay unchanged, and `null` resets a field to its default.
Outputs
Result.
datanull- The complete service response; record and list fields retain their API names.
has_moretrue/false- Whether the API reports another page.
next_cursortext- Pass to the pagination field for the next page, when Has more is true.
Example output
{
"data": null,
"has_more": false,
"next_cursor": null
}