Update an environment

Update an environment by replacing its whole configuration.

PUT /api/v2/environments/{id}

Python

from hai_agents import Client

client = Client()

environment = client.environments.update_environment(
    "wide-browser",
    request={
        "kind": "web",
        "id": "wide-browser",
        "start_url": "https://example.com",
        "mode": {"type": "visual", "width": 1920, "height": 1080, "markdown": True},
        "vault_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    },
)
print(environment.mode)

200

{
  "id": "wide-browser",
  "kind": "web",
  "host": "cloud",
  "start_url": "https://example.com",
  "headless": false,
  "session_id": null,
  "mode": {"type": "visual", "width": 1920, "height": 1080, "markdown": true},
  "lazy": false,
  "settle_s": 1.0,
  "vault_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "browser_profile_id": null,
  "use_default_browser_profile": false,
  "persist_browser_profile": false,
  "network": null
}

Behavior

The id can’t change. To change a few fields, patch the environment.

Path parameters

id · string · required

The environment’s id, for example wide-browser or myorg/wide-browser.

Request body

The full environment, with the same fields as Create an environment. The id must equal the URL identifier. Omitted fields reset to their defaults. That includes vault_id: omitting it unbinds any attached vault.

Response

200 with the updated environment object.

Python

from hai_agents import Client

client = Client()

environment = client.environments.update_environment(
    "wide-browser",
    request={
        "kind": "web",
        "id": "wide-browser",
        "start_url": "https://example.com",
        "mode": {"type": "visual", "width": 1920, "height": 1080, "markdown": True},
        "vault_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    },
)
print(environment.mode)

200

{
  "id": "wide-browser",
  "kind": "web",
  "host": "cloud",
  "start_url": "https://example.com",
  "headless": false,
  "session_id": null,
  "mode": {"type": "visual", "width": 1920, "height": 1080, "markdown": true},
  "lazy": false,
  "settle_s": 1.0,
  "vault_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "browser_profile_id": null,
  "use_default_browser_profile": false,
  "persist_browser_profile": false,
  "network": null
}

Errors

Status	Cause
400	The id in the body does not match the URL identifier.
403	The environment is reserved (h/) and read-only.
404	Not found, or not in your organization.
422	Body failed validation. Common cases: invalid id shape, missing required field.