Agents
Cloud Agent Environments API
The Environments API lets you script the environments Cloud Agents run in, the same work you would otherwise do in the Cloud Agents dashboard. It creates, lists, updates and deletes environments, reads their history, starts and inspects Builds, and manages environment secrets under /v1/environments. It has been in beta since October 16, 2026.

On this page
What is the 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 saved environments: the repositories and environment.json configuration an agent runs in. Cursor launched it in beta in its October 16, 2026 changelog. The same entry said environments now support up to 300 repositories and that 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 its APIs may change before general availability, so plan to revisit any client you build on it. Authentication works as it does for the rest of the API: Basic or Bearer, with a user API key from the dashboard or a service account API key.
- Method
- POST
- Path
/v1/environments- What it does
- Create an environment (returns
201)
- Method
- GET
- Path
/v1/environments- What it does
- List environments, most recently updated first
- Method
- GET
- Path
/v1/environments/{id}- What it does
- Get one environment with its configuration and build settings
- Method
- PATCH
- Path
/v1/environments/{id}- What it does
- Rename, replace configuration or repositories, or change build settings (returns
204)
- Method
- DELETE
- Path
/v1/environments/{id}- What it does
- Permanently delete an environment
- Method
- GET
- Path
/v1/environments/{id}/history- What it does
- List changes, newest first
- Method
- GET / POST
- Path
/v1/environments/{id}/builds- What it does
- List Builds, or start one (returns
202)
- Method
- GET
- Path
/v1/environments/{id}/builds/{buildId}- What it does
- Get one Build
- Method
- GET
- Path
/v1/environments/{id}/builds/active- What it does
- What a new agent boots from
- Method
- GET
- Path
/v1/environments/{id}/secrets- What it does
- List the environment's secrets, without values
- Method
- PUT / DELETE
- Path
/v1/environments/{id}/secrets/{name}- What it does
- Set a secret, or delete one version of it
| Method | Path | What it does |
|---|---|---|
| POST | /v1/environments | Create an environment (returns 201) |
| GET | /v1/environments | List environments, most recently updated first |
| GET | /v1/environments/{id} | Get one environment with its configuration and build settings |
| PATCH | /v1/environments/{id} | Rename, replace configuration or repositories, or change build settings (returns 204) |
| DELETE | /v1/environments/{id} | Permanently delete an environment |
| GET | /v1/environments/{id}/history | List changes, newest first |
| GET / POST | /v1/environments/{id}/builds | List Builds, or start one (returns 202) |
| GET | /v1/environments/{id}/builds/{buildId} | Get one Build |
| GET | /v1/environments/{id}/builds/active | What a new agent boots from |
| GET | /v1/environments/{id}/secrets | List the environment's secrets, without values |
| PUT / DELETE | /v1/environments/{id}/secrets/{name} | Set a secret, or delete one version of it |
Cursor docs: Cloud Agents API endpoints, Environments and Secrets sections, checked October 28, 2026.
This is covered hands-on in Agent Mode Foundations — 6 short Units, free to read.
Rather do it than read about it? Run 11 interactive Cursor walkthroughs in a simulated editor. Free, no account needed.
How do you create and update an environment through the API?
Create takes four required fields. owner is personal or team, name holds up to 255 characters, and repos is an array of { url } entries. environmentJson is 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 can't 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\"}" }'
Cursor's two sources disagree on repository counts. The changelog says environments support up to 300 repositories, while the API reference lists a maximum of 500 in the create request body. Until Cursor reconciles them, we suggest planning around 300, the figure it announced.
Update is a PATCH, and it applies every field it sends together, so either all of them change or none do. Take care with 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 have tight limits. Only environments with two or more repositories can change them, and they must keep at least two. An environment with no repositories can't add any, and a single-repository environment can't change its repository. Both cases return 409 environment_repo_edit_blocked, and Cursor's answer is to create a new environment.
An environment can also read its configuration from a file in one of its repositories. Get An Environment then shows that file in repoFile, and its repository has to stay in the list. If that repository is the environment's only one, the environment is locked to the file.
How do Builds and build settings work through the API?
Each environment carries buildSettings with three fields. Change them in a PATCH of their own, because a request that also sends name, environmentJson or repos returns 400 validation_error. Sending null resets a field to its default.
- pullLatestCode
when_stale(default) ornever.alwaysis a legacy value you can read but not set.- stalenessThresholdHours
- 0 to 8,760.
0pulls on every start. Default 24. - installTimeoutMinutes
- 5 to 300 for the install step. Default 90.
Get An Environment response fields, Cursor docs.
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 that agents don't start from until it's activated. Only a draft can name other branches through refs.
Not every key can start a Build. An API key limited to certain repositories can't, and neither can a user-scoped token it minted. Those get 404 environment_not_found when the environment has no repositories or any repository outside the limit, and 403 key_not_supported otherwise. A team service account key with no repository limit can start Builds of its own team's environments if it has the agent scope. On a team that limits environment edits to admins, members can start drafts, but only admins can start non-draft Builds.
Give one error its own rule in your client. A 503 upstream_error means Cursor couldn't confirm whether the Build started. The docs say not to retry automatically, because another request can start a second Build, so check List Environment Builds first.
To see what a new agent will boot from, call GET /builds/active. Its type is build, with a buildId, when the agent starts from a Build, and universal_image when it starts on Cursor's default image.
A failed Build reports failure.type as INSTALL_FAILED or TERMINAL_FAILURE. When present, failure.code names the cause, such as environment_json_invalid. Cursor can add codes over time, so treat a code you don't recognize 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.
How do environment secrets work through the API?
Environment secrets are the environment variables Cursor gives cloud agents, the same values as the Secrets tab in the dashboard, and no API response includes a value. You list them with GET /v1/environments/{id}/secrets, set one with PUT .../secrets/{name}, and delete one version with DELETE. A name can hold several versions, each for different repositories, and each version has its own id.
When one name is set in several places, an agent gets the most specific value: 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. Agents that start from a Build see a change only once a newer Build of their environment finishes.
Build Secrets can't be set through the API yet: type: "build_secret" returns 400 validation_error. DELETE still removes one.
An environment holds at most 1,000 secrets. Names containing CURSOR_SANDBOX are reserved, as are HTTP_PROXY, HTTPS_PROXY and ALL_PROXY in any letter case.
When the team lets only admins change secrets, everyone else gets 403 team_admin_required, service account API keys included.
Every set or delete is recorded as a cloud_agent_secret event with the secret's name and repositories but not its value, the same as a change made in the dashboard. Cloud Agent settings explains where those secrets sit among the other dashboard controls.
Who can see which environments, and how do you audit changes?
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, and any user-scoped token minted with it, lists only environments that have repositories, all inside that limit. Drafts and deleted environments are never listed.
A sync job that walks the list has to handle two quirks. 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 callers other than team admins and service account keys, repository access checks can also time out. A page can then leave out team environments, or stop before the end of the list, and those environments appear 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) and a source such as dashboard, api or agent_run. It also carries a current flag for the event that saved the active configuration, and the environmentJson it saved. Deleting an environment can't be undone.
Frequently asked questions
Is the Cursor Environments API generally available?
No. Cursor's October 16, 2026 changelog launched it in beta, and the Cloud Agents API v1 it belongs to is in public beta, so endpoints may change before general availability.
How many repositories can a Cloud Agent environment have?
The changelog says up to 300 repositories. The API reference lists a maximum of 500 in the create request body, so plan around 300 until Cursor reconciles the two figures.
Can I change an environment's repositories through the API?
Only in environments with two or more repositories, and they must keep at least two. Send the full repository list together with the environment's configuration. Environments with no repositories or a single repository return a conflict error and can't change them.
Can a service account API key start a Build?
Yes, for its own team's environments, if it is a team service account key with no repository limit and the agent scope. A key limited to certain repositories can't start Builds, and neither can a user-scoped token it minted.
Does the API return secret values?
No. Secrets endpoints return names, types, repositories and version IDs, never values. Build Secrets can't be set through the API yet, though they can be deleted.
Sources & last verified
- Cursor docs: Cloud Agents API endpoints
- Cursor changelog: Cloud Agent Canvases and Environment Improvements
- Cursor docs: Cloud Agent setup
- Cursor docs: Cloud Agent Builds
- Cursor docs: API overview
Cursor ships frequently. Facts verified against primary sources on October 28, 2026.