Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

update_environment

Changes an environment of a project in part; the health and the freeze have their own doors and never change here.

Change an environment by environment_id with any of name, kind, component_id, url, api_url, admin_url, branch, hosting, region, auto_deploy, protected, health_check_url, current_version and notes (HTML). A field left out keeps its value; a field sent as null is cleared. The change goes through the same action the Environments page runs and environment.updated goes out with what moved. A staff token with environment:update on the project is needed.

Requires ability

environment:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Runs the same action as

PATCH/v1/environments/{environment}

The REST endpoint and this tool share one action, so validation, permissions and events are identical.

Fires one event

environment.updated

Delivered to every endpoint subscribed to it once the change is made.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

environment_id*string

UUID of the environment.

namestringoptional

What the environment is called, 2 to 60 characters.

kindstringoptional

What the environment is for.

localdevelopmentqastaginguatpreproductionproductioncustom
component_idstringoptional

UUID of the component it runs; null when it serves the whole project.

urlstringoptional

The address people open.

api_urlstringoptional

The address the API answers on.

admin_urlstringoptional

The address of the back office.

branchstringoptional

The branch deployed there.

hostingstringoptional

Where it runs, in words.

regionstringoptional

The region it runs in.

auto_deploybooleanoptional

Whether the pipeline deploys to it without a hand.

protectedbooleanoptional

Whether a deployment needs a promotion approval.

health_check_urlstringoptional

The address the scheduled health check calls.

current_versionstringoptional

The version running there, as last recorded.

notesstringoptional

Anything the team should know, as HTML.

What it returns

{  "data": {    "id": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "component_id": "c0a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b",    "name": "Staging",    "kind": "staging",    "url": "https://staging.example.test",    "api_url": "https://api.staging.example.test",    "admin_url": null,    "branch": "develop",    "hosting": "Managed cloud, Frankfurt",    "region": "FSN1",    "auto_deploy": true,    "protected": true,    "health": "healthy",    "health_check_url": "https://staging.example.test/up",    "last_checked_at": "2026-10-28T12:00:00+00:00",    "consecutive_failures": 0,    "current_version": "web@0.3.0",    "frozen_until": null,    "frozen": false,    "notes": null,    "position": 2,    "created_at": "2026-10-28T09:20:00+00:00",    "updated_at": "2026-10-28T12:05:00+00:00"  }}

How it fails

VALIDATION_FAILED

a field outside its limits, a kind outside the list, an address that is not a URL, a component_id that is not the project's, or a name already used for the same component.

RESOURCE_NOT_FOUND

unknown environment_id, or an environment outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry environment:update.

TOKEN_MISSING_ABILITY

token lacks environment:update.

Related

get_environmentthe environment as it stands, with its health.delete_environmenttake it away.Environments APIthe same door over REST, with the freeze and the health verbs.

How is this guide?

Last updated on