One change
Environments
api/beta/environments
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
api/beta/environments Changed · +245 / -607 lines
### Headers ### Body parameters #### Response (200) ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ## Environments › Work ### Get Work Item #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Poll for Work #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Acknowledge Work #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Record Heartbeat #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Stop Work #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### List Work Items #### Path parameters #### Query parameters #### Headers #### Returns #### Example ##### Response (200) ### Update Work Item #### Path parameters #### Headers #### Body parameters #### Returns #### Example ##### Response (200) ### Get Queue Statistics #### Path parameters #### Headers #### Returns #### Example ##### Response (200) ### Header Parameters ### Body Parameters #### Response ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types # Work ## Get Work Item ### Path Parameters ### Header Parameters #### Response ## Poll for Work ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Acknowledge Work ### Path Parameters ### Header Parameters #### Response ## Record Heartbeat ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Stop Work ### Path Parameters ### Header Parameters ### Body Parameters #### Response ## List Work Items ### Path Parameters ### Query Parameters ### Header Parameters #### Response ## Update Work Item ### Path Parameters ### Header Parameters ### Body Parameters #### Response ## Get Queue Statistics ### Path Parameters ### Header Parameters #### Response ## Domain Types ### Beta Self Hosted Work ### Beta Self Hosted Work Heartbeat Response ### Beta Self Hosted Work List Response ### Beta Self Hosted Work Queue Stats ### Beta Self Hosted Work Stop Request ### Beta Self Hosted Work Update Request ### Beta Session Work Data
The two sides of this change are too far apart to line up, so this is the differ's own diff of it.
from line 1
---- -title: Environments -url: https://platform.claude.com/docs/en/api/beta/environments ---- - # Environments ## Create Environment -**post** `/v1/environments` +**POST** `/v1/environments` Create a new environment with the specified configuration. -### Header Parameters +### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 84
- `"mid-conversation-tool-changes-2026-07-01"` -### Body Parameters +### Body parameters - `name: string` Human-readable name for the environment + maxLength: 256, minLength: 1 + - `config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams or null` Environment configuration - - `BetaCloudConfigParams object { type, networking, packages }` + - `BetaCloudConfigParams object` Request params for `cloud` environment configuration.
from line 107
Environment type - - `"cloud"` - - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null` Network configuration policy. Omit on update to preserve the existing value. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 119
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + - `BetaLimitedNetworkParams object` Limited network request params.
from line 130
Network policy type - - `"limited"` - - `allow_mcp_servers: optional boolean or null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
from line 176
Package configuration type - - `"packages"` - - - `BetaSelfHostedConfigParams object { type }` + default: packages + + - `BetaSelfHostedConfigParams object` Request params for `self_hosted` environment configuration.
from line 186
Environment type - - `"self_hosted"` - - `description: optional string or null` Optional description of the environment + maxLength: 1024 + - `metadata: optional map[string]` User-provided metadata key-value pairs
from line 206
### Returns -- `BetaEnvironment object { id, archived_at, config, 7 more }` +- `BetaEnvironment object` Unified Environment resource for both cloud and self-hosted environments.
from line 222
Environment configuration (either Anthropic Cloud or self-hosted) - - `BetaCloudConfig object { networking, packages, type }` + - `BetaCloudConfig object` `cloud` environment configuration.
from line 230
Network configuration policy. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 238
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + - `BetaLimitedNetwork object` Limited network access.
from line 258
Network policy type - - `"limited"` - - `packages: BetaPackages` Package manager configuration.
from line 290
Package configuration type - - `"packages"` + default: packages - `type: "cloud"` Environment type - - `"cloud"` - - - `BetaSelfHostedConfig object { type }` + - `BetaSelfHostedConfig object` Configuration for self-hosted environments.
from line 304
Environment type - - `"self_hosted"` - - `created_at: string` RFC 3339 timestamp when environment was created
from line 324
The type of object (always 'environment') - - `"environment"` + default: environment - `updated_at: string`
from line 340
### Example -```http +```bash curl https://api.anthropic.com/v1/environments \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 368
}' ``` -#### Response +#### Response (200) ```json {
from line 419
## List Environments -**get** `/v1/environments` +**GET** `/v1/environments` List environments with pagination support. -### Query Parameters +### Query parameters - `include_archived: optional boolean` Include archived environments in the response + default: false + - `limit: optional number` Maximum number of environments to return + default: 20, maximum: 1000, minimum: 1 + - `page: optional string` Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response. -### Header Parameters +### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 537
Environment configuration (either Anthropic Cloud or self-hosted) - - `BetaCloudConfig object { networking, packages, type }` + - `BetaCloudConfig object` `cloud` environment configuration.
from line 545
Network configuration policy. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 553
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + - `BetaLimitedNetwork object` Limited network access.
from line 573
Network policy type - - `"limited"` - - `packages: BetaPackages` Package manager configuration.
from line 605
Package configuration type - - `"packages"` + default: packages - `type: "cloud"` Environment type - - `"cloud"` - - - `BetaSelfHostedConfig object { type }` + - `BetaSelfHostedConfig object` Configuration for self-hosted environments.
from line 619
Environment type - - `"self_hosted"` - - `created_at: string` RFC 3339 timestamp when environment was created
from line 639
The type of object (always 'environment') - - `"environment"` + default: environment - `updated_at: string`
from line 659
### Example -```http +```bash curl https://api.anthropic.com/v1/environments \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +#### Response (200) ```json {
from line 722
## Get Environment -**get** `/v1/environments/{environment_id}` +**GET** `/v1/environments/{environment_id}` Retrieve a specific environment by ID. -### Path Parameters +### Path parameters - `environment_id: string` -### Header Parameters +### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 810
### Returns -- `BetaEnvironment object { id, archived_at, config, 7 more }` +- `BetaEnvironment object` Unified Environment resource for both cloud and self-hosted environments.
from line 826
Environment configuration (either Anthropic Cloud or self-hosted) - - `BetaCloudConfig object { networking, packages, type }` + - `BetaCloudConfig object` `cloud` environment configuration.
from line 834
Network configuration policy. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 842
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + - `BetaLimitedNetwork object` Limited network access.
from line 862
Network policy type - - `"limited"` - - `packages: BetaPackages` Package manager configuration.
from line 894
Package configuration type - - `"packages"` + default: packages - `type: "cloud"` Environment type - - `"cloud"` - - - `BetaSelfHostedConfig object { type }` + - `BetaSelfHostedConfig object` Configuration for self-hosted environments.
from line 908
Environment type - - `"self_hosted"` - - `created_at: string` RFC 3339 timestamp when environment was created
from line 928
The type of object (always 'environment') - - `"environment"` + default: environment - `updated_at: string`
from line 944
### Example -```http +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +#### Response (200) ```json {
from line 1002
## Update Environment -**post** `/v1/environments/{environment_id}` +**POST** `/v1/environments/{environment_id}` Update an existing environment's configuration. -### Path Parameters +### Path parameters - `environment_id: string` -### Header Parameters +### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 1088
- `"mid-conversation-tool-changes-2026-07-01"` -### Body Parameters +### Body parameters - `config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams or null` Updated environment configuration - - `BetaCloudConfigParams object { type, networking, packages }` + - `BetaCloudConfigParams object` Request params for `cloud` environment configuration.
from line 1105
Environment type - - `"cloud"` - - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null` Network configuration policy. Omit on update to preserve the existing value. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 1117
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + - `BetaLimitedNetworkParams object` Limited network request params.
from line 1128
Network policy type - - `"limited"` - - `allow_mcp_servers: optional boolean or null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
from line 1174
Package configuration type - - `"packages"` - - - `BetaSelfHostedConfigParams object { type }` + default: packages + + - `BetaSelfHostedConfigParams object` Request params for `self_hosted` environment configuration.
from line 1184
Environment type - - `"self_hosted"` - - `description: optional string or null` Updated description of the environment. Omit to preserve; null clears to null; an empty string is stored as an empty string. + maxLength: 1024 + - `metadata: optional map[string]` User-provided metadata key-value pairs. Set a value to null or empty string to delete the key.
from line 1198
Updated name for the environment + maxLength: 256, minLength: 1 + - `scope: optional "organization" or "account" or null` The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only.
from line 1210
### Returns -- `BetaEnvironment object { id, archived_at, config, 7 more }` +- `BetaEnvironment object` Unified Environment resource for both cloud and self-hosted environments.
from line 1226
Environment configuration (either Anthropic Cloud or self-hosted) - - `BetaCloudConfig object { networking, packages, type }` + - `BetaCloudConfig object` `cloud` environment configuration.
from line 1234
Network configuration policy. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 1242
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + - `BetaLimitedNetwork object` Limited network access.
from line 1262
Network policy type - - `"limited"` - - `packages: BetaPackages` Package manager configuration.
from line 1294
Package configuration type - - `"packages"` + default: packages - `type: "cloud"` Environment type - - `"cloud"` - - - `BetaSelfHostedConfig object { type }` + - `BetaSelfHostedConfig object` Configuration for self-hosted environments.
from line 1308
Environment type - - `"self_hosted"` - - `created_at: string` RFC 3339 timestamp when environment was created
from line 1328
The type of object (always 'environment') - - `"environment"` + default: environment - `updated_at: string`
from line 1344
### Example -```http +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 1355
}' ``` -#### Response +#### Response (200) ```json {
from line 1406
## Delete Environment -**delete** `/v1/environments/{environment_id}` +**DELETE** `/v1/environments/{environment_id}` Delete an environment by ID. Returns a confirmation of the deletion. -### Path Parameters +### Path parameters - `environment_id: string` -### Header Parameters +### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 1494
### Returns -- `BetaEnvironmentDeleteResponse object { id, type }` +- `BetaEnvironmentDeleteResponse object` Response after deleting an environment.
from line 1506
The type of response - - `"environment_deleted"` + default: environment_deleted ### Example -```http +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \ -X DELETE \ -H 'anthropic-version: 2023-06-01' \
from line 1518
-H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +#### Response (200) ```json {
from line 1529
## Archive Environment -**post** `/v1/environments/{environment_id}/archive` +**POST** `/v1/environments/{environment_id}/archive` Archive an environment by ID. Archived environments cannot be used to create new sessions. -### Path Parameters +### Path parameters - `environment_id: string` -### Header Parameters +### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 1617
### Returns -- `BetaEnvironment object { id, archived_at, config, 7 more }` +- `BetaEnvironment object` Unified Environment resource for both cloud and self-hosted environments.
from line 1633
Environment configuration (either Anthropic Cloud or self-hosted) - - `BetaCloudConfig object { networking, packages, type }` + - `BetaCloudConfig object` `cloud` environment configuration.
from line 1641
Network configuration policy. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 1649
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + - `BetaLimitedNetwork object` Limited network access.
from line 1669
Network policy type - - `"limited"` - - `packages: BetaPackages` Package manager configuration.
from line 1701
Package configuration type - - `"packages"` + default: packages - `type: "cloud"` Environment type - - `"cloud"` - - - `BetaSelfHostedConfig object { type }` + - `BetaSelfHostedConfig object` Configuration for self-hosted environments.
from line 1715
Environment type - - `"self_hosted"` - - `created_at: string` RFC 3339 timestamp when environment was created
from line 1735
The type of object (always 'environment') - - `"environment"` + default: environment - `updated_at: string`
from line 1751
### Example -```http +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive \ -X POST \ -H 'anthropic-version: 2023-06-01' \
from line 1759
-H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +#### Response (200) ```json {
from line 1808
} ``` -## Domain Types +## Domain types ### Beta Cloud Config -- `BetaCloudConfig object { networking, packages, type }` +- `BetaCloudConfig object` `cloud` environment configuration.
from line 1820
Network configuration policy. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 1828
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + - `BetaLimitedNetwork object` Limited network access.
from line 1848
Network policy type - - `"limited"` - - `packages: BetaPackages` Package manager configuration.
from line 1880
Package configuration type - - `"packages"` + default: packages - `type: "cloud"` Environment type - - `"cloud"` - ### Beta Cloud Config Params -- `BetaCloudConfigParams object { type, networking, packages }` +- `BetaCloudConfigParams object` Request params for `cloud` environment configuration.
from line 1899
Environment type - - `"cloud"` - - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null` Network configuration policy. Omit on update to preserve the existing value. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 1911
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` + - `BetaLimitedNetworkParams object` Limited network request params.
from line 1922
Network policy type - - `"limited"` - - `allow_mcp_servers: optional boolean or null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
from line 1968
Package configuration type - - `"packages"` + default: packages ### Beta Environment -- `BetaEnvironment object { id, archived_at, config, 7 more }` +- `BetaEnvironment object` Unified Environment resource for both cloud and self-hosted environments.
from line 1988
Environment configuration (either Anthropic Cloud or self-hosted) - - `BetaCloudConfig object { networking, packages, type }` + - `BetaCloudConfig object` `cloud` environment configuration.
from line 1996
Network configuration policy. - - `BetaUnrestrictedNetwork object { type }` + - `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 2004
Network policy type - - `"unrestricted"` - - - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` + - `BetaLimitedNetwork object` Limited network access.
from line 2024
Network policy type - - `"limited"` - - `packages: BetaPackages` Package manager configuration.
from line 2056
Package configuration type - - `"packages"` + default: packages - `type: "cloud"` Environment type - - `"cloud"` - - - `BetaSelfHostedConfig object { type }` + - `BetaSelfHostedConfig object` Configuration for self-hosted environments.
from line 2070
Environment type - - `"self_hosted"` - - `created_at: string` RFC 3339 timestamp when environment was created
from line 2090
The type of object (always 'environment') - - `"environment"` + default: environment - `updated_at: string`
from line 2106
### Beta Environment Delete Response -- `BetaEnvironmentDeleteResponse object { id, type }` +- `BetaEnvironmentDeleteResponse object` Response after deleting an environment.
from line 2118
The type of response - - `"environment_deleted"` + default: environment_deleted ### Beta Limited Network -- `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }` +- `BetaLimitedNetwork object` Limited network access.
from line 2142
Network policy type - - `"limited"` - ### Beta Limited Network Params -- `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }` +- `BetaLimitedNetworkParams object` Limited network request params.
from line 2155
Network policy type - - `"limited"` - - `allow_mcp_servers: optional boolean or null` Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
from line 2169
### Beta Packages -- `BetaPackages object { apt, cargo, gem, 4 more }` +- `BetaPackages object` Packages (and their versions) available in this environment.
from line 2201
Package configuration type - - `"packages"` + default: packages ### Beta Packages Params -- `BetaPackagesParams object { apt, cargo, gem, 4 more }` +- `BetaPackagesParams object` Specify packages (and optionally their versions) available in this environment.
from line 2239
Package configuration type - - `"packages"` + default: packages ### Beta Self Hosted Config -- `BetaSelfHostedConfig object { type }` +- `BetaSelfHostedConfig object` Configuration for self-hosted environments.
from line 2251
Environment type - - `"self_hosted"` - ### Beta Self Hosted Config Params -- `BetaSelfHostedConfigParams object { type }` +- `BetaSelfHostedConfigParams object` Request params for `self_hosted` environment configuration.
from line 2261
Environment type - - `"self_hosted"` - ### Beta Unrestricted Network -- `BetaUnrestrictedNetwork object { type }` +- `BetaUnrestrictedNetwork object` Unrestricted network access.
from line 2271
Network policy type - - `"unrestricted"` - -# Work - -## Get Work Item - -**get** `/v1/environments/{environment_id}/work/{work_id}` +## Environments › Work + +### Get Work Item + +**GET** `/v1/environments/{environment_id}/work/{work_id}` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Retrieve detailed information about a specific work item. -### Path Parameters +#### Path parameters - `environment_id: string` - `work_id: string` -### Header Parameters +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 2365
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns - -- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }` +#### Returns + +- `BetaSelfHostedWork object` Work resource representing a unit of work in a self-hosted environment.
from line 2399
Type of work data - - `"session"` - - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`)
from line 2445
The type of object (always 'work') - - `"work"` - -### Example - -```http + default: work + +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +##### Response (200) ```json {
from line 2481
} ``` -## Poll for Work - -**get** `/v1/environments/{environment_id}/work/poll` +### Poll for Work + +**GET** `/v1/environments/{environment_id}/work/poll` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Long poll for work items in the queue. -### Path Parameters +#### Path parameters - `environment_id: string` -### Query Parameters +#### Query parameters - `block_ms: optional number` How long to wait for work to arrive before returning. Must be 1-999 in milliseconds. Defaults to non-blocking (returns immediately if no work is available). + minimum: 1 + - `reclaim_older_than_ms: optional number` Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms). -### Header Parameters + minimum: 1 + +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 2589
Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console -### Returns - -- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }` +#### Returns + +- `BetaSelfHostedWork object` Work resource representing a unit of work in a self-hosted environment.
from line 2623
Type of work data - - `"session"` - - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`)
from line 2669
The type of object (always 'work') - - `"work"` - -### Example - -```http + default: work + +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/poll \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +##### Response (200) ```json {
from line 2705
} ``` -## Acknowledge Work - -**post** `/v1/environments/{environment_id}/work/{work_id}/ack` +### Acknowledge Work + +**POST** `/v1/environments/{environment_id}/work/{work_id}/ack` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue. -### Path Parameters +#### Path parameters - `environment_id: string` - `work_id: string` -### Header Parameters +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 2797
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns - -- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }` +#### Returns + +- `BetaSelfHostedWork object` Work resource representing a unit of work in a self-hosted environment.
from line 2831
Type of work data - - `"session"` - - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`)
from line 2877
The type of object (always 'work') - - `"work"` - -### Example - -```http + default: work + +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/ack \ -X POST \ -H 'anthropic-version: 2023-06-01' \
from line 2889
-H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +##### Response (200) ```json {
from line 2914
} ``` -## Record Heartbeat - -**post** `/v1/environments/{environment_id}/work/{work_id}/heartbeat` +### Record Heartbeat + +**POST** `/v1/environments/{environment_id}/work/{work_id}/heartbeat` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Record a heartbeat for a work item to maintain the lease. -### Path Parameters +#### Path parameters - `environment_id: string` - `work_id: string` -### Query Parameters +#### Query parameters - `desired_ttl_seconds: optional number`
from line 2938
Expected last_heartbeat for conditional update (optimistic concurrency). Use literal 'NO_HEARTBEAT' to claim an unclaimed lease (first heartbeat). For subsequent heartbeats, echo the server's previous last_heartbeat value exactly. Returns 412 Precondition Failed if the actual value doesn't match. -### Header Parameters +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 3016
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns - -- `BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }` +#### Returns + +- `BetaSelfHostedWorkHeartbeatResponse object` Response after recording a heartbeat for a work item.
from line 3052
The type of response - - `"work_heartbeat"` - -### Example - -```http + default: work_heartbeat + +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/heartbeat \ -X POST \ -H 'anthropic-version: 2023-06-01' \
from line 3064
-H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +##### Response (200) ```json {
from line 3076
} ``` -## Stop Work - -**post** `/v1/environments/{environment_id}/work/{work_id}/stop` +### Stop Work + +**POST** `/v1/environments/{environment_id}/work/{work_id}/stop` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Stop a work item, initiating graceful or forced shutdown. -### Path Parameters +#### Path parameters - `environment_id: string` - `work_id: string` -### Header Parameters +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 3168
- `"mid-conversation-tool-changes-2026-07-01"` -### Body Parameters +#### Body parameters - `force: optional boolean` If true, immediately stop work without graceful shutdown -### Returns - -- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }` + default: false + +#### Returns + +- `BetaSelfHostedWork object` Work resource representing a unit of work in a self-hosted environment.
from line 3210
Type of work data - - `"session"` - - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`)
from line 3256
The type of object (always 'work') - - `"work"` - -### Example - -```http + default: work + +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/stop \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 3269
-d '{}' ``` -#### Response +##### Response (200) ```json {
from line 3294
} ``` -## List Work Items - -**get** `/v1/environments/{environment_id}/work` +### List Work Items + +**GET** `/v1/environments/{environment_id}/work` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. List work items in an environment. -### Path Parameters +#### Path parameters - `environment_id: string` -### Query Parameters +#### Query parameters - `limit: optional number` Maximum number of work items to return + default: 20, maximum: 1000, minimum: 1 + - `page: optional string` Opaque cursor from previous response for pagination -### Header Parameters +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 3396
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns - -- `BetaSelfHostedWorkListResponse object { data, next_page }` +#### Returns + +- `BetaSelfHostedWorkListResponse object` Response when listing work items with cursor-based pagination.
from line 3430
Type of work data - - `"session"` - - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`)
from line 3476
The type of object (always 'work') - - `"work"` + default: work - `next_page: string or null` Opaque cursor for fetching the next page of results -### Example - -```http +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +##### Response (200) ```json {
from line 3521
} ``` -## Update Work Item - -**post** `/v1/environments/{environment_id}/work/{work_id}` +### Update Work Item + +**POST** `/v1/environments/{environment_id}/work/{work_id}` Note: these endpoints are called automatically by the pre-built environment worker provided in the SDKs and CLI, for orchestrating sessions with self-hosted sandbox environments. They are included here as a reference; you do not need to invoke them directly. Update work item metadata with merge semantics. -### Path Parameters +#### Path parameters - `environment_id: string` - `work_id: string` -### Header Parameters +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 3613
- `"mid-conversation-tool-changes-2026-07-01"` -### Body Parameters +#### Body parameters - `metadata: map[string]` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata. -### Returns - -- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }` +#### Returns + +- `BetaSelfHostedWork object` Work resource representing a unit of work in a self-hosted environment.
from line 3653
Type of work data - - `"session"` - - `environment_id: string` Environment identifier this work belongs to (e.g., `env_...`)
from line 3699
The type of object (always 'work') - - `"work"` - -### Example - -```http + default: work + +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \ -H 'Content-Type: application/json' \ -H 'anthropic-version: 2023-06-01' \
from line 3716
}' ``` -#### Response +##### Response (200) ```json {
from line 3741
} ``` -## Get Queue Statistics - -**get** `/v1/environments/{environment_id}/work/stats` +### Get Queue Statistics + +**GET** `/v1/environments/{environment_id}/work/stats` Get statistics about the work queue for an environment. -### Path Parameters +#### Path parameters - `environment_id: string` -### Header Parameters +#### Headers - `"anthropic-beta": optional array of AnthropicBeta`
from line 3829
- `"mid-conversation-tool-changes-2026-07-01"` -### Returns - -- `BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }` +#### Returns + +- `BetaSelfHostedWorkQueueStats object` Statistics about the work queue for an environment.
from line 3849
Number of work items being processed (polled but not acknowledged) + default: 0 + - `type: "work_queue_stats"` The type of object - - `"work_queue_stats"` + default: work_queue_stats - `workers_polling: number or null` Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests. -### Example - -```http +#### Example + +```bash curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/stats \ -H 'anthropic-version: 2023-06-01' \ -H 'anthropic-beta: managed-agents-2026-04-01' \ -H "X-Api-Key: $ANTHROPIC_API_KEY" ``` -#### Response +##### Response (200) ```json {
from line 3881
"workers_polling": 0 } ``` - -## Domain Types - -### Beta Self Hosted Work - -- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }` - - Work resource representing a unit of work in a self-hosted environment. - - Work items are queued when sessions are created or when long-dormant sessions - receive new messages. The environment worker polls for work to execute in a - self-hosted sandbox. - - - `id: string` - - Work identifier (e.g., 'work_...') - - - `acknowledged_at: string or null` - - RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - - - `created_at: string` - - RFC 3339 timestamp when work was created - - - `data: BetaSessionWorkData` - - The actual work to be performed - - - `id: string` - - Session identifier (e.g., 'session_...') - - - `type: "session"` - - Type of work data - - - `"session"` - - - `environment_id: string` - - Environment identifier this work belongs to (e.g., `env_...`) - - - `latest_heartbeat_at: string or null` - - RFC 3339 timestamp of the most recent heartbeat - - - `metadata: map[string]` - - User-provided metadata key-value pairs associated with this work item - - - `secret: string or null` - - Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - - - `started_at: string or null` - - RFC 3339 timestamp when work execution started - - - `state: "queued" or "starting" or "active" or 2 more` - - Current state of the work item - - - `"queued"` - - - `"starting"` - - - `"active"` - - - `"stopping"` - - - `"stopped"` - - - `stop_requested_at: string or null` - - RFC 3339 timestamp when stop was requested - - - `stopped_at: string or null` - - RFC 3339 timestamp when work execution stopped - - - `type: "work"` - - The type of object (always 'work') - - - `"work"` - -### Beta Self Hosted Work Heartbeat Response - -- `BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }` - - Response after recording a heartbeat for a work item. - - - `last_heartbeat: string` - - RFC 3339 timestamp of the actual heartbeat from DB - - - `lease_extended: boolean` - - Whether the heartbeat succeeded in extending the lease - - - `state: "queued" or "starting" or "active" or 2 more` - - Current state of the work item (active/stopping/stopped) - - - `"queued"` - - - `"starting"` - - - `"active"` - - - `"stopping"` - - - `"stopped"` - - - `ttl_seconds: number` - - Effective TTL applied to the lease - - - `type: "work_heartbeat"` - - The type of response - - - `"work_heartbeat"` - -### Beta Self Hosted Work List Response - -- `BetaSelfHostedWorkListResponse object { data, next_page }` - - Response when listing work items with cursor-based pagination. - - - `data: array of BetaSelfHostedWork` - - List of work items - - - `id: string` - - Work identifier (e.g., 'work_...') - - - `acknowledged_at: string or null` - - RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox - - - `created_at: string` - - RFC 3339 timestamp when work was created - - - `data: BetaSessionWorkData` - - The actual work to be performed - - - `id: string` - - Session identifier (e.g., 'session_...') - - - `type: "session"` - - Type of work data - - - `"session"` - - - `environment_id: string` - - Environment identifier this work belongs to (e.g., `env_...`) - - - `latest_heartbeat_at: string or null` - - RFC 3339 timestamp of the most recent heartbeat - - - `metadata: map[string]` - - User-provided metadata key-value pairs associated with this work item - - - `secret: string or null` - - Credential payload used by the environment worker to execute this work item. May be populated when polling for work; null on all other retrieval paths. - - - `started_at: string or null` - - RFC 3339 timestamp when work execution started - - - `state: "queued" or "starting" or "active" or 2 more` - - Current state of the work item - - - `"queued"` - - - `"starting"` - - - `"active"` - - - `"stopping"` - - - `"stopped"` - - - `stop_requested_at: string or null` - - RFC 3339 timestamp when stop was requested - - - `stopped_at: string or null` - - RFC 3339 timestamp when work execution stopped - - - `type: "work"` - - The type of object (always 'work') - - - `"work"` - - - `next_page: string or null` - - Opaque cursor for fetching the next page of results - -### Beta Self Hosted Work Queue Stats - -- `BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }` - - Statistics about the work queue for an environment. - - Uses Redis Stream consumer group metrics for O(1) queries. - - - `depth: number` - - Number of work items waiting to be picked up (lag from consumer group) - - - `oldest_queued_at: string or null` - - RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty - - - `pending: number` - - Number of work items being processed (polled but not acknowledged) - - - `type: "work_queue_stats"` - - The type of object - - - `"work_queue_stats"` - - - `workers_polling: number or null` - - Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests. - -### Beta Self Hosted Work Stop Request - -- `BetaSelfHostedWorkStopRequest object { force }` - - Request to stop a work item. - - - `force: optional boolean` - - If true, immediately stop work without graceful shutdown - -### Beta Self Hosted Work Update Request - -- `BetaSelfHostedWorkUpdateRequest object { metadata }` - - Request to update work item metadata. - - - `metadata: map[string]` - - Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata. - -### Beta Session Work Data - -- `BetaSessionWorkData object { id, type }` - - Work data for session work items. - - This resource type is used when work represents a session that needs to be executed - in a self-hosted environment. - - - `id: string` - - Session identifier (e.g., 'session_...') - - - `type: "session"` - - Type of work data - - - `"session"`