Cloud Agent Environments API

It is the part of the Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. API v1 that manages environments: the repositories and environment.json configuration an agent runs in, which you would otherwise edit in the Cloud Agents dashboard. Cursor announced it in beta in its October 16, 2026 changelog, in the same entry that raised environments to up to 300 repositories and said large environments load 5x faster.

The whole Cloud AgentsAgents that run in a Cursor-managed virtual machine, check out the repo, do the work and open a pull request, then shut down, with no load on your laptop. Press Enter for the full definition. API v1 is in public beta, and Cursor says APIs may change before general availability. So treat anything you build on it as something you will revisit, probably sooner than a stable integration. Authentication is the same as the rest of the API: Basic or Bearer, with a user API key from the dashboard or a service account API key.

Create takes four required fields: owner (personal or team), a name of up to 255 characters, a repos array of { url } entries, and environmentJson, the environment's environment.json sent as a JSON-encoded string with the same schema as a .cursor/environment.json file. A name the owner already uses returns 409 environment_name_conflict, and a repository Cursor cannot reach through your source control integration returns 400 repository_access.

curl --request POST \
  --url https://api.cursor.com/v1/environments \
  -u YOUR_API_KEY: \
  --header 'Content-Type: application/json' \
  --data '{
    "owner": "team",
    "name": "Web app",
    "repos": [
      { "url": "https://github.com/your-org/your-web-app" },
      { "url": "https://github.com/your-org/your-api" }
    ],
    "environmentJson": "{\"install\": \"pnpm install\", \"start\": \"sudo service docker start\"}"
  }'

On repository counts the two sources do not quite agree. The changelog says environments support up to 300 repositories, while the API reference lists a maximum of 500 in the create request body. I would plan around the lower figure until Cursor reconciles them, since that is the one it announced.

Update is a PATCH, and every field it sends is applied together, so either all of them change or none do. The part that catches people is repos: it replaces the whole list, and it must travel with environmentJson, because a repository change saves the whole configuration. To keep the current configuration, read it from Get An Environment and send it back unchanged.

Repository edits are also narrower than they look. Only environments with two or more repositories can change them, and they must keep at least two. An environment with no repositories cannot add any, and a single-repository environment cannot swap its one repository; both return 409 environment_repo_edit_blocked, and Cursor's answer is to create a new environment. When an environment reads its configuration from a file in a repository, repoFile shows where, that repository has to stay in the list, and an environment whose only repository holds the file is locked to it.

Each environment carries buildSettings with three fields, and you change them in a PATCH of their own: a request that also sends name, environmentJson or repos returns 400 validation_error. Sending null resets a field to its default.

Starting a Build with POST /v1/environments/{id}/builds is the API version of Trigger build in the dashboard. With no body it builds every repository's default branch. Set draft: true for a Build agents do not start from until it is activated, and only a draft can name other branches through refs. Service account API keys get 403 key_not_supported on this endpoint, and on a team that limits environment edits to admins, members can start drafts but only admins can start non-draft Builds.

One error deserves its own rule in your client. A 503 upstream_error means Cursor could not confirm whether the Build started, and the docs say not to retry automatically because another request can start a second Build. Check List Environment Builds first. To see what a new agent will actually boot from, GET /builds/active returns either a buildId or universal_image, Cursor's default image.

A failed Build reports failure.type as INSTALL_FAILED or TERMINAL_FAILURE, often with a code such as environment_json_invalid. Cursor says it can add codes over time, so a client should treat an unrecognized code as a generic failure. Cloud Agent BuildsPrepared Cloud Agent environments built in the background, with the last successful build kept active when a newer build fails. Press Enter for the full definition. covers what a Build prepares and how fallback to the last successful one works.

Environment secrets are the environment variables Cursor gives cloud agents, the same values as the Secrets tab in the dashboard, and no API response ever includes a value. You list them with GET /v1/environments/{id}/secrets, set them with PUT .../secrets/{name}, and delete one version with DELETE. One name can hold several versions, each for different repositories, and each version has its own id.

Precedence is the rule worth writing down somewhere your team will see it. An agent gets the value from the most specific place: values passed when the agent starts, then the environment's secrets, then the user's personal secrets, then the team's. Changes reach agents that start afterward, and agents that start from a Build only see them once a newer Build of their environment finishes.

Every set or delete is recorded as a cloud_agent_secret event with the name and repositories but not the value, the same as a change made in the dashboard. Cloud Agent settings explains where those secrets sit among the other dashboard controls.

Visibility depends on the key. Team admins and service account API keys see every team environment; other callers see a team environment only when they can access all of its repositories. A service account key limited to specific repositories lists only environments whose repositories all fall inside that limit. Drafts and deleted environments are never listed.

Paging has a quirk that will, I suspect, bite anyone who writes a sync job. The list is ordered by last update, so an environment that changes mid-walk jumps to the front, and a later page can skip it and repeat another. For non-admin callers, repository access checks can also time out, leaving out team environments that show up on later requests. Keep requesting until nextCursor is absent (it is omitted, not null).

For auditing, GET /v1/environments/{id}/history returns the same events as the History tab. Each event has a kind (created, updated, deleted, backfilled or changed), a source such as dashboard, api or agent_run, a current flag for the event that saved the active configuration, and the environmentJson it saved. Delete, by contrast, is permanent and irreversible.