One read of Claude Developer Platformapi-20260825T033708Z
377 pages moved out of 612 read.
Pages moved
377
significant first
Pages read
612
in this capture
Captured
03:37 UTC
Corpus hash
7d98cae5bb87
corpus-hash
What this read moved
151-175 of 377, page 7 of 16This capture is too large to show at once. Changes 151-175 of 377 are below, significant first; the rest are on the following screens.
api/beta/deployments/retrieve Changed · +91 / -142 lines
# Get Deployment ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Deployment
3url: https://platform.claude.com/docs/en/api/beta/deployments/retrieve
4---
1# Get Deployment
52
6## Get Deployment
3**GET** `/v1/deployments/{deployment_id}`
74
8**get** `/v1/deployments/{deployment_id}`
9
105Get Deployment
116
12### Path Parameters
7## Path parameters
138
149- `deployment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
91- `BetaManagedAgentsDeployment object`
9792
9893 A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.
9994
from line 104
109104
110105 - `type: "agent"`
111106
112 - `"agent"`
113
114107 - `version: number`
115108
109 format: int32
110
116111 - `archived_at: string or null`
117112
118113 A timestamp in RFC 3339 format
119114
115 format: date-time
116
120117 - `created_at: string`
121118
122119 A timestamp in RFC 3339 format
123120
121 format: date-time
122
124123 - `description: string or null`
125124
126125 Description of what the deployment does.
from line 132
133132
134133 Events sent to each session immediately after creation.
135134
136 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
135 - `BetaManagedAgentsDeploymentUserMessageEvent object`
137136
138137 A user message sent to the session.
139138
from line 140
141140
142141 Array of content blocks for the user message.
143142
144 - `BetaManagedAgentsTextBlock object { text, type }`
143 - `BetaManagedAgentsTextBlock object`
145144
146145 Regular text content.
147146
from line 148
149148
150149 The text content.
151150
151 minLength: 1
152
152153 - `type: "text"`
153154
154 - `"text"`
155 - `BetaManagedAgentsImageBlock object`
155156
156 - `BetaManagedAgentsImageBlock object { source, type }`
157
158157 Image content specified directly as base64 data or as a reference via a URL.
159158
160159 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 160
161160
162161 Union type for image source variants.
163162
164 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
163 - `BetaManagedAgentsBase64ImageSource object`
165164
166165 Base64-encoded image data.
167166
from line 168
169168
170169 Base64-encoded image data.
171170
171 minLength: 1
172
172173 - `media_type: string`
173174
174175 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
175176
177 minLength: 1
178
176179 - `type: "base64"`
177180
178 - `"base64"`
181 - `BetaManagedAgentsURLImageSource object`
179182
180 - `BetaManagedAgentsURLImageSource object { type, url }`
181
182183 Image referenced by URL.
183184
184185 - `type: "url"`
185186
186 - `"url"`
187
188187 - `url: string`
189188
190189 URL of the image to fetch.
191190
192 - `BetaManagedAgentsFileImageSource object { file_id, type }`
191 minLength: 1
193192
193 - `BetaManagedAgentsFileImageSource object`
194
194195 Image referenced by file ID.
195196
196197 - `file_id: string`
from line 198
197198
198199 ID of a previously uploaded file.
199200
201 minLength: 1
202
200203 - `type: "file"`
201204
202 - `"file"`
203
204205 - `type: "image"`
205206
206 - `"image"`
207 - `BetaManagedAgentsDocumentBlock object`
207208
208 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
209
210209 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
211210
212211 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 212
213212
214213 Union type for document source variants.
215214
216 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
215 - `BetaManagedAgentsBase64DocumentSource object`
217216
218217 Base64-encoded document data.
219218
from line 220
221220
222221 Base64-encoded document data.
223222
223 minLength: 1
224
224225 - `media_type: string`
225226
226227 MIME type of the document (e.g., "application/pdf").
227228
229 minLength: 1
230
228231 - `type: "base64"`
229232
230 - `"base64"`
233 - `BetaManagedAgentsPlainTextDocumentSource object`
231234
232 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
233
234235 Plain text document content.
235236
236237 - `data: string`
from line 238
237238
238239 The plain text content.
239240
241 minLength: 1
242
240243 - `media_type: "text/plain"`
241244
242245 MIME type of the text content. Must be "text/plain".
243246
244 - `"text/plain"`
245
246247 - `type: "text"`
247248
248 - `"text"`
249 - `BetaManagedAgentsURLDocumentSource object`
249250
250 - `BetaManagedAgentsURLDocumentSource object { type, url }`
251
252251 Document referenced by URL.
253252
254253 - `type: "url"`
255254
256 - `"url"`
257
258255 - `url: string`
259256
260257 URL of the document to fetch.
261258
262 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
259 minLength: 1
263260
261 - `BetaManagedAgentsFileDocumentSource object`
262
264263 Document referenced by file ID.
265264
266265 - `file_id: string`
from line 266
267266
268267 ID of a previously uploaded file.
269268
269 minLength: 1
270
270271 - `type: "file"`
271272
272 - `"file"`
273
274273 - `type: "document"`
275274
276 - `"document"`
277
278275 - `context: optional string or null`
279276
280277 Additional context about the document for the model.
from line 280
283280
284281 The title of the document.
285282
286 - `BetaManagedAgentsRedactedBlock object { type }`
283 - `BetaManagedAgentsRedactedBlock object`
287284
288285 Placeholder for content withheld by Anthropic model policy.
289286
290287 - `type: "redacted"`
291288
292 - `"redacted"`
293
294289 - `type: "user.message"`
295290
296 - `"user.message"`
291 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
297292
298 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
299
300293 An outcome the agent should work toward. The agent begins work on receipt.
301294
302295 - `description: string`
from line 300
307300
308301 Rubric for grading the quality of an outcome.
309302
310 - `BetaManagedAgentsFileRubric object { file_id, type }`
303 - `BetaManagedAgentsFileRubric object`
311304
312305 Rubric referenced by a file uploaded via the Files API.
313306
from line 310
317310
318311 - `type: "file"`
319312
320 - `"file"`
313 - `BetaManagedAgentsTextRubric object`
321314
322 - `BetaManagedAgentsTextRubric object { content, type }`
323
324315 Rubric content provided inline as text.
325316
326317 - `content: string`
from line 320
329320
330321 - `type: "text"`
331322
332 - `"text"`
333
334323 - `type: "user.define_outcome"`
335324
336 - `"user.define_outcome"`
337
338325 - `max_iterations: optional number or null`
339326
340327 Eval→revision cycles before giving up. Default 3, max 20.
341328
342 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
329 format: int32
343330
331 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
332
344333 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.
345334
346335 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 340
351340
352341 The text content.
353342
343 minLength: 1
344
354345 - `type: "text"`
355346
356 - `"text"`
357
358347 - `type: "system.message"`
359348
360 - `"system.message"`
361
362349 - `metadata: map[string]`
363350
364351 Arbitrary key-value metadata. Maximum 16 pairs.
from line 358
371358
372359 Why a deployment is paused. Non-null exactly when `status` is `paused`.
373360
374 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
361 - `BetaManagedAgentsManualDeploymentPausedReason object`
375362
376363 The caller invoked the pause endpoint on the deployment.
377364
378365 - `type: "manual"`
379366
380 - `"manual"`
367 - `BetaManagedAgentsErrorDeploymentPausedReason object`
381368
382 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
383
384369 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
385370
386371 - `error: BetaManagedAgentsDeploymentPausedReasonError`
from line 372
387372
388373 The error that triggered an auto-pause. Matches the failed run's `error.type`.
389374
390 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
375 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
391376
392377 The deployment's environment was archived.
393378
394379 - `type: "environment_archived_error"`
395380
396 - `"environment_archived_error"`
381 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
397382
398 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
399
400383 The deployment's agent was archived.
401384
402385 - `type: "agent_archived_error"`
403386
404 - `"agent_archived_error"`
387 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
405388
406 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
407
408389 The deployment's environment no longer exists.
409390
410391 - `type: "environment_not_found_error"`
411392
412 - `"environment_not_found_error"`
393 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
413394
414 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
415
416395 A vault referenced by the deployment no longer exists.
417396
418397 - `type: "vault_not_found_error"`
419398
420 - `"vault_not_found_error"`
399 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
421400
422 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
423
424401 A file resource referenced by the deployment no longer exists.
425402
426403 - `type: "file_not_found_error"`
427404
428 - `"file_not_found_error"`
405 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
429406
430 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
431
432407 A referenced resource no longer exists and its kind was not reported.
433408
434409 - `type: "session_resource_not_found_error"`
435410
436 - `"session_resource_not_found_error"`
411 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
437412
438 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
439
440413 The deployment's workspace was archived.
441414
442415 - `type: "workspace_archived_error"`
443416
444 - `"workspace_archived_error"`
417 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
445418
446 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
447
448419 The deployment's organization is disabled.
449420
450421 - `type: "organization_disabled_error"`
451422
452 - `"organization_disabled_error"`
423 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
453424
454 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
455
456425 A memory store referenced by the deployment is archived.
457426
458427 - `type: "memory_store_archived_error"`
459428
460 - `"memory_store_archived_error"`
429 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
461430
462 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
463
464431 A skill referenced by the deployment's agent no longer exists.
465432
466433 - `type: "skill_not_found_error"`
467434
468 - `"skill_not_found_error"`
435 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
469436
470 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
471
472437 A vault referenced by the deployment is archived.
473438
474439 - `type: "vault_archived_error"`
475440
476 - `"vault_archived_error"`
441 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
477442
478 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
479
480443 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
481444
482445 - `type: "unknown_error"`
483446
484 - `"unknown_error"`
447 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
485448
486 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
487
488449 The deployment configures resources, but its environment is self-hosted and cannot mount them.
489450
490451 - `type: "self_hosted_resources_unsupported_error"`
491452
492 - `"self_hosted_resources_unsupported_error"`
453 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
493454
494 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
495
496455 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
497456
498457 - `type: "mcp_egress_blocked_error"`
499458
500 - `"mcp_egress_blocked_error"`
501
502459 - `type: "error"`
503460
504 - `"error"`
505
506461 - `resources: array of BetaManagedAgentsSessionResourceConfig`
507462
508463 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
509464
510 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
465 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
511466
512467 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
513468
514469 - `type: "github_repository"`
515470
516 - `"github_repository"`
517
518471 - `url: string`
519472
520473 Github URL of the repository
from line 476
523476
524477 Branch or commit to check out. Defaults to the repository's default branch.
525478
526 - `BetaManagedAgentsBranchCheckout object { name, type }`
479 - `BetaManagedAgentsBranchCheckout object`
527480
528481 - `name: string`
529482
530483 Branch name to check out.
531484
485 minLength: 1, maxLength: 255
486
532487 - `type: "branch"`
533488
534 - `"branch"`
489 - `BetaManagedAgentsCommitCheckout object`
535490
536 - `BetaManagedAgentsCommitCheckout object { sha, type }`
537
538491 - `sha: string`
539492
540493 Full commit SHA to check out.
541494
495 minLength: 7, maxLength: 64
496
542497 - `type: "commit"`
543498
544 - `"commit"`
545
546499 - `mount_path: optional string or null`
547500
548501 Mount path in the container. Defaults to `/workspace/<repo-name>`.
549502
550 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
503 - `BetaManagedAgentsFileResourceConfig object`
551504
552505 A file mounted into each session's container.
553506
from line 510
557510
558511 - `type: "file"`
559512
560 - `"file"`
561
562513 - `mount_path: optional string or null`
563514
564515 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
565516
566 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
517 - `BetaManagedAgentsMemoryStoreResourceConfig object`
567518
568519 A memory store attached to each session created from this deployment.
569520
from line 524
573524
574525 - `type: "memory_store"`
575526
576 - `"memory_store"`
577
578527 - `access: optional "read_write" or "read_only" or null`
579528
580529 Access mode for an attached memory store.
from line 544
595544
596545 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).
597546
547 minLength: 1, maxLength: 256
548
598549 - `timezone: string`
599550
600551 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
601552
553 minLength: 1
554
602555 - `type: "cron"`
603556
604 - `"cron"`
605
606557 - `last_run_at: optional string or null`
607558
608559 A timestamp in RFC 3339 format
609560
561 format: date-time
562
610563 - `upcoming_runs_at: optional array of string`
611564
612565 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 574
621574
622575 - `type: "deployment"`
623576
624 - `"deployment"`
625
626577 - `updated_at: string`
627578
628579 A timestamp in RFC 3339 format
629580
581 format: date-time
582
630583 - `vault_ids: array of string`
631584
632585 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 600
647600
648601 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
649602
650 - `"USD"`
651
652603 - `type: "limit"`
653604
654 - `"limit"`
605## Example
655606
656### Example
657
658```http
607```bash
659608curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID \
660609 -H 'anthropic-version: 2023-06-01' \
661610 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 611
662611 -H "X-Api-Key: $ANTHROPIC_API_KEY"
663612```
664613
665#### Response
614### Response (200)
666615
667616```json
668617{
api/beta/deployments/run Changed · +36 / -75 lines
# Run Deployment Now ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Run Deployment Now ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Run Deployment Now
3url: https://platform.claude.com/docs/en/api/beta/deployments/run
4---
1# Run Deployment Now
52
6## Run Deployment Now
3**POST** `/v1/deployments/{deployment_id}/run`
74
8**post** `/v1/deployments/{deployment_id}/run`
9
105Run Deployment Now
116
12### Path Parameters
7## Path parameters
138
149- `deployment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsDeploymentRun object { id, agent, created_at, 5 more }`
91- `BetaManagedAgentsDeploymentRun object`
9792
9893 A persistent, append-only record of a single deployment execution. Records session creation success or failure — no session lifecycle tracking.
9994
from line 104
109104
110105 - `type: "agent"`
111106
112 - `"agent"`
113
114107 - `version: number`
115108
109 format: int32
110
116111 - `created_at: string`
117112
118113 A timestamp in RFC 3339 format
119114
115 format: date-time
116
120117 - `deployment_id: string`
121118
122119 ID of the deployment that produced this run.
from line 122
125122
126123 Why the run failed to create a session. The type identifies the failure; message is human-readable detail.
127124
128 - `BetaManagedAgentsEnvironmentArchivedRunError object { message, type }`
125 - `BetaManagedAgentsEnvironmentArchivedRunError object`
129126
130127 The deployment's environment was archived.
131128
from line 132
135132
136133 - `type: "environment_archived_error"`
137134
138 - `"environment_archived_error"`
135 - `BetaManagedAgentsAgentArchivedRunError object`
139136
140 - `BetaManagedAgentsAgentArchivedRunError object { message, type }`
141
142137 The deployment's agent was archived.
143138
144139 - `message: string`
from line 142
147142
148143 - `type: "agent_archived_error"`
149144
150 - `"agent_archived_error"`
145 - `BetaManagedAgentsEnvironmentNotFoundRunError object`
151146
152 - `BetaManagedAgentsEnvironmentNotFoundRunError object { message, type }`
153
154147 The deployment's environment no longer exists.
155148
156149 - `message: string`
from line 152
159152
160153 - `type: "environment_not_found_error"`
161154
162 - `"environment_not_found_error"`
155 - `BetaManagedAgentsVaultNotFoundRunError object`
163156
164 - `BetaManagedAgentsVaultNotFoundRunError object { message, type }`
165
166157 A vault referenced by the deployment no longer exists.
167158
168159 - `message: string`
from line 162
171162
172163 - `type: "vault_not_found_error"`
173164
174 - `"vault_not_found_error"`
165 - `BetaManagedAgentsVaultArchivedRunError object`
175166
176 - `BetaManagedAgentsVaultArchivedRunError object { message, type }`
177
178167 A vault referenced by the deployment is archived.
179168
180169 - `message: string`
from line 172
183172
184173 - `type: "vault_archived_error"`
185174
186 - `"vault_archived_error"`
175 - `BetaManagedAgentsFileNotFoundRunError object`
187176
188 - `BetaManagedAgentsFileNotFoundRunError object { message, type }`
189
190177 A file resource referenced by the deployment no longer exists.
191178
192179 - `message: string`
from line 182
195182
196183 - `type: "file_not_found_error"`
197184
198 - `"file_not_found_error"`
185 - `BetaManagedAgentsMemoryStoreArchivedRunError object`
199186
200 - `BetaManagedAgentsMemoryStoreArchivedRunError object { message, type }`
201
202187 A memory store referenced by the deployment is archived.
203188
204189 - `message: string`
from line 192
207192
208193 - `type: "memory_store_archived_error"`
209194
210 - `"memory_store_archived_error"`
195 - `BetaManagedAgentsSkillNotFoundRunError object`
211196
212 - `BetaManagedAgentsSkillNotFoundRunError object { message, type }`
213
214197 A skill referenced by the deployment's agent no longer exists.
215198
216199 - `message: string`
from line 202
219202
220203 - `type: "skill_not_found_error"`
221204
222 - `"skill_not_found_error"`
205 - `BetaManagedAgentsSessionResourceNotFoundRunError object`
223206
224 - `BetaManagedAgentsSessionResourceNotFoundRunError object { message, type }`
225
226207 A referenced resource no longer exists and its kind was not reported.
227208
228209 - `message: string`
from line 212
231212
232213 - `type: "session_resource_not_found_error"`
233214
234 - `"session_resource_not_found_error"`
215 - `BetaManagedAgentsWorkspaceArchivedRunError object`
235216
236 - `BetaManagedAgentsWorkspaceArchivedRunError object { message, type }`
237
238217 The deployment's workspace was archived.
239218
240219 - `message: string`
from line 222
243222
244223 - `type: "workspace_archived_error"`
245224
246 - `"workspace_archived_error"`
225 - `BetaManagedAgentsOrganizationDisabledRunError object`
247226
248 - `BetaManagedAgentsOrganizationDisabledRunError object { message, type }`
249
250227 The deployment's organization is disabled.
251228
252229 - `message: string`
from line 232
255232
256233 - `type: "organization_disabled_error"`
257234
258 - `"organization_disabled_error"`
235 - `BetaManagedAgentsSessionRateLimitedRunError object`
259236
260 - `BetaManagedAgentsSessionRateLimitedRunError object { message, type }`
261
262237 Session creation was rejected due to rate limiting. The schedule keeps firing; subsequent runs may succeed.
263238
264239 - `message: string`
from line 242
267242
268243 - `type: "session_rate_limited_error"`
269244
270 - `"session_rate_limited_error"`
245 - `BetaManagedAgentsSessionCreationRejectedRunError object`
271246
272 - `BetaManagedAgentsSessionCreationRejectedRunError object { message, type }`
273
274247 The session create request was rejected with a non-retryable validation error.
275248
276249 - `message: string`
from line 252
279252
280253 - `type: "session_creation_rejected_error"`
281254
282 - `"session_creation_rejected_error"`
255 - `BetaManagedAgentsUnknownRunError object`
283256
284 - `BetaManagedAgentsUnknownRunError object { message, type }`
285
286257 An unknown or unexpected error caused the run to fail. A fallback variant; clients that do not recognize a new error type can match on message alone.
287258
288259 - `message: string`
from line 262
291262
292263 - `type: "unknown_error"`
293264
294 - `"unknown_error"`
265 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object`
295266
296 - `BetaManagedAgentsSelfHostedResourcesUnsupportedRunError object { message, type }`
297
298267 The deployment configures resources, but its environment is self-hosted and cannot mount them.
299268
300269 - `message: string`
from line 272
303272
304273 - `type: "self_hosted_resources_unsupported_error"`
305274
306 - `"self_hosted_resources_unsupported_error"`
275 - `BetaManagedAgentsMCPEgressBlockedRunError object`
307276
308 - `BetaManagedAgentsMCPEgressBlockedRunError object { message, type }`
309
310277 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
311278
312279 - `message: string`
from line 282
315282
316283 - `type: "mcp_egress_blocked_error"`
317284
318 - `"mcp_egress_blocked_error"`
319
320285 - `session_id: string or null`
321286
322287 Populated on success. Null on creation failure. Exactly one of session_id or error is non-null.
from line 290
325290
326291 Describes what triggered a deployment run, with trigger-specific metadata.
327292
328 - `BetaManagedAgentsScheduleTriggerContext object { scheduled_at, type }`
293 - `BetaManagedAgentsScheduleTriggerContext object`
329294
330295 The run was fired by the deployment's cron schedule.
331296
from line 298
333298
334299 A timestamp in RFC 3339 format
335300
301 format: date-time
302
336303 - `type: "schedule"`
337304
338 - `"schedule"`
305 - `BetaManagedAgentsManualTriggerContext object`
339306
340 - `BetaManagedAgentsManualTriggerContext object { type }`
341
342307 The run was started manually by creating a session directly against the deployment.
343308
344309 - `type: "manual"`
345310
346 - `"manual"`
347
348311 - `type: "deployment_run"`
349312
350 - `"deployment_run"`
313## Example
351314
352### Example
353
354```http
315```bash
355316curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/run \
356317 -X POST \
357318 -H 'anthropic-version: 2023-06-01' \
from line 320
359320 -H "X-Api-Key: $ANTHROPIC_API_KEY"
360321```
361322
362#### Response
323### Response (200)
363324
364325```json
365326{
api/beta/deployments/unpause Changed · +91 / -142 lines
# Unpause Deployment ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Unpause Deployment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Unpause Deployment
3url: https://platform.claude.com/docs/en/api/beta/deployments/unpause
4---
1# Unpause Deployment
52
6## Unpause Deployment
3**POST** `/v1/deployments/{deployment_id}/unpause`
74
8**post** `/v1/deployments/{deployment_id}/unpause`
9
105Unpause Deployment
116
12### Path Parameters
7## Path parameters
138
149- `deployment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
91- `BetaManagedAgentsDeployment object`
9792
9893 A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.
9994
from line 104
109104
110105 - `type: "agent"`
111106
112 - `"agent"`
113
114107 - `version: number`
115108
109 format: int32
110
116111 - `archived_at: string or null`
117112
118113 A timestamp in RFC 3339 format
119114
115 format: date-time
116
120117 - `created_at: string`
121118
122119 A timestamp in RFC 3339 format
123120
121 format: date-time
122
124123 - `description: string or null`
125124
126125 Description of what the deployment does.
from line 132
133132
134133 Events sent to each session immediately after creation.
135134
136 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
135 - `BetaManagedAgentsDeploymentUserMessageEvent object`
137136
138137 A user message sent to the session.
139138
from line 140
141140
142141 Array of content blocks for the user message.
143142
144 - `BetaManagedAgentsTextBlock object { text, type }`
143 - `BetaManagedAgentsTextBlock object`
145144
146145 Regular text content.
147146
from line 148
149148
150149 The text content.
151150
151 minLength: 1
152
152153 - `type: "text"`
153154
154 - `"text"`
155 - `BetaManagedAgentsImageBlock object`
155156
156 - `BetaManagedAgentsImageBlock object { source, type }`
157
158157 Image content specified directly as base64 data or as a reference via a URL.
159158
160159 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 160
161160
162161 Union type for image source variants.
163162
164 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
163 - `BetaManagedAgentsBase64ImageSource object`
165164
166165 Base64-encoded image data.
167166
from line 168
169168
170169 Base64-encoded image data.
171170
171 minLength: 1
172
172173 - `media_type: string`
173174
174175 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
175176
177 minLength: 1
178
176179 - `type: "base64"`
177180
178 - `"base64"`
181 - `BetaManagedAgentsURLImageSource object`
179182
180 - `BetaManagedAgentsURLImageSource object { type, url }`
181
182183 Image referenced by URL.
183184
184185 - `type: "url"`
185186
186 - `"url"`
187
188187 - `url: string`
189188
190189 URL of the image to fetch.
191190
192 - `BetaManagedAgentsFileImageSource object { file_id, type }`
191 minLength: 1
193192
193 - `BetaManagedAgentsFileImageSource object`
194
194195 Image referenced by file ID.
195196
196197 - `file_id: string`
from line 198
197198
198199 ID of a previously uploaded file.
199200
201 minLength: 1
202
200203 - `type: "file"`
201204
202 - `"file"`
203
204205 - `type: "image"`
205206
206 - `"image"`
207 - `BetaManagedAgentsDocumentBlock object`
207208
208 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
209
210209 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
211210
212211 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 212
213212
214213 Union type for document source variants.
215214
216 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
215 - `BetaManagedAgentsBase64DocumentSource object`
217216
218217 Base64-encoded document data.
219218
from line 220
221220
222221 Base64-encoded document data.
223222
223 minLength: 1
224
224225 - `media_type: string`
225226
226227 MIME type of the document (e.g., "application/pdf").
227228
229 minLength: 1
230
228231 - `type: "base64"`
229232
230 - `"base64"`
233 - `BetaManagedAgentsPlainTextDocumentSource object`
231234
232 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
233
234235 Plain text document content.
235236
236237 - `data: string`
from line 238
237238
238239 The plain text content.
239240
241 minLength: 1
242
240243 - `media_type: "text/plain"`
241244
242245 MIME type of the text content. Must be "text/plain".
243246
244 - `"text/plain"`
245
246247 - `type: "text"`
247248
248 - `"text"`
249 - `BetaManagedAgentsURLDocumentSource object`
249250
250 - `BetaManagedAgentsURLDocumentSource object { type, url }`
251
252251 Document referenced by URL.
253252
254253 - `type: "url"`
255254
256 - `"url"`
257
258255 - `url: string`
259256
260257 URL of the document to fetch.
261258
262 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
259 minLength: 1
263260
261 - `BetaManagedAgentsFileDocumentSource object`
262
264263 Document referenced by file ID.
265264
266265 - `file_id: string`
from line 266
267266
268267 ID of a previously uploaded file.
269268
269 minLength: 1
270
270271 - `type: "file"`
271272
272 - `"file"`
273
274273 - `type: "document"`
275274
276 - `"document"`
277
278275 - `context: optional string or null`
279276
280277 Additional context about the document for the model.
from line 280
283280
284281 The title of the document.
285282
286 - `BetaManagedAgentsRedactedBlock object { type }`
283 - `BetaManagedAgentsRedactedBlock object`
287284
288285 Placeholder for content withheld by Anthropic model policy.
289286
290287 - `type: "redacted"`
291288
292 - `"redacted"`
293
294289 - `type: "user.message"`
295290
296 - `"user.message"`
291 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
297292
298 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
299
300293 An outcome the agent should work toward. The agent begins work on receipt.
301294
302295 - `description: string`
from line 300
307300
308301 Rubric for grading the quality of an outcome.
309302
310 - `BetaManagedAgentsFileRubric object { file_id, type }`
303 - `BetaManagedAgentsFileRubric object`
311304
312305 Rubric referenced by a file uploaded via the Files API.
313306
from line 310
317310
318311 - `type: "file"`
319312
320 - `"file"`
313 - `BetaManagedAgentsTextRubric object`
321314
322 - `BetaManagedAgentsTextRubric object { content, type }`
323
324315 Rubric content provided inline as text.
325316
326317 - `content: string`
from line 320
329320
330321 - `type: "text"`
331322
332 - `"text"`
333
334323 - `type: "user.define_outcome"`
335324
336 - `"user.define_outcome"`
337
338325 - `max_iterations: optional number or null`
339326
340327 Eval→revision cycles before giving up. Default 3, max 20.
341328
342 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
329 format: int32
343330
331 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
332
344333 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.
345334
346335 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 340
351340
352341 The text content.
353342
343 minLength: 1
344
354345 - `type: "text"`
355346
356 - `"text"`
357
358347 - `type: "system.message"`
359348
360 - `"system.message"`
361
362349 - `metadata: map[string]`
363350
364351 Arbitrary key-value metadata. Maximum 16 pairs.
from line 358
371358
372359 Why a deployment is paused. Non-null exactly when `status` is `paused`.
373360
374 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
361 - `BetaManagedAgentsManualDeploymentPausedReason object`
375362
376363 The caller invoked the pause endpoint on the deployment.
377364
378365 - `type: "manual"`
379366
380 - `"manual"`
367 - `BetaManagedAgentsErrorDeploymentPausedReason object`
381368
382 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
383
384369 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
385370
386371 - `error: BetaManagedAgentsDeploymentPausedReasonError`
from line 372
387372
388373 The error that triggered an auto-pause. Matches the failed run's `error.type`.
389374
390 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
375 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
391376
392377 The deployment's environment was archived.
393378
394379 - `type: "environment_archived_error"`
395380
396 - `"environment_archived_error"`
381 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
397382
398 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
399
400383 The deployment's agent was archived.
401384
402385 - `type: "agent_archived_error"`
403386
404 - `"agent_archived_error"`
387 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
405388
406 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
407
408389 The deployment's environment no longer exists.
409390
410391 - `type: "environment_not_found_error"`
411392
412 - `"environment_not_found_error"`
393 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
413394
414 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
415
416395 A vault referenced by the deployment no longer exists.
417396
418397 - `type: "vault_not_found_error"`
419398
420 - `"vault_not_found_error"`
399 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
421400
422 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
423
424401 A file resource referenced by the deployment no longer exists.
425402
426403 - `type: "file_not_found_error"`
427404
428 - `"file_not_found_error"`
405 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
429406
430 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
431
432407 A referenced resource no longer exists and its kind was not reported.
433408
434409 - `type: "session_resource_not_found_error"`
435410
436 - `"session_resource_not_found_error"`
411 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
437412
438 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
439
440413 The deployment's workspace was archived.
441414
442415 - `type: "workspace_archived_error"`
443416
444 - `"workspace_archived_error"`
417 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
445418
446 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
447
448419 The deployment's organization is disabled.
449420
450421 - `type: "organization_disabled_error"`
451422
452 - `"organization_disabled_error"`
423 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
453424
454 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
455
456425 A memory store referenced by the deployment is archived.
457426
458427 - `type: "memory_store_archived_error"`
459428
460 - `"memory_store_archived_error"`
429 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
461430
462 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
463
464431 A skill referenced by the deployment's agent no longer exists.
465432
466433 - `type: "skill_not_found_error"`
467434
468 - `"skill_not_found_error"`
435 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
469436
470 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
471
472437 A vault referenced by the deployment is archived.
473438
474439 - `type: "vault_archived_error"`
475440
476 - `"vault_archived_error"`
441 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
477442
478 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
479
480443 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
481444
482445 - `type: "unknown_error"`
483446
484 - `"unknown_error"`
447 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
485448
486 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
487
488449 The deployment configures resources, but its environment is self-hosted and cannot mount them.
489450
490451 - `type: "self_hosted_resources_unsupported_error"`
491452
492 - `"self_hosted_resources_unsupported_error"`
453 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
493454
494 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
495
496455 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
497456
498457 - `type: "mcp_egress_blocked_error"`
499458
500 - `"mcp_egress_blocked_error"`
501
502459 - `type: "error"`
503460
504 - `"error"`
505
506461 - `resources: array of BetaManagedAgentsSessionResourceConfig`
507462
508463 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
509464
510 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
465 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
511466
512467 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
513468
514469 - `type: "github_repository"`
515470
516 - `"github_repository"`
517
518471 - `url: string`
519472
520473 Github URL of the repository
from line 476
523476
524477 Branch or commit to check out. Defaults to the repository's default branch.
525478
526 - `BetaManagedAgentsBranchCheckout object { name, type }`
479 - `BetaManagedAgentsBranchCheckout object`
527480
528481 - `name: string`
529482
530483 Branch name to check out.
531484
485 minLength: 1, maxLength: 255
486
532487 - `type: "branch"`
533488
534 - `"branch"`
489 - `BetaManagedAgentsCommitCheckout object`
535490
536 - `BetaManagedAgentsCommitCheckout object { sha, type }`
537
538491 - `sha: string`
539492
540493 Full commit SHA to check out.
541494
495 minLength: 7, maxLength: 64
496
542497 - `type: "commit"`
543498
544 - `"commit"`
545
546499 - `mount_path: optional string or null`
547500
548501 Mount path in the container. Defaults to `/workspace/<repo-name>`.
549502
550 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
503 - `BetaManagedAgentsFileResourceConfig object`
551504
552505 A file mounted into each session's container.
553506
from line 510
557510
558511 - `type: "file"`
559512
560 - `"file"`
561
562513 - `mount_path: optional string or null`
563514
564515 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
565516
566 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
517 - `BetaManagedAgentsMemoryStoreResourceConfig object`
567518
568519 A memory store attached to each session created from this deployment.
569520
from line 524
573524
574525 - `type: "memory_store"`
575526
576 - `"memory_store"`
577
578527 - `access: optional "read_write" or "read_only" or null`
579528
580529 Access mode for an attached memory store.
from line 544
595544
596545 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).
597546
547 minLength: 1, maxLength: 256
548
598549 - `timezone: string`
599550
600551 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
601552
553 minLength: 1
554
602555 - `type: "cron"`
603556
604 - `"cron"`
605
606557 - `last_run_at: optional string or null`
607558
608559 A timestamp in RFC 3339 format
609560
561 format: date-time
562
610563 - `upcoming_runs_at: optional array of string`
611564
612565 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 574
621574
622575 - `type: "deployment"`
623576
624 - `"deployment"`
625
626577 - `updated_at: string`
627578
628579 A timestamp in RFC 3339 format
629580
581 format: date-time
582
630583 - `vault_ids: array of string`
631584
632585 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 600
647600
648601 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
649602
650 - `"USD"`
651
652603 - `type: "limit"`
653604
654 - `"limit"`
605## Example
655606
656### Example
657
658```http
607```bash
659608curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/unpause \
660609 -X POST \
661610 -H 'anthropic-version: 2023-06-01' \
from line 612
663612 -H "X-Api-Key: $ANTHROPIC_API_KEY"
664613```
665614
666#### Response
615### Response (200)
667616
668617```json
669618{
api/beta/deployments/update Changed · +170 / -219 lines
# Update Deployment ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Deployment ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Update Deployment
3url: https://platform.claude.com/docs/en/api/beta/deployments/update
4---
1# Update Deployment
52
6## Update Deployment
3**POST** `/v1/deployments/{deployment_id}`
74
8**post** `/v1/deployments/{deployment_id}`
9
105Update Deployment
116
12### Path Parameters
7## Path parameters
138
149- `deployment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Body Parameters
89## Body parameters
9590
9691- `agent: optional string or BetaManagedAgentsAgentParams`
9792
from line 94
9994
10095 - `string`
10196
102 - `BetaManagedAgentsAgentParams object { id, type, version }`
97 - `BetaManagedAgentsAgentParams object`
10398
10499 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
105100
from line 102
107102
108103 The `agent` ID.
109104
105 minLength: 1, maxLength: 128
106
110107 - `type: "agent"`
111108
112 - `"agent"`
113
114109 - `version: optional number`
115110
116111 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
117112
113 format: int32
114
118115- `budget: optional BetaManagedAgentsBudgetLimit or null`
119116
120117 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 128
131128
132129 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
133130
134 - `"USD"`
135
136131 - `type: "limit"`
137132
138 - `"limit"`
139
140133- `description: optional string or null`
141134
142135 Description. Omit to preserve; send empty string or null to clear.
143136
137 maxLength: 2048
138
144139- `environment_id: optional string`
145140
146141 ID of the `environment` where sessions run. Omit to preserve. Cannot be cleared.
147142
143 maxLength: 128
144
148145- `initial_events: optional array of BetaManagedAgentsDeploymentInitialEventParams`
149146
150147 Initial events. Full replacement. Omit to preserve. Cannot be cleared. At least 1, maximum 50.
151148
152 - `BetaManagedAgentsUserMessageEventParams object { content, type }`
149 - `BetaManagedAgentsUserMessageEventParams object`
153150
154151 Parameters for sending a user message to the session.
155152
from line 154
157154
158155 Array of content blocks for the user message.
159156
160 - `BetaManagedAgentsTextBlock object { text, type }`
157 - `BetaManagedAgentsTextBlock object`
161158
162159 Regular text content.
163160
from line 162
165162
166163 The text content.
167164
165 minLength: 1
166
168167 - `type: "text"`
169168
170 - `"text"`
169 - `BetaManagedAgentsImageBlock object`
171170
172 - `BetaManagedAgentsImageBlock object { source, type }`
173
174171 Image content specified directly as base64 data or as a reference via a URL.
175172
176173 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 174
177174
178175 Union type for image source variants.
179176
180 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
177 - `BetaManagedAgentsBase64ImageSource object`
181178
182179 Base64-encoded image data.
183180
from line 182
185182
186183 Base64-encoded image data.
187184
185 minLength: 1
186
188187 - `media_type: string`
189188
190189 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
191190
191 minLength: 1
192
192193 - `type: "base64"`
193194
194 - `"base64"`
195 - `BetaManagedAgentsURLImageSource object`
195196
196 - `BetaManagedAgentsURLImageSource object { type, url }`
197
198197 Image referenced by URL.
199198
200199 - `type: "url"`
201200
202 - `"url"`
203
204201 - `url: string`
205202
206203 URL of the image to fetch.
207204
208 - `BetaManagedAgentsFileImageSource object { file_id, type }`
205 minLength: 1
209206
207 - `BetaManagedAgentsFileImageSource object`
208
210209 Image referenced by file ID.
211210
212211 - `file_id: string`
from line 212
213212
214213 ID of a previously uploaded file.
215214
215 minLength: 1
216
216217 - `type: "file"`
217218
218 - `"file"`
219
220219 - `type: "image"`
221220
222 - `"image"`
221 - `BetaManagedAgentsDocumentBlock object`
223222
224 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
225
226223 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
227224
228225 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 226
229226
230227 Union type for document source variants.
231228
232 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
229 - `BetaManagedAgentsBase64DocumentSource object`
233230
234231 Base64-encoded document data.
235232
from line 234
237234
238235 Base64-encoded document data.
239236
237 minLength: 1
238
240239 - `media_type: string`
241240
242241 MIME type of the document (e.g., "application/pdf").
243242
243 minLength: 1
244
244245 - `type: "base64"`
245246
246 - `"base64"`
247 - `BetaManagedAgentsPlainTextDocumentSource object`
247248
248 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
249
250249 Plain text document content.
251250
252251 - `data: string`
from line 252
253252
254253 The plain text content.
255254
255 minLength: 1
256
256257 - `media_type: "text/plain"`
257258
258259 MIME type of the text content. Must be "text/plain".
259260
260 - `"text/plain"`
261
262261 - `type: "text"`
263262
264 - `"text"`
263 - `BetaManagedAgentsURLDocumentSource object`
265264
266 - `BetaManagedAgentsURLDocumentSource object { type, url }`
267
268265 Document referenced by URL.
269266
270267 - `type: "url"`
271268
272 - `"url"`
273
274269 - `url: string`
275270
276271 URL of the document to fetch.
277272
278 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
273 minLength: 1
279274
275 - `BetaManagedAgentsFileDocumentSource object`
276
280277 Document referenced by file ID.
281278
282279 - `file_id: string`
from line 280
283280
284281 ID of a previously uploaded file.
285282
283 minLength: 1
284
286285 - `type: "file"`
287286
288 - `"file"`
289
290287 - `type: "document"`
291288
292 - `"document"`
293
294289 - `context: optional string or null`
295290
296291 Additional context about the document for the model.
from line 294
299294
300295 The title of the document.
301296
302 - `BetaManagedAgentsRedactedBlock object { type }`
297 - `BetaManagedAgentsRedactedBlock object`
303298
304299 Placeholder for content withheld by Anthropic model policy.
305300
306301 - `type: "redacted"`
307302
308 - `"redacted"`
309
310303 - `type: "user.message"`
311304
312 - `"user.message"`
305 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
313306
314 - `BetaManagedAgentsUserDefineOutcomeEventParams object { description, rubric, type, max_iterations }`
315
316307 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
317308
318309 - `description: string`
from line 314
323314
324315 Rubric for grading the quality of an outcome.
325316
326 - `BetaManagedAgentsFileRubricParams object { file_id, type }`
317 - `BetaManagedAgentsFileRubricParams object`
327318
328319 Rubric referenced by a file uploaded via the Files API.
329320
from line 324
333324
334325 - `type: "file"`
335326
336 - `"file"`
327 - `BetaManagedAgentsTextRubricParams object`
337328
338 - `BetaManagedAgentsTextRubricParams object { content, type }`
339
340329 Rubric content provided inline as text.
341330
342331 - `content: string`
from line 332
343332
344333 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
345334
335 maxLength: 262144
336
346337 - `type: "text"`
347338
348 - `"text"`
349
350339 - `type: "user.define_outcome"`
351340
352 - `"user.define_outcome"`
353
354341 - `max_iterations: optional number or null`
355342
356343 Eval→revision cycles before giving up. Default 3, max 20.
357344
358 - `BetaManagedAgentsSystemMessageEventParams object { content, type }`
345 format: int32
359346
347 - `BetaManagedAgentsSystemMessageEventParams object`
348
360349 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.
361350
362351 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 356
367356
368357 The text content.
369358
359 minLength: 1
360
370361 - `type: "text"`
371362
372 - `"text"`
373
374363 - `type: "system.message"`
375364
376 - `"system.message"`
377
378365- `metadata: optional map[string] or null`
379366
380367 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars.
from line 370
383370
384371 Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.
385372
373 maxLength: 256
374
386375- `resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParam or null`
387376
388377 Session resources. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 500.
389378
390 - `BetaManagedAgentsGitHubRepositoryResourceParams object { authorization_token, type, url, 2 more }`
379 - `BetaManagedAgentsGitHubRepositoryResourceParams object`
391380
392381 Mount a GitHub repository into the session's container.
393382
from line 384
395384
396385 GitHub authorization token used to clone the repository.
397386
387 minLength: 1, maxLength: 4096
388
398389 - `type: "github_repository"`
399390
400 - `"github_repository"`
401
402391 - `url: string`
403392
404393 Github URL of the repository
405394
395 minLength: 1, maxLength: 2048
396
406397 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
407398
408399 Branch or commit to check out. Defaults to the repository's default branch.
409400
410 - `BetaManagedAgentsBranchCheckout object { name, type }`
401 - `BetaManagedAgentsBranchCheckout object`
411402
412403 - `name: string`
413404
414405 Branch name to check out.
415406
407 minLength: 1, maxLength: 255
408
416409 - `type: "branch"`
417410
418 - `"branch"`
411 - `BetaManagedAgentsCommitCheckout object`
419412
420 - `BetaManagedAgentsCommitCheckout object { sha, type }`
421
422413 - `sha: string`
423414
424415 Full commit SHA to check out.
425416
417 minLength: 7, maxLength: 64
418
426419 - `type: "commit"`
427420
428 - `"commit"`
429
430421 - `mount_path: optional string or null`
431422
432423 Mount path in the container. Defaults to `/workspace/<repo-name>`.
433424
434 - `BetaManagedAgentsFileResourceParams object { file_id, type, mount_path }`
425 minLength: 1, maxLength: 4096
435426
427 - `BetaManagedAgentsFileResourceParams object`
428
436429 Mount a file uploaded via the Files API into the session.
437430
438431 - `file_id: string`
from line 432
439432
440433 ID of a previously uploaded file.
441434
435 minLength: 1, maxLength: 128
436
442437 - `type: "file"`
443438
444 - `"file"`
445
446439 - `mount_path: optional string or null`
447440
448441 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
449442
450 - `BetaManagedAgentsMemoryStoreResourceParam object { memory_store_id, type, access, instructions }`
443 minLength: 1, maxLength: 4096
451444
445 - `BetaManagedAgentsMemoryStoreResourceParam object`
446
452447 Parameters for attaching a memory store to an agent session.
453448
454449 - `memory_store_id: string`
from line 452
457452
458453 - `type: "memory_store"`
459454
460 - `"memory_store"`
461
462455 - `access: optional "read_write" or "read_only" or null`
463456
464457 Access mode for an attached memory store.
from line 464
471464
472465 Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
473466
467 maxLength: 4096
468
474469- `schedule: optional BetaManagedAgentsScheduleParams or null`
475470
476471 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
from line 474
479474
480475 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).
481476
477 minLength: 1, maxLength: 256
478
482479 - `timezone: string`
483480
484481 Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.
485482
483 minLength: 1
484
486485 - `type: "cron"`
487486
488 - `"cron"`
489
490487- `vault_ids: optional array of string or null`
491488
492489 Vault IDs. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 50.
493490
494### Returns
491## Returns
495492
496- `BetaManagedAgentsDeployment object { id, agent, archived_at, 14 more }`
493- `BetaManagedAgentsDeployment object`
497494
498495 A deployment is a configured instance of an agent — it binds the agent to everything needed to run it autonomously: an environment, credentials, initial events, and an optional schedule.
499496
from line 506
509506
510507 - `type: "agent"`
511508
512 - `"agent"`
513
514509 - `version: number`
515510
511 format: int32
512
516513 - `archived_at: string or null`
517514
518515 A timestamp in RFC 3339 format
519516
517 format: date-time
518
520519 - `created_at: string`
521520
522521 A timestamp in RFC 3339 format
523522
523 format: date-time
524
524525 - `description: string or null`
525526
526527 Description of what the deployment does.
from line 534
533534
534535 Events sent to each session immediately after creation.
535536
536 - `BetaManagedAgentsDeploymentUserMessageEvent object { content, type }`
537 - `BetaManagedAgentsDeploymentUserMessageEvent object`
537538
538539 A user message sent to the session.
539540
from line 542
541542
542543 Array of content blocks for the user message.
543544
544 - `BetaManagedAgentsTextBlock object { text, type }`
545 - `BetaManagedAgentsTextBlock object`
545546
546547 Regular text content.
547548
from line 550
549550
550551 The text content.
551552
553 minLength: 1
554
552555 - `type: "text"`
553556
554 - `"text"`
557 - `BetaManagedAgentsImageBlock object`
555558
556 - `BetaManagedAgentsImageBlock object { source, type }`
557
558559 Image content specified directly as base64 data or as a reference via a URL.
559560
560561 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
from line 562
561562
562563 Union type for image source variants.
563564
564 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
565 - `BetaManagedAgentsBase64ImageSource object`
565566
566567 Base64-encoded image data.
567568
from line 570
569570
570571 Base64-encoded image data.
571572
573 minLength: 1
574
572575 - `media_type: string`
573576
574577 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
575578
579 minLength: 1
580
576581 - `type: "base64"`
577582
578 - `"base64"`
583 - `BetaManagedAgentsURLImageSource object`
579584
580 - `BetaManagedAgentsURLImageSource object { type, url }`
581
582585 Image referenced by URL.
583586
584587 - `type: "url"`
585588
586 - `"url"`
587
588589 - `url: string`
589590
590591 URL of the image to fetch.
591592
592 - `BetaManagedAgentsFileImageSource object { file_id, type }`
593 minLength: 1
593594
595 - `BetaManagedAgentsFileImageSource object`
596
594597 Image referenced by file ID.
595598
596599 - `file_id: string`
from line 600
597600
598601 ID of a previously uploaded file.
599602
603 minLength: 1
604
600605 - `type: "file"`
601606
602 - `"file"`
603
604607 - `type: "image"`
605608
606 - `"image"`
609 - `BetaManagedAgentsDocumentBlock object`
607610
608 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
609
610611 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
611612
612613 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
from line 614
613614
614615 Union type for document source variants.
615616
616 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
617 - `BetaManagedAgentsBase64DocumentSource object`
617618
618619 Base64-encoded document data.
619620
from line 622
621622
622623 Base64-encoded document data.
623624
625 minLength: 1
626
624627 - `media_type: string`
625628
626629 MIME type of the document (e.g., "application/pdf").
627630
631 minLength: 1
632
628633 - `type: "base64"`
629634
630 - `"base64"`
635 - `BetaManagedAgentsPlainTextDocumentSource object`
631636
632 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
633
634637 Plain text document content.
635638
636639 - `data: string`
from line 640
637640
638641 The plain text content.
639642
643 minLength: 1
644
640645 - `media_type: "text/plain"`
641646
642647 MIME type of the text content. Must be "text/plain".
643648
644 - `"text/plain"`
645
646649 - `type: "text"`
647650
648 - `"text"`
651 - `BetaManagedAgentsURLDocumentSource object`
649652
650 - `BetaManagedAgentsURLDocumentSource object { type, url }`
651
652653 Document referenced by URL.
653654
654655 - `type: "url"`
655656
656 - `"url"`
657
658657 - `url: string`
659658
660659 URL of the document to fetch.
661660
662 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
661 minLength: 1
663662
663 - `BetaManagedAgentsFileDocumentSource object`
664
664665 Document referenced by file ID.
665666
666667 - `file_id: string`
from line 668
667668
668669 ID of a previously uploaded file.
669670
671 minLength: 1
672
670673 - `type: "file"`
671674
672 - `"file"`
673
674675 - `type: "document"`
675676
676 - `"document"`
677
678677 - `context: optional string or null`
679678
680679 Additional context about the document for the model.
from line 682
683682
684683 The title of the document.
685684
686 - `BetaManagedAgentsRedactedBlock object { type }`
685 - `BetaManagedAgentsRedactedBlock object`
687686
688687 Placeholder for content withheld by Anthropic model policy.
689688
690689 - `type: "redacted"`
691690
692 - `"redacted"`
693
694691 - `type: "user.message"`
695692
696 - `"user.message"`
693 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
697694
698 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object { description, rubric, type, max_iterations }`
699
700695 An outcome the agent should work toward. The agent begins work on receipt.
701696
702697 - `description: string`
from line 702
707702
708703 Rubric for grading the quality of an outcome.
709704
710 - `BetaManagedAgentsFileRubric object { file_id, type }`
705 - `BetaManagedAgentsFileRubric object`
711706
712707 Rubric referenced by a file uploaded via the Files API.
713708
from line 712
717712
718713 - `type: "file"`
719714
720 - `"file"`
715 - `BetaManagedAgentsTextRubric object`
721716
722 - `BetaManagedAgentsTextRubric object { content, type }`
723
724717 Rubric content provided inline as text.
725718
726719 - `content: string`
from line 722
729722
730723 - `type: "text"`
731724
732 - `"text"`
733
734725 - `type: "user.define_outcome"`
735726
736 - `"user.define_outcome"`
737
738727 - `max_iterations: optional number or null`
739728
740729 Eval→revision cycles before giving up. Default 3, max 20.
741730
742 - `BetaManagedAgentsDeploymentSystemMessageEvent object { content, type }`
731 format: int32
743732
733 - `BetaManagedAgentsDeploymentSystemMessageEvent object`
734
744735 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt.
745736
746737 - `content: array of BetaManagedAgentsSystemContentBlock`
from line 742
751742
752743 The text content.
753744
745 minLength: 1
746
754747 - `type: "text"`
755748
756 - `"text"`
757
758749 - `type: "system.message"`
759750
760 - `"system.message"`
761
762751 - `metadata: map[string]`
763752
764753 Arbitrary key-value metadata. Maximum 16 pairs.
from line 760
771760
772761 Why a deployment is paused. Non-null exactly when `status` is `paused`.
773762
774 - `BetaManagedAgentsManualDeploymentPausedReason object { type }`
763 - `BetaManagedAgentsManualDeploymentPausedReason object`
775764
776765 The caller invoked the pause endpoint on the deployment.
777766
778767 - `type: "manual"`
779768
780 - `"manual"`
769 - `BetaManagedAgentsErrorDeploymentPausedReason object`
781770
782 - `BetaManagedAgentsErrorDeploymentPausedReason object { error, type }`
783
784771 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
785772
786773 - `error: BetaManagedAgentsDeploymentPausedReasonError`
from line 774
787774
788775 The error that triggered an auto-pause. Matches the failed run's `error.type`.
789776
790 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object { type }`
777 - `BetaManagedAgentsEnvironmentArchivedDeploymentPausedReasonError object`
791778
792779 The deployment's environment was archived.
793780
794781 - `type: "environment_archived_error"`
795782
796 - `"environment_archived_error"`
783 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object`
797784
798 - `BetaManagedAgentsAgentArchivedDeploymentPausedReasonError object { type }`
799
800785 The deployment's agent was archived.
801786
802787 - `type: "agent_archived_error"`
803788
804 - `"agent_archived_error"`
789 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object`
805790
806 - `BetaManagedAgentsEnvironmentNotFoundDeploymentPausedReasonError object { type }`
807
808791 The deployment's environment no longer exists.
809792
810793 - `type: "environment_not_found_error"`
811794
812 - `"environment_not_found_error"`
795 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object`
813796
814 - `BetaManagedAgentsVaultNotFoundDeploymentPausedReasonError object { type }`
815
816797 A vault referenced by the deployment no longer exists.
817798
818799 - `type: "vault_not_found_error"`
819800
820 - `"vault_not_found_error"`
801 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object`
821802
822 - `BetaManagedAgentsFileNotFoundDeploymentPausedReasonError object { type }`
823
824803 A file resource referenced by the deployment no longer exists.
825804
826805 - `type: "file_not_found_error"`
827806
828 - `"file_not_found_error"`
807 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object`
829808
830 - `BetaManagedAgentsSessionResourceNotFoundDeploymentPausedReasonError object { type }`
831
832809 A referenced resource no longer exists and its kind was not reported.
833810
834811 - `type: "session_resource_not_found_error"`
835812
836 - `"session_resource_not_found_error"`
813 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object`
837814
838 - `BetaManagedAgentsWorkspaceArchivedDeploymentPausedReasonError object { type }`
839
840815 The deployment's workspace was archived.
841816
842817 - `type: "workspace_archived_error"`
843818
844 - `"workspace_archived_error"`
819 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object`
845820
846 - `BetaManagedAgentsOrganizationDisabledDeploymentPausedReasonError object { type }`
847
848821 The deployment's organization is disabled.
849822
850823 - `type: "organization_disabled_error"`
851824
852 - `"organization_disabled_error"`
825 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object`
853826
854 - `BetaManagedAgentsMemoryStoreArchivedDeploymentPausedReasonError object { type }`
855
856827 A memory store referenced by the deployment is archived.
857828
858829 - `type: "memory_store_archived_error"`
859830
860 - `"memory_store_archived_error"`
831 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object`
861832
862 - `BetaManagedAgentsSkillNotFoundDeploymentPausedReasonError object { type }`
863
864833 A skill referenced by the deployment's agent no longer exists.
865834
866835 - `type: "skill_not_found_error"`
867836
868 - `"skill_not_found_error"`
837 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object`
869838
870 - `BetaManagedAgentsVaultArchivedDeploymentPausedReasonError object { type }`
871
872839 A vault referenced by the deployment is archived.
873840
874841 - `type: "vault_archived_error"`
875842
876 - `"vault_archived_error"`
843 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object`
877844
878 - `BetaManagedAgentsUnknownDeploymentPausedReasonError object { type }`
879
880845 An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
881846
882847 - `type: "unknown_error"`
883848
884 - `"unknown_error"`
849 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object`
885850
886 - `BetaManagedAgentsSelfHostedResourcesUnsupportedDeploymentPausedReasonError object { type }`
887
888851 The deployment configures resources, but its environment is self-hosted and cannot mount them.
889852
890853 - `type: "self_hosted_resources_unsupported_error"`
891854
892 - `"self_hosted_resources_unsupported_error"`
855 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object`
893856
894 - `BetaManagedAgentsMCPEgressBlockedDeploymentPausedReasonError object { type }`
895
896857 An MCP server host used by the deployment's agent is blocked by the environment's network policy.
897858
898859 - `type: "mcp_egress_blocked_error"`
899860
900 - `"mcp_egress_blocked_error"`
901
902861 - `type: "error"`
903862
904 - `"error"`
905
906863 - `resources: array of BetaManagedAgentsSessionResourceConfig`
907864
908865 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
909866
910 - `BetaManagedAgentsGitHubRepositoryResourceConfig object { type, url, checkout, mount_path }`
867 - `BetaManagedAgentsGitHubRepositoryResourceConfig object`
911868
912869 A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
913870
914871 - `type: "github_repository"`
915872
916 - `"github_repository"`
917
918873 - `url: string`
919874
920875 Github URL of the repository
from line 878
923878
924879 Branch or commit to check out. Defaults to the repository's default branch.
925880
926 - `BetaManagedAgentsBranchCheckout object { name, type }`
881 - `BetaManagedAgentsBranchCheckout object`
927882
928883 - `name: string`
929884
930885 Branch name to check out.
931886
887 minLength: 1, maxLength: 255
888
932889 - `type: "branch"`
933890
934 - `"branch"`
891 - `BetaManagedAgentsCommitCheckout object`
935892
936 - `BetaManagedAgentsCommitCheckout object { sha, type }`
937
938893 - `sha: string`
939894
940895 Full commit SHA to check out.
941896
897 minLength: 7, maxLength: 64
898
942899 - `type: "commit"`
943900
944 - `"commit"`
945
946901 - `mount_path: optional string or null`
947902
948903 Mount path in the container. Defaults to `/workspace/<repo-name>`.
949904
950 - `BetaManagedAgentsFileResourceConfig object { file_id, type, mount_path }`
905 - `BetaManagedAgentsFileResourceConfig object`
951906
952907 A file mounted into each session's container.
953908
from line 912
957912
958913 - `type: "file"`
959914
960 - `"file"`
961
962915 - `mount_path: optional string or null`
963916
964917 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
965918
966 - `BetaManagedAgentsMemoryStoreResourceConfig object { memory_store_id, type, access, instructions }`
919 - `BetaManagedAgentsMemoryStoreResourceConfig object`
967920
968921 A memory store attached to each session created from this deployment.
969922
from line 926
973926
974927 - `type: "memory_store"`
975928
976 - `"memory_store"`
977
978929 - `access: optional "read_write" or "read_only" or null`
979930
980931 Access mode for an attached memory store.
from line 946
995946
996947 5-field POSIX cron expression: minute hour day-of-month month day-of-week (e.g., "0 9 * * 1-5" for weekdays at 9am). Day-of-week is 0-7 where 0 and 7 both mean Sunday. Extended cron syntax - seconds or year fields, and the special characters L, W, #, and ? - is not supported, nor are predefined shortcuts (@daily).
997948
949 minLength: 1, maxLength: 256
950
998951 - `timezone: string`
999952
1000953 IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
1001954
955 minLength: 1
956
1002957 - `type: "cron"`
1003958
1004 - `"cron"`
1005
1006959 - `last_run_at: optional string or null`
1007960
1008961 A timestamp in RFC 3339 format
1009962
963 format: date-time
964
1010965 - `upcoming_runs_at: optional array of string`
1011966
1012967 Up to 5 timestamps of upcoming cron occurrences. Non-empty for active and paused deployments (reflects what the schedule would do if unpaused); empty once the deployment is archived (`archived_at` set). Each fire is offset by a small per-schedule jitter, so a run will actually start at or shortly after its listed time.
from line 976
1021976
1022977 - `type: "deployment"`
1023978
1024 - `"deployment"`
1025
1026979 - `updated_at: string`
1027980
1028981 A timestamp in RFC 3339 format
1029982
983 format: date-time
984
1030985 - `vault_ids: array of string`
1031986
1032987 Vault IDs supplying stored credentials for sessions created from this deployment.
from line 1002
10471002
10481003 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
10491004
1050 - `"USD"`
1051
10521005 - `type: "limit"`
10531006
1054 - `"limit"`
1007## Example
10551008
1056### Example
1057
1058```http
1009```bash
10591010curl https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID \
10601011 -H 'Content-Type: application/json' \
10611012 -H 'anthropic-version: 2023-06-01' \
from line 1015
10641015 -d '{}'
10651016```
10661017
1067#### Response
1018### Response (200)
10681019
10691020```json
10701021{
api/beta/dreams Changed · +228 / -179 lines
### Headers ### Body parameters #### Response (200) ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Header Parameters ### Body Parameters #### Response ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Dreams
3url: https://platform.claude.com/docs/en/api/beta/dreams
4---
5
61# Dreams
72
83## Create a Dream
94
10**post** `/v1/dreams`
5**POST** `/v1/dreams`
116
127Create a Dream
138
14### Header Parameters
9### Headers
1510
1611- `"anthropic-beta": optional array of AnthropicBeta`
1712
from line 84
8984
9085 - `"mid-conversation-tool-changes-2026-07-01"`
9186
92### Body Parameters
87### Body parameters
9388
9489- `inputs: array of BetaDreamInput`
9590
96 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
91 - `BetaDreamMemoryStoreInput object`
9792
9893 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
9994
10095 - `memory_store_id: string`
10196
97 minLength: 1
98
10299 - `type: "memory_store"`
103100
104 - `"memory_store"`
105
106 - `BetaDreamSessionsInput object { session_ids, type }`
101 - `BetaDreamSessionsInput object`
107102
108103 Input session transcripts the dream reads.
109104
from line 106
111106
112107 - `type: "sessions"`
113108
114 - `"sessions"`
115
116109- `model: string or BetaDreamModelConfigParam`
117110
118111 Model identifier and configuration applied to every pipeline stage.
119112
120113 - `string`
121114
122 - `BetaDreamModelConfigParam object { id, speed }`
115 - `BetaDreamModelConfigParam object`
123116
124117 Model identifier and configuration applied to every pipeline stage.
125118
from line 120
127120
128121 Model identifier, e.g. "claude-opus-5". 1-256 characters.
129122
123 minLength: 1, maxLength: 256
124
130125 - `speed: optional "standard" or "fast" or null`
131126
132127 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 132
137132
138133- `instructions: optional string or null`
139134
135 minLength: 1, maxLength: 4096
136
140137- `output_behavior: optional BetaOutputBehavior`
141138
142139 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
143140
144 - `BetaOutputBehaviorCreateNew object { type }`
141 - `BetaOutputBehaviorCreateNew object`
145142
146143 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
147144
148145 - `type: "create_new"`
149146
150 - `"create_new"`
151
152 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
147 - `BetaOutputBehaviorUpdateExisting object`
153148
154149 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
155150
156151 - `memory_store_id: string`
157152
153 minLength: 1
154
158155 - `type: "update_existing"`
159156
160 - `"update_existing"`
161
162157### Returns
163158
164- `BetaDream object { id, archived_at, created_at, 11 more }`
159- `BetaDream object`
165160
166161 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
167162
from line 166
171166
172167 A timestamp in RFC 3339 format
173168
169 format: date-time
170
174171 - `created_at: string`
175172
176173 A timestamp in RFC 3339 format
177174
175 format: date-time
176
178177 - `ended_at: string or null`
179178
180179 A timestamp in RFC 3339 format
181180
181 format: date-time
182
182183 - `error: BetaDreamError or null`
183184
184185 Failure detail for a Dream whose `status` is `failed`.
from line 190
189190
190191 - `inputs: array of BetaDreamInput`
191192
192 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
193 - `BetaDreamMemoryStoreInput object`
193194
194195 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
195196
196197 - `memory_store_id: string`
197198
199 minLength: 1
200
198201 - `type: "memory_store"`
199202
200 - `"memory_store"`
201
202 - `BetaDreamSessionsInput object { session_ids, type }`
203 - `BetaDreamSessionsInput object`
203204
204205 Input session transcripts the dream reads.
205206
from line 208
207208
208209 - `type: "sessions"`
209210
210 - `"sessions"`
211
212211 - `instructions: string or null`
213212
214213 - `model: BetaDreamModelConfig`
from line 218
219218
220219 Model identifier, e.g. "claude-opus-5". 1-256 characters.
221220
221 minLength: 1, maxLength: 256
222
222223 - `speed: optional "standard" or "fast"`
223224
224225 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 232
231232
232233 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
233234
234 - `BetaOutputBehaviorCreateNew object { type }`
235 - `BetaOutputBehaviorCreateNew object`
235236
236237 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
237238
238239 - `type: "create_new"`
239240
240 - `"create_new"`
241
242 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
241 - `BetaOutputBehaviorUpdateExisting object`
243242
244243 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
245244
246245 - `memory_store_id: string`
247246
247 minLength: 1
248
248249 - `type: "update_existing"`
249250
250 - `"update_existing"`
251
252251 - `outputs: array of BetaDreamOutput`
253252
254253 - `memory_store_id: string`
255254
256255 - `type: "memory_store"`
257256
258 - `"memory_store"`
259
260257 - `session_id: string or null`
261258
262259 - `status: BetaDreamStatus`
from line 272
275272
276273 - `type: "dream"`
277274
278 - `"dream"`
279
280275 - `usage: BetaDreamUsage`
281276
282277 Cumulative token usage for the dream across every pipeline stage.
from line 280
285280
286281 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
287282
283 format: int32
284
288285 - `cache_read_input_tokens: number`
289286
290287 Total tokens read from prompt cache.
291288
289 format: int32
290
292291 - `input_tokens: number`
293292
294293 Total uncached input tokens consumed across every pipeline stage.
295294
295 format: int32
296
296297 - `output_tokens: number`
297298
298299 Total output tokens generated across every pipeline stage.
299300
301 format: int32
302
300303### Example
301304
302```http
305```bash
303306curl https://api.anthropic.com/v1/dreams \
304307 -H 'Content-Type: application/json' \
305308 -H 'anthropic-version: 2023-06-01' \
from line 319
316319 }'
317320```
318321
319#### Response
322#### Response (200)
320323
321324```json
322325{
from line 365
362365
363366## List Dreams
364367
365**get** `/v1/dreams`
368**GET** `/v1/dreams`
366369
367370List Dreams
368371
369### Query Parameters
372### Query parameters
370373
371374- `"created_at[gt]": optional string`
372375
373376 Return dreams with `created_at` strictly after this timestamp (exclusive lower bound, RFC 3339). Unset applies no lower bound.
374377
378 format: date-time
379
375380- `"created_at[lt]": optional string`
376381
377382 Return dreams with `created_at` strictly before this timestamp (exclusive upper bound, RFC 3339). Unset applies no upper bound.
378383
384 format: date-time
385
379386- `include_archived: optional boolean`
380387
381388 Query parameter for include_archived
from line 391
384391
385392 Query parameter for limit
386393
394 format: int32
395
387396- `page: optional string`
388397
389398 Query parameter for page
from line 411
402411
403412 - `"canceled"`
404413
405### Header Parameters
414### Headers
406415
407416- `"anthropic-beta": optional array of AnthropicBeta`
408417
from line 499
490499
491500 A timestamp in RFC 3339 format
492501
502 format: date-time
503
493504 - `created_at: string`
494505
495506 A timestamp in RFC 3339 format
496507
508 format: date-time
509
497510 - `ended_at: string or null`
498511
499512 A timestamp in RFC 3339 format
500513
514 format: date-time
515
501516 - `error: BetaDreamError or null`
502517
503518 Failure detail for a Dream whose `status` is `failed`.
from line 523
508523
509524 - `inputs: array of BetaDreamInput`
510525
511 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
526 - `BetaDreamMemoryStoreInput object`
512527
513528 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
514529
515530 - `memory_store_id: string`
516531
532 minLength: 1
533
517534 - `type: "memory_store"`
518535
519 - `"memory_store"`
520
521 - `BetaDreamSessionsInput object { session_ids, type }`
536 - `BetaDreamSessionsInput object`
522537
523538 Input session transcripts the dream reads.
524539
from line 541
526541
527542 - `type: "sessions"`
528543
529 - `"sessions"`
530
531544 - `instructions: string or null`
532545
533546 - `model: BetaDreamModelConfig`
from line 551
538551
539552 Model identifier, e.g. "claude-opus-5". 1-256 characters.
540553
554 minLength: 1, maxLength: 256
555
541556 - `speed: optional "standard" or "fast"`
542557
543558 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 565
550565
551566 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
552567
553 - `BetaOutputBehaviorCreateNew object { type }`
568 - `BetaOutputBehaviorCreateNew object`
554569
555570 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
556571
557572 - `type: "create_new"`
558573
559 - `"create_new"`
560
561 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
574 - `BetaOutputBehaviorUpdateExisting object`
562575
563576 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
564577
565578 - `memory_store_id: string`
566579
580 minLength: 1
581
567582 - `type: "update_existing"`
568583
569 - `"update_existing"`
570
571584 - `outputs: array of BetaDreamOutput`
572585
573586 - `memory_store_id: string`
574587
575588 - `type: "memory_store"`
576589
577 - `"memory_store"`
578
579590 - `session_id: string or null`
580591
581592 - `status: BetaDreamStatus`
from line 605
594605
595606 - `type: "dream"`
596607
597 - `"dream"`
598
599608 - `usage: BetaDreamUsage`
600609
601610 Cumulative token usage for the dream across every pipeline stage.
from line 613
604613
605614 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
606615
616 format: int32
617
607618 - `cache_read_input_tokens: number`
608619
609620 Total tokens read from prompt cache.
610621
622 format: int32
623
611624 - `input_tokens: number`
612625
613626 Total uncached input tokens consumed across every pipeline stage.
614627
628 format: int32
629
615630 - `output_tokens: number`
616631
617632 Total output tokens generated across every pipeline stage.
618633
634 format: int32
635
619636- `next_page: string or null`
620637
621638### Example
622639
623```http
640```bash
624641curl https://api.anthropic.com/v1/dreams \
625642 -H 'anthropic-version: 2023-06-01' \
626643 -H 'anthropic-beta: dreaming-2026-04-21' \
627644 -H "X-Api-Key: $ANTHROPIC_API_KEY"
628645```
629646
630#### Response
647#### Response (200)
631648
632649```json
633650{
from line 695
678695
679696## Get a Dream
680697
681**get** `/v1/dreams/{dream_id}`
698**GET** `/v1/dreams/{dream_id}`
682699
683700Get a Dream
684701
685### Path Parameters
702### Path parameters
686703
687704- `dream_id: string`
688705
689### Header Parameters
706### Headers
690707
691708- `"anthropic-beta": optional array of AnthropicBeta`
692709
from line 783
766783
767784### Returns
768785
769- `BetaDream object { id, archived_at, created_at, 11 more }`
786- `BetaDream object`
770787
771788 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
772789
from line 793
776793
777794 A timestamp in RFC 3339 format
778795
796 format: date-time
797
779798 - `created_at: string`
780799
781800 A timestamp in RFC 3339 format
782801
802 format: date-time
803
783804 - `ended_at: string or null`
784805
785806 A timestamp in RFC 3339 format
786807
808 format: date-time
809
787810 - `error: BetaDreamError or null`
788811
789812 Failure detail for a Dream whose `status` is `failed`.
from line 817
794817
795818 - `inputs: array of BetaDreamInput`
796819
797 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
820 - `BetaDreamMemoryStoreInput object`
798821
799822 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
800823
801824 - `memory_store_id: string`
802825
826 minLength: 1
827
803828 - `type: "memory_store"`
804829
805 - `"memory_store"`
806
807 - `BetaDreamSessionsInput object { session_ids, type }`
830 - `BetaDreamSessionsInput object`
808831
809832 Input session transcripts the dream reads.
810833
from line 835
812835
813836 - `type: "sessions"`
814837
815 - `"sessions"`
816
817838 - `instructions: string or null`
818839
819840 - `model: BetaDreamModelConfig`
from line 845
824845
825846 Model identifier, e.g. "claude-opus-5". 1-256 characters.
826847
848 minLength: 1, maxLength: 256
849
827850 - `speed: optional "standard" or "fast"`
828851
829852 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 859
836859
837860 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
838861
839 - `BetaOutputBehaviorCreateNew object { type }`
862 - `BetaOutputBehaviorCreateNew object`
840863
841864 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
842865
843866 - `type: "create_new"`
844867
845 - `"create_new"`
846
847 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
868 - `BetaOutputBehaviorUpdateExisting object`
848869
849870 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
850871
851872 - `memory_store_id: string`
852873
874 minLength: 1
875
853876 - `type: "update_existing"`
854877
855 - `"update_existing"`
856
857878 - `outputs: array of BetaDreamOutput`
858879
859880 - `memory_store_id: string`
860881
861882 - `type: "memory_store"`
862883
863 - `"memory_store"`
864
865884 - `session_id: string or null`
866885
867886 - `status: BetaDreamStatus`
from line 899
880899
881900 - `type: "dream"`
882901
883 - `"dream"`
884
885902 - `usage: BetaDreamUsage`
886903
887904 Cumulative token usage for the dream across every pipeline stage.
from line 907
890907
891908 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
892909
910 format: int32
911
893912 - `cache_read_input_tokens: number`
894913
895914 Total tokens read from prompt cache.
896915
916 format: int32
917
897918 - `input_tokens: number`
898919
899920 Total uncached input tokens consumed across every pipeline stage.
900921
922 format: int32
923
901924 - `output_tokens: number`
902925
903926 Total output tokens generated across every pipeline stage.
904927
928 format: int32
929
905930### Example
906931
907```http
932```bash
908933curl https://api.anthropic.com/v1/dreams/$DREAM_ID \
909934 -H 'anthropic-version: 2023-06-01' \
910935 -H 'anthropic-beta: dreaming-2026-04-21' \
911936 -H "X-Api-Key: $ANTHROPIC_API_KEY"
912937```
913938
914#### Response
939#### Response (200)
915940
916941```json
917942{
from line 982
957982
958983## Cancel a Dream
959984
960**post** `/v1/dreams/{dream_id}/cancel`
985**POST** `/v1/dreams/{dream_id}/cancel`
961986
962987Cancel a Dream
963988
964### Path Parameters
989### Path parameters
965990
966991- `dream_id: string`
967992
968### Header Parameters
993### Headers
969994
970995- `"anthropic-beta": optional array of AnthropicBeta`
971996
from line 1070
10451070
10461071### Returns
10471072
1048- `BetaDream object { id, archived_at, created_at, 11 more }`
1073- `BetaDream object`
10491074
10501075 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
10511076
from line 1080
10551080
10561081 A timestamp in RFC 3339 format
10571082
1083 format: date-time
1084
10581085 - `created_at: string`
10591086
10601087 A timestamp in RFC 3339 format
10611088
1089 format: date-time
1090
10621091 - `ended_at: string or null`
10631092
10641093 A timestamp in RFC 3339 format
10651094
1095 format: date-time
1096
10661097 - `error: BetaDreamError or null`
10671098
10681099 Failure detail for a Dream whose `status` is `failed`.
from line 1104
10731104
10741105 - `inputs: array of BetaDreamInput`
10751106
1076 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
1107 - `BetaDreamMemoryStoreInput object`
10771108
10781109 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
10791110
10801111 - `memory_store_id: string`
10811112
1113 minLength: 1
1114
10821115 - `type: "memory_store"`
10831116
1084 - `"memory_store"`
1085
1086 - `BetaDreamSessionsInput object { session_ids, type }`
1117 - `BetaDreamSessionsInput object`
10871118
10881119 Input session transcripts the dream reads.
10891120
from line 1122
10911122
10921123 - `type: "sessions"`
10931124
1094 - `"sessions"`
1095
10961125 - `instructions: string or null`
10971126
10981127 - `model: BetaDreamModelConfig`
from line 1132
11031132
11041133 Model identifier, e.g. "claude-opus-5". 1-256 characters.
11051134
1135 minLength: 1, maxLength: 256
1136
11061137 - `speed: optional "standard" or "fast"`
11071138
11081139 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1146
11151146
11161147 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
11171148
1118 - `BetaOutputBehaviorCreateNew object { type }`
1149 - `BetaOutputBehaviorCreateNew object`
11191150
11201151 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
11211152
11221153 - `type: "create_new"`
11231154
1124 - `"create_new"`
1125
1126 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
1155 - `BetaOutputBehaviorUpdateExisting object`
11271156
11281157 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
11291158
11301159 - `memory_store_id: string`
11311160
1161 minLength: 1
1162
11321163 - `type: "update_existing"`
11331164
1134 - `"update_existing"`
1135
11361165 - `outputs: array of BetaDreamOutput`
11371166
11381167 - `memory_store_id: string`
11391168
11401169 - `type: "memory_store"`
11411170
1142 - `"memory_store"`
1143
11441171 - `session_id: string or null`
11451172
11461173 - `status: BetaDreamStatus`
from line 1186
11591186
11601187 - `type: "dream"`
11611188
1162 - `"dream"`
1163
11641189 - `usage: BetaDreamUsage`
11651190
11661191 Cumulative token usage for the dream across every pipeline stage.
from line 1194
11691194
11701195 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
11711196
1197 format: int32
1198
11721199 - `cache_read_input_tokens: number`
11731200
11741201 Total tokens read from prompt cache.
11751202
1203 format: int32
1204
11761205 - `input_tokens: number`
11771206
11781207 Total uncached input tokens consumed across every pipeline stage.
11791208
1209 format: int32
1210
11801211 - `output_tokens: number`
11811212
11821213 Total output tokens generated across every pipeline stage.
11831214
1215 format: int32
1216
11841217### Example
11851218
1186```http
1219```bash
11871220curl https://api.anthropic.com/v1/dreams/$DREAM_ID/cancel \
11881221 -X POST \
11891222 -H 'anthropic-version: 2023-06-01' \
from line 1224
11911224 -H "X-Api-Key: $ANTHROPIC_API_KEY"
11921225```
11931226
1194#### Response
1227#### Response (200)
11951228
11961229```json
11971230{
from line 1270
12371270
12381271## Archive a Dream
12391272
1240**post** `/v1/dreams/{dream_id}/archive`
1273**POST** `/v1/dreams/{dream_id}/archive`
12411274
12421275Archive a Dream
12431276
1244### Path Parameters
1277### Path parameters
12451278
12461279- `dream_id: string`
12471280
1248### Header Parameters
1281### Headers
12491282
12501283- `"anthropic-beta": optional array of AnthropicBeta`
12511284
from line 1358
13251358
13261359### Returns
13271360
1328- `BetaDream object { id, archived_at, created_at, 11 more }`
1361- `BetaDream object`
13291362
13301363 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
13311364
from line 1368
13351368
13361369 A timestamp in RFC 3339 format
13371370
1371 format: date-time
1372
13381373 - `created_at: string`
13391374
13401375 A timestamp in RFC 3339 format
13411376
1377 format: date-time
1378
13421379 - `ended_at: string or null`
13431380
13441381 A timestamp in RFC 3339 format
13451382
1383 format: date-time
1384
13461385 - `error: BetaDreamError or null`
13471386
13481387 Failure detail for a Dream whose `status` is `failed`.
from line 1392
13531392
13541393 - `inputs: array of BetaDreamInput`
13551394
1356 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
1395 - `BetaDreamMemoryStoreInput object`
13571396
13581397 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
13591398
13601399 - `memory_store_id: string`
13611400
1401 minLength: 1
1402
13621403 - `type: "memory_store"`
13631404
1364 - `"memory_store"`
1365
1366 - `BetaDreamSessionsInput object { session_ids, type }`
1405 - `BetaDreamSessionsInput object`
13671406
13681407 Input session transcripts the dream reads.
13691408
from line 1410
13711410
13721411 - `type: "sessions"`
13731412
1374 - `"sessions"`
1375
13761413 - `instructions: string or null`
13771414
13781415 - `model: BetaDreamModelConfig`
from line 1420
13831420
13841421 Model identifier, e.g. "claude-opus-5". 1-256 characters.
13851422
1423 minLength: 1, maxLength: 256
1424
13861425 - `speed: optional "standard" or "fast"`
13871426
13881427 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1434
13951434
13961435 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
13971436
1398 - `BetaOutputBehaviorCreateNew object { type }`
1437 - `BetaOutputBehaviorCreateNew object`
13991438
14001439 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
14011440
14021441 - `type: "create_new"`
14031442
1404 - `"create_new"`
1405
1406 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
1443 - `BetaOutputBehaviorUpdateExisting object`
14071444
14081445 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
14091446
14101447 - `memory_store_id: string`
14111448
1449 minLength: 1
1450
14121451 - `type: "update_existing"`
14131452
1414 - `"update_existing"`
1415
14161453 - `outputs: array of BetaDreamOutput`
14171454
14181455 - `memory_store_id: string`
14191456
14201457 - `type: "memory_store"`
14211458
1422 - `"memory_store"`
1423
14241459 - `session_id: string or null`
14251460
14261461 - `status: BetaDreamStatus`
from line 1474
14391474
14401475 - `type: "dream"`
14411476
1442 - `"dream"`
1443
14441477 - `usage: BetaDreamUsage`
14451478
14461479 Cumulative token usage for the dream across every pipeline stage.
from line 1482
14491482
14501483 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
14511484
1485 format: int32
1486
14521487 - `cache_read_input_tokens: number`
14531488
14541489 Total tokens read from prompt cache.
14551490
1491 format: int32
1492
14561493 - `input_tokens: number`
14571494
14581495 Total uncached input tokens consumed across every pipeline stage.
14591496
1497 format: int32
1498
14601499 - `output_tokens: number`
14611500
14621501 Total output tokens generated across every pipeline stage.
14631502
1503 format: int32
1504
14641505### Example
14651506
1466```http
1507```bash
14671508curl https://api.anthropic.com/v1/dreams/$DREAM_ID/archive \
14681509 -X POST \
14691510 -H 'anthropic-version: 2023-06-01' \
from line 1512
14711512 -H "X-Api-Key: $ANTHROPIC_API_KEY"
14721513```
14731514
1474#### Response
1515#### Response (200)
14751516
14761517```json
14771518{
from line 1556
15151556}
15161557```
15171558
1518## Domain Types
1559## Domain types
15191560
15201561### Beta Dream
15211562
1522- `BetaDream object { id, archived_at, created_at, 11 more }`
1563- `BetaDream object`
15231564
15241565 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
15251566
from line 1570
15291570
15301571 A timestamp in RFC 3339 format
15311572
1573 format: date-time
1574
15321575 - `created_at: string`
15331576
15341577 A timestamp in RFC 3339 format
15351578
1579 format: date-time
1580
15361581 - `ended_at: string or null`
15371582
15381583 A timestamp in RFC 3339 format
15391584
1585 format: date-time
1586
15401587 - `error: BetaDreamError or null`
15411588
15421589 Failure detail for a Dream whose `status` is `failed`.
from line 1594
15471594
15481595 - `inputs: array of BetaDreamInput`
15491596
1550 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
1597 - `BetaDreamMemoryStoreInput object`
15511598
15521599 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
15531600
15541601 - `memory_store_id: string`
15551602
1603 minLength: 1
1604
15561605 - `type: "memory_store"`
15571606
1558 - `"memory_store"`
1559
1560 - `BetaDreamSessionsInput object { session_ids, type }`
1607 - `BetaDreamSessionsInput object`
15611608
15621609 Input session transcripts the dream reads.
15631610
from line 1612
15651612
15661613 - `type: "sessions"`
15671614
1568 - `"sessions"`
1569
15701615 - `instructions: string or null`
15711616
15721617 - `model: BetaDreamModelConfig`
from line 1622
15771622
15781623 Model identifier, e.g. "claude-opus-5". 1-256 characters.
15791624
1625 minLength: 1, maxLength: 256
1626
15801627 - `speed: optional "standard" or "fast"`
15811628
15821629 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1636
15891636
15901637 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
15911638
1592 - `BetaOutputBehaviorCreateNew object { type }`
1639 - `BetaOutputBehaviorCreateNew object`
15931640
15941641 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
15951642
15961643 - `type: "create_new"`
15971644
1598 - `"create_new"`
1599
1600 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
1645 - `BetaOutputBehaviorUpdateExisting object`
16011646
16021647 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
16031648
16041649 - `memory_store_id: string`
16051650
1651 minLength: 1
1652
16061653 - `type: "update_existing"`
16071654
1608 - `"update_existing"`
1609
16101655 - `outputs: array of BetaDreamOutput`
16111656
16121657 - `memory_store_id: string`
16131658
16141659 - `type: "memory_store"`
16151660
1616 - `"memory_store"`
1617
16181661 - `session_id: string or null`
16191662
16201663 - `status: BetaDreamStatus`
from line 1676
16331676
16341677 - `type: "dream"`
16351678
1636 - `"dream"`
1637
16381679 - `usage: BetaDreamUsage`
16391680
16401681 Cumulative token usage for the dream across every pipeline stage.
from line 1684
16431684
16441685 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
16451686
1687 format: int32
1688
16461689 - `cache_read_input_tokens: number`
16471690
16481691 Total tokens read from prompt cache.
16491692
1693 format: int32
1694
16501695 - `input_tokens: number`
16511696
16521697 Total uncached input tokens consumed across every pipeline stage.
16531698
1699 format: int32
1700
16541701 - `output_tokens: number`
16551702
16561703 Total output tokens generated across every pipeline stage.
16571704
1705 format: int32
1706
16581707### Beta Dream Error
16591708
1660- `BetaDreamError object { message, type }`
1709- `BetaDreamError object`
16611710
16621711 Failure detail for a Dream whose `status` is `failed`.
16631712
from line 1720
16711720
16721721 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
16731722
1674 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
1723 - `BetaDreamMemoryStoreInput object`
16751724
16761725 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
16771726
16781727 - `memory_store_id: string`
16791728
1729 minLength: 1
1730
16801731 - `type: "memory_store"`
16811732
1682 - `"memory_store"`
1683
1684 - `BetaDreamSessionsInput object { session_ids, type }`
1733 - `BetaDreamSessionsInput object`
16851734
16861735 Input session transcripts the dream reads.
16871736
from line 1738
16891738
16901739 - `type: "sessions"`
16911740
1692 - `"sessions"`
1693
16941741### Beta Dream Memory Store Input
16951742
1696- `BetaDreamMemoryStoreInput object { memory_store_id, type }`
1743- `BetaDreamMemoryStoreInput object`
16971744
16981745 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
16991746
17001747 - `memory_store_id: string`
17011748
1749 minLength: 1
1750
17021751 - `type: "memory_store"`
17031752
1704 - `"memory_store"`
1705
17061753### Beta Dream Memory Store Output
17071754
1708- `BetaDreamMemoryStoreOutput object { memory_store_id, type }`
1755- `BetaDreamMemoryStoreOutput object`
17091756
17101757 An output memory store the dream writes consolidated memories into.
17111758
from line 1760
17131760
17141761 - `type: "memory_store"`
17151762
1716 - `"memory_store"`
1717
17181763### Beta Dream Model Config
17191764
1720- `BetaDreamModelConfig object { id, speed }`
1765- `BetaDreamModelConfig object`
17211766
17221767 Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.
17231768
from line 1770
17251770
17261771 Model identifier, e.g. "claude-opus-5". 1-256 characters.
17271772
1773 minLength: 1, maxLength: 256
1774
17281775 - `speed: optional "standard" or "fast"`
17291776
17301777 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1782
17351782
17361783### Beta Dream Model Config Param
17371784
1738- `BetaDreamModelConfigParam object { id, speed }`
1785- `BetaDreamModelConfigParam object`
17391786
17401787 Model identifier and configuration applied to every pipeline stage.
17411788
from line 1790
17431790
17441791 Model identifier, e.g. "claude-opus-5". 1-256 characters.
17451792
1793 minLength: 1, maxLength: 256
1794
17461795 - `speed: optional "standard" or "fast" or null`
17471796
17481797 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1802
17531802
17541803### Beta Dream Output
17551804
1756- `BetaDreamOutput object { memory_store_id, type }`
1805- `BetaDreamOutput object`
17571806
17581807 An output memory store the dream writes consolidated memories into.
17591808
from line 1810
17611810
17621811 - `type: "memory_store"`
17631812
1764 - `"memory_store"`
1765
17661813### Beta Dream Sessions Input
17671814
1768- `BetaDreamSessionsInput object { session_ids, type }`
1815- `BetaDreamSessionsInput object`
17691816
17701817 Input session transcripts the dream reads.
17711818
from line 1820
17731820
17741821 - `type: "sessions"`
17751822
1776 - `"sessions"`
1777
17781823### Beta Dream Status
17791824
17801825- `BetaDreamStatus = "pending" or "running" or "completed" or 2 more`
from line 1838
17931838
17941839### Beta Dream Usage
17951840
1796- `BetaDreamUsage object { cache_creation_input_tokens, cache_read_input_tokens, input_tokens, output_tokens }`
1841- `BetaDreamUsage object`
17971842
17981843 Cumulative token usage for the dream across every pipeline stage.
17991844
from line 1846
18011846
18021847 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
18031848
1849 format: int32
1850
18041851 - `cache_read_input_tokens: number`
18051852
18061853 Total tokens read from prompt cache.
18071854
1855 format: int32
1856
18081857 - `input_tokens: number`
18091858
18101859 Total uncached input tokens consumed across every pipeline stage.
18111860
1861 format: int32
1862
18121863 - `output_tokens: number`
18131864
18141865 Total output tokens generated across every pipeline stage.
18151866
1867 format: int32
1868
18161869### Beta Output Behavior
18171870
18181871- `BetaOutputBehavior = BetaOutputBehaviorCreateNew or BetaOutputBehaviorUpdateExisting`
18191872
18201873 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
18211874
1822 - `BetaOutputBehaviorCreateNew object { type }`
1875 - `BetaOutputBehaviorCreateNew object`
18231876
18241877 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
18251878
18261879 - `type: "create_new"`
18271880
1828 - `"create_new"`
1829
1830 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
1881 - `BetaOutputBehaviorUpdateExisting object`
18311882
18321883 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
18331884
18341885 - `memory_store_id: string`
18351886
1887 minLength: 1
1888
18361889 - `type: "update_existing"`
18371890
1838 - `"update_existing"`
1839
18401891### Beta Output Behavior Create New
18411892
1842- `BetaOutputBehaviorCreateNew object { type }`
1893- `BetaOutputBehaviorCreateNew object`
18431894
18441895 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
18451896
18461897 - `type: "create_new"`
18471898
1848 - `"create_new"`
1849
18501899### Beta Output Behavior Update Existing
18511900
1852- `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
1901- `BetaOutputBehaviorUpdateExisting object`
18531902
18541903 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
18551904
18561905 - `memory_store_id: string`
18571906
1907 minLength: 1
1908
18581909 - `type: "update_existing"`
1859
1860 - `"update_existing"`
18611910
api/beta/dreams/archive Changed · +36 / -33 lines
# Archive a Dream ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Archive a Dream ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Archive a Dream
3url: https://platform.claude.com/docs/en/api/beta/dreams/archive
4---
1# Archive a Dream
52
6## Archive a Dream
3**POST** `/v1/dreams/{dream_id}/archive`
74
8**post** `/v1/dreams/{dream_id}/archive`
9
105Archive a Dream
116
12### Path Parameters
7## Path parameters
138
149- `dream_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaDream object { id, archived_at, created_at, 11 more }`
91- `BetaDream object`
9792
9893 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
9994
from line 98
10398
10499 A timestamp in RFC 3339 format
105100
101 format: date-time
102
106103 - `created_at: string`
107104
108105 A timestamp in RFC 3339 format
109106
107 format: date-time
108
110109 - `ended_at: string or null`
111110
112111 A timestamp in RFC 3339 format
113112
113 format: date-time
114
114115 - `error: BetaDreamError or null`
115116
116117 Failure detail for a Dream whose `status` is `failed`.
from line 122
121122
122123 - `inputs: array of BetaDreamInput`
123124
124 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
125 - `BetaDreamMemoryStoreInput object`
125126
126127 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
127128
128129 - `memory_store_id: string`
129130
131 minLength: 1
132
130133 - `type: "memory_store"`
131134
132 - `"memory_store"`
135 - `BetaDreamSessionsInput object`
133136
134 - `BetaDreamSessionsInput object { session_ids, type }`
135
136137 Input session transcripts the dream reads.
137138
138139 - `session_ids: array of string`
from line 140
139140
140141 - `type: "sessions"`
141142
142 - `"sessions"`
143
144143 - `instructions: string or null`
145144
146145 - `model: BetaDreamModelConfig`
from line 150
151150
152151 Model identifier, e.g. "claude-opus-5". 1-256 characters.
153152
153 minLength: 1, maxLength: 256
154
154155 - `speed: optional "standard" or "fast"`
155156
156157 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 164
163164
164165 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
165166
166 - `BetaOutputBehaviorCreateNew object { type }`
167 - `BetaOutputBehaviorCreateNew object`
167168
168169 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
169170
170171 - `type: "create_new"`
171172
172 - `"create_new"`
173 - `BetaOutputBehaviorUpdateExisting object`
173174
174 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
175
176175 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
177176
178177 - `memory_store_id: string`
179178
179 minLength: 1
180
180181 - `type: "update_existing"`
181182
182 - `"update_existing"`
183
184183 - `outputs: array of BetaDreamOutput`
185184
186185 - `memory_store_id: string`
from line 186
187186
188187 - `type: "memory_store"`
189188
190 - `"memory_store"`
191
192189 - `session_id: string or null`
193190
194191 - `status: BetaDreamStatus`
from line 204
207204
208205 - `type: "dream"`
209206
210 - `"dream"`
211
212207 - `usage: BetaDreamUsage`
213208
214209 Cumulative token usage for the dream across every pipeline stage.
from line 212
217212
218213 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
219214
215 format: int32
216
220217 - `cache_read_input_tokens: number`
221218
222219 Total tokens read from prompt cache.
223220
221 format: int32
222
224223 - `input_tokens: number`
225224
226225 Total uncached input tokens consumed across every pipeline stage.
227226
227 format: int32
228
228229 - `output_tokens: number`
229230
230231 Total output tokens generated across every pipeline stage.
231232
232### Example
233 format: int32
233234
234```http
235## Example
236
237```bash
235238curl https://api.anthropic.com/v1/dreams/$DREAM_ID/archive \
236239 -X POST \
237240 -H 'anthropic-version: 2023-06-01' \
from line 242
239242 -H "X-Api-Key: $ANTHROPIC_API_KEY"
240243```
241244
242#### Response
245### Response (200)
243246
244247```json
245248{
api/beta/dreams/cancel Changed · +36 / -33 lines
# Cancel a Dream ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Cancel a Dream ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Cancel a Dream
3url: https://platform.claude.com/docs/en/api/beta/dreams/cancel
4---
1# Cancel a Dream
52
6## Cancel a Dream
3**POST** `/v1/dreams/{dream_id}/cancel`
74
8**post** `/v1/dreams/{dream_id}/cancel`
9
105Cancel a Dream
116
12### Path Parameters
7## Path parameters
138
149- `dream_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaDream object { id, archived_at, created_at, 11 more }`
91- `BetaDream object`
9792
9893 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
9994
from line 98
10398
10499 A timestamp in RFC 3339 format
105100
101 format: date-time
102
106103 - `created_at: string`
107104
108105 A timestamp in RFC 3339 format
109106
107 format: date-time
108
110109 - `ended_at: string or null`
111110
112111 A timestamp in RFC 3339 format
113112
113 format: date-time
114
114115 - `error: BetaDreamError or null`
115116
116117 Failure detail for a Dream whose `status` is `failed`.
from line 122
121122
122123 - `inputs: array of BetaDreamInput`
123124
124 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
125 - `BetaDreamMemoryStoreInput object`
125126
126127 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
127128
128129 - `memory_store_id: string`
129130
131 minLength: 1
132
130133 - `type: "memory_store"`
131134
132 - `"memory_store"`
135 - `BetaDreamSessionsInput object`
133136
134 - `BetaDreamSessionsInput object { session_ids, type }`
135
136137 Input session transcripts the dream reads.
137138
138139 - `session_ids: array of string`
from line 140
139140
140141 - `type: "sessions"`
141142
142 - `"sessions"`
143
144143 - `instructions: string or null`
145144
146145 - `model: BetaDreamModelConfig`
from line 150
151150
152151 Model identifier, e.g. "claude-opus-5". 1-256 characters.
153152
153 minLength: 1, maxLength: 256
154
154155 - `speed: optional "standard" or "fast"`
155156
156157 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 164
163164
164165 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
165166
166 - `BetaOutputBehaviorCreateNew object { type }`
167 - `BetaOutputBehaviorCreateNew object`
167168
168169 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
169170
170171 - `type: "create_new"`
171172
172 - `"create_new"`
173 - `BetaOutputBehaviorUpdateExisting object`
173174
174 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
175
176175 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
177176
178177 - `memory_store_id: string`
179178
179 minLength: 1
180
180181 - `type: "update_existing"`
181182
182 - `"update_existing"`
183
184183 - `outputs: array of BetaDreamOutput`
185184
186185 - `memory_store_id: string`
from line 186
187186
188187 - `type: "memory_store"`
189188
190 - `"memory_store"`
191
192189 - `session_id: string or null`
193190
194191 - `status: BetaDreamStatus`
from line 204
207204
208205 - `type: "dream"`
209206
210 - `"dream"`
211
212207 - `usage: BetaDreamUsage`
213208
214209 Cumulative token usage for the dream across every pipeline stage.
from line 212
217212
218213 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
219214
215 format: int32
216
220217 - `cache_read_input_tokens: number`
221218
222219 Total tokens read from prompt cache.
223220
221 format: int32
222
224223 - `input_tokens: number`
225224
226225 Total uncached input tokens consumed across every pipeline stage.
227226
227 format: int32
228
228229 - `output_tokens: number`
229230
230231 Total output tokens generated across every pipeline stage.
231232
232### Example
233 format: int32
233234
234```http
235## Example
236
237```bash
235238curl https://api.anthropic.com/v1/dreams/$DREAM_ID/cancel \
236239 -X POST \
237240 -H 'anthropic-version: 2023-06-01' \
from line 242
239242 -H "X-Api-Key: $ANTHROPIC_API_KEY"
240243```
241244
242#### Response
245### Response (200)
243246
244247```json
245248{
api/beta/dreams/create Changed · +49 / -46 lines
# Create a Dream ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create a Dream ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Create a Dream
3url: https://platform.claude.com/docs/en/api/beta/dreams/create
4---
1# Create a Dream
52
6## Create a Dream
3**POST** `/v1/dreams`
74
8**post** `/v1/dreams`
9
105Create a Dream
116
12### Header Parameters
7## Headers
138
149- `"anthropic-beta": optional array of AnthropicBeta`
1510
from line 82
8782
8883 - `"mid-conversation-tool-changes-2026-07-01"`
8984
90### Body Parameters
85## Body parameters
9186
9287- `inputs: array of BetaDreamInput`
9388
94 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
89 - `BetaDreamMemoryStoreInput object`
9590
9691 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
9792
9893 - `memory_store_id: string`
9994
95 minLength: 1
96
10097 - `type: "memory_store"`
10198
102 - `"memory_store"`
99 - `BetaDreamSessionsInput object`
103100
104 - `BetaDreamSessionsInput object { session_ids, type }`
105
106101 Input session transcripts the dream reads.
107102
108103 - `session_ids: array of string`
from line 104
109104
110105 - `type: "sessions"`
111106
112 - `"sessions"`
113
114107- `model: string or BetaDreamModelConfigParam`
115108
116109 Model identifier and configuration applied to every pipeline stage.
from line 110
117110
118111 - `string`
119112
120 - `BetaDreamModelConfigParam object { id, speed }`
113 - `BetaDreamModelConfigParam object`
121114
122115 Model identifier and configuration applied to every pipeline stage.
123116
from line 118
125118
126119 Model identifier, e.g. "claude-opus-5". 1-256 characters.
127120
121 minLength: 1, maxLength: 256
122
128123 - `speed: optional "standard" or "fast" or null`
129124
130125 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 130
135130
136131- `instructions: optional string or null`
137132
133 minLength: 1, maxLength: 4096
134
138135- `output_behavior: optional BetaOutputBehavior`
139136
140137 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
141138
142 - `BetaOutputBehaviorCreateNew object { type }`
139 - `BetaOutputBehaviorCreateNew object`
143140
144141 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
145142
146143 - `type: "create_new"`
147144
148 - `"create_new"`
145 - `BetaOutputBehaviorUpdateExisting object`
149146
150 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
151
152147 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
153148
154149 - `memory_store_id: string`
155150
151 minLength: 1
152
156153 - `type: "update_existing"`
157154
158 - `"update_existing"`
155## Returns
159156
160### Returns
157- `BetaDream object`
161158
162- `BetaDream object { id, archived_at, created_at, 11 more }`
163
164159 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
165160
166161 - `id: string`
from line 164
169164
170165 A timestamp in RFC 3339 format
171166
167 format: date-time
168
172169 - `created_at: string`
173170
174171 A timestamp in RFC 3339 format
175172
173 format: date-time
174
176175 - `ended_at: string or null`
177176
178177 A timestamp in RFC 3339 format
179178
179 format: date-time
180
180181 - `error: BetaDreamError or null`
181182
182183 Failure detail for a Dream whose `status` is `failed`.
from line 188
187188
188189 - `inputs: array of BetaDreamInput`
189190
190 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
191 - `BetaDreamMemoryStoreInput object`
191192
192193 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
193194
194195 - `memory_store_id: string`
195196
197 minLength: 1
198
196199 - `type: "memory_store"`
197200
198 - `"memory_store"`
201 - `BetaDreamSessionsInput object`
199202
200 - `BetaDreamSessionsInput object { session_ids, type }`
201
202203 Input session transcripts the dream reads.
203204
204205 - `session_ids: array of string`
from line 206
205206
206207 - `type: "sessions"`
207208
208 - `"sessions"`
209
210209 - `instructions: string or null`
211210
212211 - `model: BetaDreamModelConfig`
from line 216
217216
218217 Model identifier, e.g. "claude-opus-5". 1-256 characters.
219218
219 minLength: 1, maxLength: 256
220
220221 - `speed: optional "standard" or "fast"`
221222
222223 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 230
229230
230231 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
231232
232 - `BetaOutputBehaviorCreateNew object { type }`
233 - `BetaOutputBehaviorCreateNew object`
233234
234235 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
235236
236237 - `type: "create_new"`
237238
238 - `"create_new"`
239 - `BetaOutputBehaviorUpdateExisting object`
239240
240 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
241
242241 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
243242
244243 - `memory_store_id: string`
245244
245 minLength: 1
246
246247 - `type: "update_existing"`
247248
248 - `"update_existing"`
249
250249 - `outputs: array of BetaDreamOutput`
251250
252251 - `memory_store_id: string`
from line 252
253252
254253 - `type: "memory_store"`
255254
256 - `"memory_store"`
257
258255 - `session_id: string or null`
259256
260257 - `status: BetaDreamStatus`
from line 270
273270
274271 - `type: "dream"`
275272
276 - `"dream"`
277
278273 - `usage: BetaDreamUsage`
279274
280275 Cumulative token usage for the dream across every pipeline stage.
from line 278
283278
284279 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
285280
281 format: int32
282
286283 - `cache_read_input_tokens: number`
287284
288285 Total tokens read from prompt cache.
289286
287 format: int32
288
290289 - `input_tokens: number`
291290
292291 Total uncached input tokens consumed across every pipeline stage.
293292
293 format: int32
294
294295 - `output_tokens: number`
295296
296297 Total output tokens generated across every pipeline stage.
297298
298### Example
299 format: int32
299300
300```http
301## Example
302
303```bash
301304curl https://api.anthropic.com/v1/dreams \
302305 -H 'Content-Type: application/json' \
303306 -H 'anthropic-version: 2023-06-01' \
from line 317
314317 }'
315318```
316319
317#### Response
320### Response (200)
318321
319322```json
320323{
api/beta/dreams/list Changed · +40 / -31 lines
# List Dreams ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Dreams ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Dreams
3url: https://platform.claude.com/docs/en/api/beta/dreams/list
4---
1# List Dreams
52
6## List Dreams
3**GET** `/v1/dreams`
74
8**get** `/v1/dreams`
9
105List Dreams
116
12### Query Parameters
7## Query parameters
138
149- `"created_at[gt]": optional string`
1510
1611 Return dreams with `created_at` strictly after this timestamp (exclusive lower bound, RFC 3339). Unset applies no lower bound.
1712
13 format: date-time
14
1815- `"created_at[lt]": optional string`
1916
2017 Return dreams with `created_at` strictly before this timestamp (exclusive upper bound, RFC 3339). Unset applies no upper bound.
2118
19 format: date-time
20
2221- `include_archived: optional boolean`
2322
2423 Query parameter for include_archived
from line 26
2726
2827 Query parameter for limit
2928
29 format: int32
30
3031- `page: optional string`
3132
3233 Query parameter for page
from line 46
4546
4647 - `"canceled"`
4748
48### Header Parameters
49## Headers
4950
5051- `"anthropic-beta": optional array of AnthropicBeta`
5152
from line 124
123124
124125 - `"mid-conversation-tool-changes-2026-07-01"`
125126
126### Returns
127## Returns
127128
128129- `data: array of BetaDream`
129130
from line 134
133134
134135 A timestamp in RFC 3339 format
135136
137 format: date-time
138
136139 - `created_at: string`
137140
138141 A timestamp in RFC 3339 format
139142
143 format: date-time
144
140145 - `ended_at: string or null`
141146
142147 A timestamp in RFC 3339 format
143148
149 format: date-time
150
144151 - `error: BetaDreamError or null`
145152
146153 Failure detail for a Dream whose `status` is `failed`.
from line 158
151158
152159 - `inputs: array of BetaDreamInput`
153160
154 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
161 - `BetaDreamMemoryStoreInput object`
155162
156163 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
157164
158165 - `memory_store_id: string`
159166
167 minLength: 1
168
160169 - `type: "memory_store"`
161170
162 - `"memory_store"`
171 - `BetaDreamSessionsInput object`
163172
164 - `BetaDreamSessionsInput object { session_ids, type }`
165
166173 Input session transcripts the dream reads.
167174
168175 - `session_ids: array of string`
from line 176
169176
170177 - `type: "sessions"`
171178
172 - `"sessions"`
173
174179 - `instructions: string or null`
175180
176181 - `model: BetaDreamModelConfig`
from line 186
181186
182187 Model identifier, e.g. "claude-opus-5". 1-256 characters.
183188
189 minLength: 1, maxLength: 256
190
184191 - `speed: optional "standard" or "fast"`
185192
186193 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 200
193200
194201 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
195202
196 - `BetaOutputBehaviorCreateNew object { type }`
203 - `BetaOutputBehaviorCreateNew object`
197204
198205 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
199206
200207 - `type: "create_new"`
201208
202 - `"create_new"`
209 - `BetaOutputBehaviorUpdateExisting object`
203210
204 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
205
206211 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
207212
208213 - `memory_store_id: string`
209214
215 minLength: 1
216
210217 - `type: "update_existing"`
211218
212 - `"update_existing"`
213
214219 - `outputs: array of BetaDreamOutput`
215220
216221 - `memory_store_id: string`
from line 222
217222
218223 - `type: "memory_store"`
219224
220 - `"memory_store"`
221
222225 - `session_id: string or null`
223226
224227 - `status: BetaDreamStatus`
from line 240
237240
238241 - `type: "dream"`
239242
240 - `"dream"`
241
242243 - `usage: BetaDreamUsage`
243244
244245 Cumulative token usage for the dream across every pipeline stage.
from line 248
247248
248249 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
249250
251 format: int32
252
250253 - `cache_read_input_tokens: number`
251254
252255 Total tokens read from prompt cache.
253256
257 format: int32
258
254259 - `input_tokens: number`
255260
256261 Total uncached input tokens consumed across every pipeline stage.
257262
263 format: int32
264
258265 - `output_tokens: number`
259266
260267 Total output tokens generated across every pipeline stage.
261268
269 format: int32
270
262271- `next_page: string or null`
263272
264### Example
273## Example
265274
266```http
275```bash
267276curl https://api.anthropic.com/v1/dreams \
268277 -H 'anthropic-version: 2023-06-01' \
269278 -H 'anthropic-beta: dreaming-2026-04-21' \
from line 279
270279 -H "X-Api-Key: $ANTHROPIC_API_KEY"
271280```
272281
273#### Response
282### Response (200)
274283
275284```json
276285{
api/beta/dreams/retrieve Changed · +36 / -33 lines
# Get a Dream ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get a Dream ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get a Dream
3url: https://platform.claude.com/docs/en/api/beta/dreams/retrieve
4---
1# Get a Dream
52
6## Get a Dream
3**GET** `/v1/dreams/{dream_id}`
74
8**get** `/v1/dreams/{dream_id}`
9
105Get a Dream
116
12### Path Parameters
7## Path parameters
138
149- `dream_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaDream object { id, archived_at, created_at, 11 more }`
91- `BetaDream object`
9792
9893 An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.
9994
from line 98
10398
10499 A timestamp in RFC 3339 format
105100
101 format: date-time
102
106103 - `created_at: string`
107104
108105 A timestamp in RFC 3339 format
109106
107 format: date-time
108
110109 - `ended_at: string or null`
111110
112111 A timestamp in RFC 3339 format
113112
113 format: date-time
114
114115 - `error: BetaDreamError or null`
115116
116117 Failure detail for a Dream whose `status` is `failed`.
from line 122
121122
122123 - `inputs: array of BetaDreamInput`
123124
124 - `BetaDreamMemoryStoreInput object { memory_store_id, type }`
125 - `BetaDreamMemoryStoreInput object`
125126
126127 An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.
127128
128129 - `memory_store_id: string`
129130
131 minLength: 1
132
130133 - `type: "memory_store"`
131134
132 - `"memory_store"`
135 - `BetaDreamSessionsInput object`
133136
134 - `BetaDreamSessionsInput object { session_ids, type }`
135
136137 Input session transcripts the dream reads.
137138
138139 - `session_ids: array of string`
from line 140
139140
140141 - `type: "sessions"`
141142
142 - `"sessions"`
143
144143 - `instructions: string or null`
145144
146145 - `model: BetaDreamModelConfig`
from line 150
151150
152151 Model identifier, e.g. "claude-opus-5". 1-256 characters.
153152
153 minLength: 1, maxLength: 256
154
154155 - `speed: optional "standard" or "fast"`
155156
156157 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 164
163164
164165 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
165166
166 - `BetaOutputBehaviorCreateNew object { type }`
167 - `BetaOutputBehaviorCreateNew object`
167168
168169 The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.
169170
170171 - `type: "create_new"`
171172
172 - `"create_new"`
173 - `BetaOutputBehaviorUpdateExisting object`
173174
174 - `BetaOutputBehaviorUpdateExisting object { memory_store_id, type }`
175
176175 The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
177176
178177 - `memory_store_id: string`
179178
179 minLength: 1
180
180181 - `type: "update_existing"`
181182
182 - `"update_existing"`
183
184183 - `outputs: array of BetaDreamOutput`
185184
186185 - `memory_store_id: string`
from line 186
187186
188187 - `type: "memory_store"`
189188
190 - `"memory_store"`
191
192189 - `session_id: string or null`
193190
194191 - `status: BetaDreamStatus`
from line 204
207204
208205 - `type: "dream"`
209206
210 - `"dream"`
211
212207 - `usage: BetaDreamUsage`
213208
214209 Cumulative token usage for the dream across every pipeline stage.
from line 212
217212
218213 Total tokens used to create prompt-cache entries (sum of all TTL tiers).
219214
215 format: int32
216
220217 - `cache_read_input_tokens: number`
221218
222219 Total tokens read from prompt cache.
223220
221 format: int32
222
224223 - `input_tokens: number`
225224
226225 Total uncached input tokens consumed across every pipeline stage.
227226
227 format: int32
228
228229 - `output_tokens: number`
229230
230231 Total output tokens generated across every pipeline stage.
231232
232### Example
233 format: int32
233234
234```http
235## Example
236
237```bash
235238curl https://api.anthropic.com/v1/dreams/$DREAM_ID \
236239 -H 'anthropic-version: 2023-06-01' \
237240 -H 'anthropic-beta: dreaming-2026-04-21' \
from line 241
238241 -H "X-Api-Key: $ANTHROPIC_API_KEY"
239242```
240243
241#### Response
244### Response (200)
242245
243246```json
244247{
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 more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Environments
3url: https://platform.claude.com/docs/en/api/beta/environments
4---
5
61# Environments
72
83## Create Environment
94
10**post** `/v1/environments`
5**POST** `/v1/environments`
116
127Create a new environment with the specified configuration.
138
14### Header Parameters
9### Headers
1510
1611- `"anthropic-beta": optional array of AnthropicBeta`
1712
from line 84
8984
9085 - `"mid-conversation-tool-changes-2026-07-01"`
9186
92### Body Parameters
87### Body parameters
9388
9489- `name: string`
9590
9691 Human-readable name for the environment
9792
93 maxLength: 256, minLength: 1
94
9895- `config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams or null`
9996
10097 Environment configuration
10198
102 - `BetaCloudConfigParams object { type, networking, packages }`
99 - `BetaCloudConfigParams object`
103100
104101 Request params for `cloud` environment configuration.
105102
from line 107
110107
111108 Environment type
112109
113 - `"cloud"`
114
115110 - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null`
116111
117112 Network configuration policy. Omit on update to preserve the existing value.
118113
119 - `BetaUnrestrictedNetwork object { type }`
114 - `BetaUnrestrictedNetwork object`
120115
121116 Unrestricted network access.
122117
from line 119
124119
125120 Network policy type
126121
127 - `"unrestricted"`
128
129 - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }`
122 - `BetaLimitedNetworkParams object`
130123
131124 Limited network request params.
132125
from line 130
137130
138131 Network policy type
139132
140 - `"limited"`
141
142133 - `allow_mcp_servers: optional boolean or null`
143134
144135 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
185176
186177 Package configuration type
187178
188 - `"packages"`
189
190 - `BetaSelfHostedConfigParams object { type }`
179 default: packages
180
181 - `BetaSelfHostedConfigParams object`
191182
192183 Request params for `self_hosted` environment configuration.
193184
from line 186
195186
196187 Environment type
197188
198 - `"self_hosted"`
199
200189- `description: optional string or null`
201190
202191 Optional description of the environment
203192
193 maxLength: 1024
194
204195- `metadata: optional map[string]`
205196
206197 User-provided metadata key-value pairs
from line 206
215206
216207### Returns
217208
218- `BetaEnvironment object { id, archived_at, config, 7 more }`
209- `BetaEnvironment object`
219210
220211 Unified Environment resource for both cloud and self-hosted environments.
221212
from line 222
231222
232223 Environment configuration (either Anthropic Cloud or self-hosted)
233224
234 - `BetaCloudConfig object { networking, packages, type }`
225 - `BetaCloudConfig object`
235226
236227 `cloud` environment configuration.
237228
from line 230
239230
240231 Network configuration policy.
241232
242 - `BetaUnrestrictedNetwork object { type }`
233 - `BetaUnrestrictedNetwork object`
243234
244235 Unrestricted network access.
245236
from line 238
247238
248239 Network policy type
249240
250 - `"unrestricted"`
251
252 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
241 - `BetaLimitedNetwork object`
253242
254243 Limited network access.
255244
from line 258
269258
270259 Network policy type
271260
272 - `"limited"`
273
274261 - `packages: BetaPackages`
275262
276263 Package manager configuration.
from line 290
303290
304291 Package configuration type
305292
306 - `"packages"`
293 default: packages
307294
308295 - `type: "cloud"`
309296
310297 Environment type
311298
312 - `"cloud"`
313
314 - `BetaSelfHostedConfig object { type }`
299 - `BetaSelfHostedConfig object`
315300
316301 Configuration for self-hosted environments.
317302
from line 304
319304
320305 Environment type
321306
322 - `"self_hosted"`
323
324307 - `created_at: string`
325308
326309 RFC 3339 timestamp when environment was created
from line 324
341324
342325 The type of object (always 'environment')
343326
344 - `"environment"`
327 default: environment
345328
346329 - `updated_at: string`
347330
from line 340
357340
358341### Example
359342
360```http
343```bash
361344curl https://api.anthropic.com/v1/environments \
362345 -H 'Content-Type: application/json' \
363346 -H 'anthropic-version: 2023-06-01' \
from line 368
385368 }'
386369```
387370
388#### Response
371#### Response (200)
389372
390373```json
391374{
from line 419
436419
437420## List Environments
438421
439**get** `/v1/environments`
422**GET** `/v1/environments`
440423
441424List environments with pagination support.
442425
443### Query Parameters
426### Query parameters
444427
445428- `include_archived: optional boolean`
446429
447430 Include archived environments in the response
448431
432 default: false
433
449434- `limit: optional number`
450435
451436 Maximum number of environments to return
452437
438 default: 20, maximum: 1000, minimum: 1
439
453440- `page: optional string`
454441
455442 Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response.
456443
457### Header Parameters
444### Headers
458445
459446- `"anthropic-beta": optional array of AnthropicBeta`
460447
from line 537
550537
551538 Environment configuration (either Anthropic Cloud or self-hosted)
552539
553 - `BetaCloudConfig object { networking, packages, type }`
540 - `BetaCloudConfig object`
554541
555542 `cloud` environment configuration.
556543
from line 545
558545
559546 Network configuration policy.
560547
561 - `BetaUnrestrictedNetwork object { type }`
548 - `BetaUnrestrictedNetwork object`
562549
563550 Unrestricted network access.
564551
from line 553
566553
567554 Network policy type
568555
569 - `"unrestricted"`
570
571 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
556 - `BetaLimitedNetwork object`
572557
573558 Limited network access.
574559
from line 573
588573
589574 Network policy type
590575
591 - `"limited"`
592
593576 - `packages: BetaPackages`
594577
595578 Package manager configuration.
from line 605
622605
623606 Package configuration type
624607
625 - `"packages"`
608 default: packages
626609
627610 - `type: "cloud"`
628611
629612 Environment type
630613
631 - `"cloud"`
632
633 - `BetaSelfHostedConfig object { type }`
614 - `BetaSelfHostedConfig object`
634615
635616 Configuration for self-hosted environments.
636617
from line 619
638619
639620 Environment type
640621
641 - `"self_hosted"`
642
643622 - `created_at: string`
644623
645624 RFC 3339 timestamp when environment was created
from line 639
660639
661640 The type of object (always 'environment')
662641
663 - `"environment"`
642 default: environment
664643
665644 - `updated_at: string`
666645
from line 659
680659
681660### Example
682661
683```http
662```bash
684663curl https://api.anthropic.com/v1/environments \
685664 -H 'anthropic-version: 2023-06-01' \
686665 -H 'anthropic-beta: managed-agents-2026-04-01' \
687666 -H "X-Api-Key: $ANTHROPIC_API_KEY"
688667```
689668
690#### Response
669#### Response (200)
691670
692671```json
693672{
from line 722
743722
744723## Get Environment
745724
746**get** `/v1/environments/{environment_id}`
725**GET** `/v1/environments/{environment_id}`
747726
748727Retrieve a specific environment by ID.
749728
750### Path Parameters
729### Path parameters
751730
752731- `environment_id: string`
753732
754### Header Parameters
733### Headers
755734
756735- `"anthropic-beta": optional array of AnthropicBeta`
757736
from line 810
831810
832811### Returns
833812
834- `BetaEnvironment object { id, archived_at, config, 7 more }`
813- `BetaEnvironment object`
835814
836815 Unified Environment resource for both cloud and self-hosted environments.
837816
from line 826
847826
848827 Environment configuration (either Anthropic Cloud or self-hosted)
849828
850 - `BetaCloudConfig object { networking, packages, type }`
829 - `BetaCloudConfig object`
851830
852831 `cloud` environment configuration.
853832
from line 834
855834
856835 Network configuration policy.
857836
858 - `BetaUnrestrictedNetwork object { type }`
837 - `BetaUnrestrictedNetwork object`
859838
860839 Unrestricted network access.
861840
from line 842
863842
864843 Network policy type
865844
866 - `"unrestricted"`
867
868 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
845 - `BetaLimitedNetwork object`
869846
870847 Limited network access.
871848
from line 862
885862
886863 Network policy type
887864
888 - `"limited"`
889
890865 - `packages: BetaPackages`
891866
892867 Package manager configuration.
from line 894
919894
920895 Package configuration type
921896
922 - `"packages"`
897 default: packages
923898
924899 - `type: "cloud"`
925900
926901 Environment type
927902
928 - `"cloud"`
929
930 - `BetaSelfHostedConfig object { type }`
903 - `BetaSelfHostedConfig object`
931904
932905 Configuration for self-hosted environments.
933906
from line 908
935908
936909 Environment type
937910
938 - `"self_hosted"`
939
940911 - `created_at: string`
941912
942913 RFC 3339 timestamp when environment was created
from line 928
957928
958929 The type of object (always 'environment')
959930
960 - `"environment"`
931 default: environment
961932
962933 - `updated_at: string`
963934
from line 944
973944
974945### Example
975946
976```http
947```bash
977948curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
978949 -H 'anthropic-version: 2023-06-01' \
979950 -H 'anthropic-beta: managed-agents-2026-04-01' \
980951 -H "X-Api-Key: $ANTHROPIC_API_KEY"
981952```
982953
983#### Response
954#### Response (200)
984955
985956```json
986957{
from line 1002
10311002
10321003## Update Environment
10331004
1034**post** `/v1/environments/{environment_id}`
1005**POST** `/v1/environments/{environment_id}`
10351006
10361007Update an existing environment's configuration.
10371008
1038### Path Parameters
1009### Path parameters
10391010
10401011- `environment_id: string`
10411012
1042### Header Parameters
1013### Headers
10431014
10441015- `"anthropic-beta": optional array of AnthropicBeta`
10451016
from line 1088
11171088
11181089 - `"mid-conversation-tool-changes-2026-07-01"`
11191090
1120### Body Parameters
1091### Body parameters
11211092
11221093- `config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams or null`
11231094
11241095 Updated environment configuration
11251096
1126 - `BetaCloudConfigParams object { type, networking, packages }`
1097 - `BetaCloudConfigParams object`
11271098
11281099 Request params for `cloud` environment configuration.
11291100
from line 1105
11341105
11351106 Environment type
11361107
1137 - `"cloud"`
1138
11391108 - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null`
11401109
11411110 Network configuration policy. Omit on update to preserve the existing value.
11421111
1143 - `BetaUnrestrictedNetwork object { type }`
1112 - `BetaUnrestrictedNetwork object`
11441113
11451114 Unrestricted network access.
11461115
from line 1117
11481117
11491118 Network policy type
11501119
1151 - `"unrestricted"`
1152
1153 - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }`
1120 - `BetaLimitedNetworkParams object`
11541121
11551122 Limited network request params.
11561123
from line 1128
11611128
11621129 Network policy type
11631130
1164 - `"limited"`
1165
11661131 - `allow_mcp_servers: optional boolean or null`
11671132
11681133 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
12091174
12101175 Package configuration type
12111176
1212 - `"packages"`
1213
1214 - `BetaSelfHostedConfigParams object { type }`
1177 default: packages
1178
1179 - `BetaSelfHostedConfigParams object`
12151180
12161181 Request params for `self_hosted` environment configuration.
12171182
from line 1184
12191184
12201185 Environment type
12211186
1222 - `"self_hosted"`
1223
12241187- `description: optional string or null`
12251188
12261189 Updated description of the environment. Omit to preserve; null clears to null; an empty string is stored as an empty string.
12271190
1191 maxLength: 1024
1192
12281193- `metadata: optional map[string]`
12291194
12301195 User-provided metadata key-value pairs. Set a value to null or empty string to delete the key.
from line 1198
12331198
12341199 Updated name for the environment
12351200
1201 maxLength: 256, minLength: 1
1202
12361203- `scope: optional "organization" or "account" or null`
12371204
12381205 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
12431210
12441211### Returns
12451212
1246- `BetaEnvironment object { id, archived_at, config, 7 more }`
1213- `BetaEnvironment object`
12471214
12481215 Unified Environment resource for both cloud and self-hosted environments.
12491216
from line 1226
12591226
12601227 Environment configuration (either Anthropic Cloud or self-hosted)
12611228
1262 - `BetaCloudConfig object { networking, packages, type }`
1229 - `BetaCloudConfig object`
12631230
12641231 `cloud` environment configuration.
12651232
from line 1234
12671234
12681235 Network configuration policy.
12691236
1270 - `BetaUnrestrictedNetwork object { type }`
1237 - `BetaUnrestrictedNetwork object`
12711238
12721239 Unrestricted network access.
12731240
from line 1242
12751242
12761243 Network policy type
12771244
1278 - `"unrestricted"`
1279
1280 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
1245 - `BetaLimitedNetwork object`
12811246
12821247 Limited network access.
12831248
from line 1262
12971262
12981263 Network policy type
12991264
1300 - `"limited"`
1301
13021265 - `packages: BetaPackages`
13031266
13041267 Package manager configuration.
from line 1294
13311294
13321295 Package configuration type
13331296
1334 - `"packages"`
1297 default: packages
13351298
13361299 - `type: "cloud"`
13371300
13381301 Environment type
13391302
1340 - `"cloud"`
1341
1342 - `BetaSelfHostedConfig object { type }`
1303 - `BetaSelfHostedConfig object`
13431304
13441305 Configuration for self-hosted environments.
13451306
from line 1308
13471308
13481309 Environment type
13491310
1350 - `"self_hosted"`
1351
13521311 - `created_at: string`
13531312
13541313 RFC 3339 timestamp when environment was created
from line 1328
13691328
13701329 The type of object (always 'environment')
13711330
1372 - `"environment"`
1331 default: environment
13731332
13741333 - `updated_at: string`
13751334
from line 1344
13851344
13861345### Example
13871346
1388```http
1347```bash
13891348curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
13901349 -H 'Content-Type: application/json' \
13911350 -H 'anthropic-version: 2023-06-01' \
from line 1355
13961355 }'
13971356```
13981357
1399#### Response
1358#### Response (200)
14001359
14011360```json
14021361{
from line 1406
14471406
14481407## Delete Environment
14491408
1450**delete** `/v1/environments/{environment_id}`
1409**DELETE** `/v1/environments/{environment_id}`
14511410
14521411Delete an environment by ID. Returns a confirmation of the deletion.
14531412
1454### Path Parameters
1413### Path parameters
14551414
14561415- `environment_id: string`
14571416
1458### Header Parameters
1417### Headers
14591418
14601419- `"anthropic-beta": optional array of AnthropicBeta`
14611420
from line 1494
15351494
15361495### Returns
15371496
1538- `BetaEnvironmentDeleteResponse object { id, type }`
1497- `BetaEnvironmentDeleteResponse object`
15391498
15401499 Response after deleting an environment.
15411500
from line 1506
15471506
15481507 The type of response
15491508
1550 - `"environment_deleted"`
1509 default: environment_deleted
15511510
15521511### Example
15531512
1554```http
1513```bash
15551514curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
15561515 -X DELETE \
15571516 -H 'anthropic-version: 2023-06-01' \
from line 1518
15591518 -H "X-Api-Key: $ANTHROPIC_API_KEY"
15601519```
15611520
1562#### Response
1521#### Response (200)
15631522
15641523```json
15651524{
from line 1529
15701529
15711530## Archive Environment
15721531
1573**post** `/v1/environments/{environment_id}/archive`
1532**POST** `/v1/environments/{environment_id}/archive`
15741533
15751534Archive an environment by ID. Archived environments cannot be used to create new sessions.
15761535
1577### Path Parameters
1536### Path parameters
15781537
15791538- `environment_id: string`
15801539
1581### Header Parameters
1540### Headers
15821541
15831542- `"anthropic-beta": optional array of AnthropicBeta`
15841543
from line 1617
16581617
16591618### Returns
16601619
1661- `BetaEnvironment object { id, archived_at, config, 7 more }`
1620- `BetaEnvironment object`
16621621
16631622 Unified Environment resource for both cloud and self-hosted environments.
16641623
from line 1633
16741633
16751634 Environment configuration (either Anthropic Cloud or self-hosted)
16761635
1677 - `BetaCloudConfig object { networking, packages, type }`
1636 - `BetaCloudConfig object`
16781637
16791638 `cloud` environment configuration.
16801639
from line 1641
16821641
16831642 Network configuration policy.
16841643
1685 - `BetaUnrestrictedNetwork object { type }`
1644 - `BetaUnrestrictedNetwork object`
16861645
16871646 Unrestricted network access.
16881647
from line 1649
16901649
16911650 Network policy type
16921651
1693 - `"unrestricted"`
1694
1695 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
1652 - `BetaLimitedNetwork object`
16961653
16971654 Limited network access.
16981655
from line 1669
17121669
17131670 Network policy type
17141671
1715 - `"limited"`
1716
17171672 - `packages: BetaPackages`
17181673
17191674 Package manager configuration.
from line 1701
17461701
17471702 Package configuration type
17481703
1749 - `"packages"`
1704 default: packages
17501705
17511706 - `type: "cloud"`
17521707
17531708 Environment type
17541709
1755 - `"cloud"`
1756
1757 - `BetaSelfHostedConfig object { type }`
1710 - `BetaSelfHostedConfig object`
17581711
17591712 Configuration for self-hosted environments.
17601713
from line 1715
17621715
17631716 Environment type
17641717
1765 - `"self_hosted"`
1766
17671718 - `created_at: string`
17681719
17691720 RFC 3339 timestamp when environment was created
from line 1735
17841735
17851736 The type of object (always 'environment')
17861737
1787 - `"environment"`
1738 default: environment
17881739
17891740 - `updated_at: string`
17901741
from line 1751
18001751
18011752### Example
18021753
1803```http
1754```bash
18041755curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive \
18051756 -X POST \
18061757 -H 'anthropic-version: 2023-06-01' \
from line 1759
18081759 -H "X-Api-Key: $ANTHROPIC_API_KEY"
18091760```
18101761
1811#### Response
1762#### Response (200)
18121763
18131764```json
18141765{
from line 1808
18571808}
18581809```
18591810
1860## Domain Types
1811## Domain types
18611812
18621813### Beta Cloud Config
18631814
1864- `BetaCloudConfig object { networking, packages, type }`
1815- `BetaCloudConfig object`
18651816
18661817 `cloud` environment configuration.
18671818
from line 1820
18691820
18701821 Network configuration policy.
18711822
1872 - `BetaUnrestrictedNetwork object { type }`
1823 - `BetaUnrestrictedNetwork object`
18731824
18741825 Unrestricted network access.
18751826
from line 1828
18771828
18781829 Network policy type
18791830
1880 - `"unrestricted"`
1881
1882 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
1831 - `BetaLimitedNetwork object`
18831832
18841833 Limited network access.
18851834
from line 1848
18991848
19001849 Network policy type
19011850
1902 - `"limited"`
1903
19041851 - `packages: BetaPackages`
19051852
19061853 Package manager configuration.
from line 1880
19331880
19341881 Package configuration type
19351882
1936 - `"packages"`
1883 default: packages
19371884
19381885 - `type: "cloud"`
19391886
19401887 Environment type
19411888
1942 - `"cloud"`
1943
19441889### Beta Cloud Config Params
19451890
1946- `BetaCloudConfigParams object { type, networking, packages }`
1891- `BetaCloudConfigParams object`
19471892
19481893 Request params for `cloud` environment configuration.
19491894
from line 1899
19541899
19551900 Environment type
19561901
1957 - `"cloud"`
1958
19591902 - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null`
19601903
19611904 Network configuration policy. Omit on update to preserve the existing value.
19621905
1963 - `BetaUnrestrictedNetwork object { type }`
1906 - `BetaUnrestrictedNetwork object`
19641907
19651908 Unrestricted network access.
19661909
from line 1911
19681911
19691912 Network policy type
19701913
1971 - `"unrestricted"`
1972
1973 - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }`
1914 - `BetaLimitedNetworkParams object`
19741915
19751916 Limited network request params.
19761917
from line 1922
19811922
19821923 Network policy type
19831924
1984 - `"limited"`
1985
19861925 - `allow_mcp_servers: optional boolean or null`
19871926
19881927 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
20291968
20301969 Package configuration type
20311970
2032 - `"packages"`
1971 default: packages
20331972
20341973### Beta Environment
20351974
2036- `BetaEnvironment object { id, archived_at, config, 7 more }`
1975- `BetaEnvironment object`
20371976
20381977 Unified Environment resource for both cloud and self-hosted environments.
20391978
from line 1988
20491988
20501989 Environment configuration (either Anthropic Cloud or self-hosted)
20511990
2052 - `BetaCloudConfig object { networking, packages, type }`
1991 - `BetaCloudConfig object`
20531992
20541993 `cloud` environment configuration.
20551994
from line 1996
20571996
20581997 Network configuration policy.
20591998
2060 - `BetaUnrestrictedNetwork object { type }`
1999 - `BetaUnrestrictedNetwork object`
20612000
20622001 Unrestricted network access.
20632002
from line 2004
20652004
20662005 Network policy type
20672006
2068 - `"unrestricted"`
2069
2070 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
2007 - `BetaLimitedNetwork object`
20712008
20722009 Limited network access.
20732010
from line 2024
20872024
20882025 Network policy type
20892026
2090 - `"limited"`
2091
20922027 - `packages: BetaPackages`
20932028
20942029 Package manager configuration.
from line 2056
21212056
21222057 Package configuration type
21232058
2124 - `"packages"`
2059 default: packages
21252060
21262061 - `type: "cloud"`
21272062
21282063 Environment type
21292064
2130 - `"cloud"`
2131
2132 - `BetaSelfHostedConfig object { type }`
2065 - `BetaSelfHostedConfig object`
21332066
21342067 Configuration for self-hosted environments.
21352068
from line 2070
21372070
21382071 Environment type
21392072
2140 - `"self_hosted"`
2141
21422073 - `created_at: string`
21432074
21442075 RFC 3339 timestamp when environment was created
from line 2090
21592090
21602091 The type of object (always 'environment')
21612092
2162 - `"environment"`
2093 default: environment
21632094
21642095 - `updated_at: string`
21652096
from line 2106
21752106
21762107### Beta Environment Delete Response
21772108
2178- `BetaEnvironmentDeleteResponse object { id, type }`
2109- `BetaEnvironmentDeleteResponse object`
21792110
21802111 Response after deleting an environment.
21812112
from line 2118
21872118
21882119 The type of response
21892120
2190 - `"environment_deleted"`
2121 default: environment_deleted
21912122
21922123### Beta Limited Network
21932124
2194- `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
2125- `BetaLimitedNetwork object`
21952126
21962127 Limited network access.
21972128
from line 2142
22112142
22122143 Network policy type
22132144
2214 - `"limited"`
2215
22162145### Beta Limited Network Params
22172146
2218- `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }`
2147- `BetaLimitedNetworkParams object`
22192148
22202149 Limited network request params.
22212150
from line 2155
22262155
22272156 Network policy type
22282157
2229 - `"limited"`
2230
22312158 - `allow_mcp_servers: optional boolean or null`
22322159
22332160 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
22422169
22432170### Beta Packages
22442171
2245- `BetaPackages object { apt, cargo, gem, 4 more }`
2172- `BetaPackages object`
22462173
22472174 Packages (and their versions) available in this environment.
22482175
from line 2201
22742201
22752202 Package configuration type
22762203
2277 - `"packages"`
2204 default: packages
22782205
22792206### Beta Packages Params
22802207
2281- `BetaPackagesParams object { apt, cargo, gem, 4 more }`
2208- `BetaPackagesParams object`
22822209
22832210 Specify packages (and optionally their versions) available in this environment.
22842211
from line 2239
23122239
23132240 Package configuration type
23142241
2315 - `"packages"`
2242 default: packages
23162243
23172244### Beta Self Hosted Config
23182245
2319- `BetaSelfHostedConfig object { type }`
2246- `BetaSelfHostedConfig object`
23202247
23212248 Configuration for self-hosted environments.
23222249
from line 2251
23242251
23252252 Environment type
23262253
2327 - `"self_hosted"`
2328
23292254### Beta Self Hosted Config Params
23302255
2331- `BetaSelfHostedConfigParams object { type }`
2256- `BetaSelfHostedConfigParams object`
23322257
23332258 Request params for `self_hosted` environment configuration.
23342259
from line 2261
23362261
23372262 Environment type
23382263
2339 - `"self_hosted"`
2340
23412264### Beta Unrestricted Network
23422265
2343- `BetaUnrestrictedNetwork object { type }`
2266- `BetaUnrestrictedNetwork object`
23442267
23452268 Unrestricted network access.
23462269
from line 2271
23482271
23492272 Network policy type
23502273
2351 - `"unrestricted"`
2352
2353# Work
2354
2355## Get Work Item
2356
2357**get** `/v1/environments/{environment_id}/work/{work_id}`
2274## Environments › Work
2275
2276### Get Work Item
2277
2278**GET** `/v1/environments/{environment_id}/work/{work_id}`
23582279
23592280Note: 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.
23602281
23612282Retrieve detailed information about a specific work item.
23622283
2363### Path Parameters
2284#### Path parameters
23642285
23652286- `environment_id: string`
23662287
23672288- `work_id: string`
23682289
2369### Header Parameters
2290#### Headers
23702291
23712292- `"anthropic-beta": optional array of AnthropicBeta`
23722293
from line 2365
24442365
24452366 - `"mid-conversation-tool-changes-2026-07-01"`
24462367
2447### Returns
2448
2449- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
2368#### Returns
2369
2370- `BetaSelfHostedWork object`
24502371
24512372 Work resource representing a unit of work in a self-hosted environment.
24522373
from line 2399
24782399
24792400 Type of work data
24802401
2481 - `"session"`
2482
24832402 - `environment_id: string`
24842403
24852404 Environment identifier this work belongs to (e.g., `env_...`)
from line 2445
25262445
25272446 The type of object (always 'work')
25282447
2529 - `"work"`
2530
2531### Example
2532
2533```http
2448 default: work
2449
2450#### Example
2451
2452```bash
25342453curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \
25352454 -H 'anthropic-version: 2023-06-01' \
25362455 -H 'anthropic-beta: managed-agents-2026-04-01' \
25372456 -H "X-Api-Key: $ANTHROPIC_API_KEY"
25382457```
25392458
2540#### Response
2459##### Response (200)
25412460
25422461```json
25432462{
from line 2481
25622481}
25632482```
25642483
2565## Poll for Work
2566
2567**get** `/v1/environments/{environment_id}/work/poll`
2484### Poll for Work
2485
2486**GET** `/v1/environments/{environment_id}/work/poll`
25682487
25692488Note: 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.
25702489
25712490Long poll for work items in the queue.
25722491
2573### Path Parameters
2492#### Path parameters
25742493
25752494- `environment_id: string`
25762495
2577### Query Parameters
2496#### Query parameters
25782497
25792498- `block_ms: optional number`
25802499
25812500 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).
25822501
2502 minimum: 1
2503
25832504- `reclaim_older_than_ms: optional number`
25842505
25852506 Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms).
25862507
2587### Header Parameters
2508 minimum: 1
2509
2510#### Headers
25882511
25892512- `"anthropic-beta": optional array of AnthropicBeta`
25902513
from line 2589
26662589
26672590 Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console
26682591
2669### Returns
2670
2671- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
2592#### Returns
2593
2594- `BetaSelfHostedWork object`
26722595
26732596 Work resource representing a unit of work in a self-hosted environment.
26742597
from line 2623
27002623
27012624 Type of work data
27022625
2703 - `"session"`
2704
27052626 - `environment_id: string`
27062627
27072628 Environment identifier this work belongs to (e.g., `env_...`)
from line 2669
27482669
27492670 The type of object (always 'work')
27502671
2751 - `"work"`
2752
2753### Example
2754
2755```http
2672 default: work
2673
2674#### Example
2675
2676```bash
27562677curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/poll \
27572678 -H 'anthropic-version: 2023-06-01' \
27582679 -H 'anthropic-beta: managed-agents-2026-04-01' \
27592680 -H "X-Api-Key: $ANTHROPIC_API_KEY"
27602681```
27612682
2762#### Response
2683##### Response (200)
27632684
27642685```json
27652686{
from line 2705
27842705}
27852706```
27862707
2787## Acknowledge Work
2788
2789**post** `/v1/environments/{environment_id}/work/{work_id}/ack`
2708### Acknowledge Work
2709
2710**POST** `/v1/environments/{environment_id}/work/{work_id}/ack`
27902711
27912712Note: 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.
27922713
27932714Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue.
27942715
2795### Path Parameters
2716#### Path parameters
27962717
27972718- `environment_id: string`
27982719
27992720- `work_id: string`
28002721
2801### Header Parameters
2722#### Headers
28022723
28032724- `"anthropic-beta": optional array of AnthropicBeta`
28042725
from line 2797
28762797
28772798 - `"mid-conversation-tool-changes-2026-07-01"`
28782799
2879### Returns
2880
2881- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
2800#### Returns
2801
2802- `BetaSelfHostedWork object`
28822803
28832804 Work resource representing a unit of work in a self-hosted environment.
28842805
from line 2831
29102831
29112832 Type of work data
29122833
2913 - `"session"`
2914
29152834 - `environment_id: string`
29162835
29172836 Environment identifier this work belongs to (e.g., `env_...`)
from line 2877
29582877
29592878 The type of object (always 'work')
29602879
2961 - `"work"`
2962
2963### Example
2964
2965```http
2880 default: work
2881
2882#### Example
2883
2884```bash
29662885curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/ack \
29672886 -X POST \
29682887 -H 'anthropic-version: 2023-06-01' \
from line 2889
29702889 -H "X-Api-Key: $ANTHROPIC_API_KEY"
29712890```
29722891
2973#### Response
2892##### Response (200)
29742893
29752894```json
29762895{
from line 2914
29952914}
29962915```
29972916
2998## Record Heartbeat
2999
3000**post** `/v1/environments/{environment_id}/work/{work_id}/heartbeat`
2917### Record Heartbeat
2918
2919**POST** `/v1/environments/{environment_id}/work/{work_id}/heartbeat`
30012920
30022921Note: 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.
30032922
30042923Record a heartbeat for a work item to maintain the lease.
30052924
3006### Path Parameters
2925#### Path parameters
30072926
30082927- `environment_id: string`
30092928
30102929- `work_id: string`
30112930
3012### Query Parameters
2931#### Query parameters
30132932
30142933- `desired_ttl_seconds: optional number`
30152934
from line 2938
30192938
30202939 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.
30212940
3022### Header Parameters
2941#### Headers
30232942
30242943- `"anthropic-beta": optional array of AnthropicBeta`
30252944
from line 3016
30973016
30983017 - `"mid-conversation-tool-changes-2026-07-01"`
30993018
3100### Returns
3101
3102- `BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }`
3019#### Returns
3020
3021- `BetaSelfHostedWorkHeartbeatResponse object`
31033022
31043023 Response after recording a heartbeat for a work item.
31053024
from line 3052
31333052
31343053 The type of response
31353054
3136 - `"work_heartbeat"`
3137
3138### Example
3139
3140```http
3055 default: work_heartbeat
3056
3057#### Example
3058
3059```bash
31413060curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/heartbeat \
31423061 -X POST \
31433062 -H 'anthropic-version: 2023-06-01' \
from line 3064
31453064 -H "X-Api-Key: $ANTHROPIC_API_KEY"
31463065```
31473066
3148#### Response
3067##### Response (200)
31493068
31503069```json
31513070{
from line 3076
31573076}
31583077```
31593078
3160## Stop Work
3161
3162**post** `/v1/environments/{environment_id}/work/{work_id}/stop`
3079### Stop Work
3080
3081**POST** `/v1/environments/{environment_id}/work/{work_id}/stop`
31633082
31643083Note: 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.
31653084
31663085Stop a work item, initiating graceful or forced shutdown.
31673086
3168### Path Parameters
3087#### Path parameters
31693088
31703089- `environment_id: string`
31713090
31723091- `work_id: string`
31733092
3174### Header Parameters
3093#### Headers
31753094
31763095- `"anthropic-beta": optional array of AnthropicBeta`
31773096
from line 3168
32493168
32503169 - `"mid-conversation-tool-changes-2026-07-01"`
32513170
3252### Body Parameters
3171#### Body parameters
32533172
32543173- `force: optional boolean`
32553174
32563175 If true, immediately stop work without graceful shutdown
32573176
3258### Returns
3259
3260- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
3177 default: false
3178
3179#### Returns
3180
3181- `BetaSelfHostedWork object`
32613182
32623183 Work resource representing a unit of work in a self-hosted environment.
32633184
from line 3210
32893210
32903211 Type of work data
32913212
3292 - `"session"`
3293
32943213 - `environment_id: string`
32953214
32963215 Environment identifier this work belongs to (e.g., `env_...`)
from line 3256
33373256
33383257 The type of object (always 'work')
33393258
3340 - `"work"`
3341
3342### Example
3343
3344```http
3259 default: work
3260
3261#### Example
3262
3263```bash
33453264curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/stop \
33463265 -H 'Content-Type: application/json' \
33473266 -H 'anthropic-version: 2023-06-01' \
from line 3269
33503269 -d '{}'
33513270```
33523271
3353#### Response
3272##### Response (200)
33543273
33553274```json
33563275{
from line 3294
33753294}
33763295```
33773296
3378## List Work Items
3379
3380**get** `/v1/environments/{environment_id}/work`
3297### List Work Items
3298
3299**GET** `/v1/environments/{environment_id}/work`
33813300
33823301Note: 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.
33833302
33843303List work items in an environment.
33853304
3386### Path Parameters
3305#### Path parameters
33873306
33883307- `environment_id: string`
33893308
3390### Query Parameters
3309#### Query parameters
33913310
33923311- `limit: optional number`
33933312
33943313 Maximum number of work items to return
33953314
3315 default: 20, maximum: 1000, minimum: 1
3316
33963317- `page: optional string`
33973318
33983319 Opaque cursor from previous response for pagination
33993320
3400### Header Parameters
3321#### Headers
34013322
34023323- `"anthropic-beta": optional array of AnthropicBeta`
34033324
from line 3396
34753396
34763397 - `"mid-conversation-tool-changes-2026-07-01"`
34773398
3478### Returns
3479
3480- `BetaSelfHostedWorkListResponse object { data, next_page }`
3399#### Returns
3400
3401- `BetaSelfHostedWorkListResponse object`
34813402
34823403 Response when listing work items with cursor-based pagination.
34833404
from line 3430
35093430
35103431 Type of work data
35113432
3512 - `"session"`
3513
35143433 - `environment_id: string`
35153434
35163435 Environment identifier this work belongs to (e.g., `env_...`)
from line 3476
35573476
35583477 The type of object (always 'work')
35593478
3560 - `"work"`
3479 default: work
35613480
35623481 - `next_page: string or null`
35633482
35643483 Opaque cursor for fetching the next page of results
35653484
3566### Example
3567
3568```http
3485#### Example
3486
3487```bash
35693488curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work \
35703489 -H 'anthropic-version: 2023-06-01' \
35713490 -H 'anthropic-beta: managed-agents-2026-04-01' \
35723491 -H "X-Api-Key: $ANTHROPIC_API_KEY"
35733492```
35743493
3575#### Response
3494##### Response (200)
35763495
35773496```json
35783497{
from line 3521
36023521}
36033522```
36043523
3605## Update Work Item
3606
3607**post** `/v1/environments/{environment_id}/work/{work_id}`
3524### Update Work Item
3525
3526**POST** `/v1/environments/{environment_id}/work/{work_id}`
36083527
36093528Note: 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.
36103529
36113530Update work item metadata with merge semantics.
36123531
3613### Path Parameters
3532#### Path parameters
36143533
36153534- `environment_id: string`
36163535
36173536- `work_id: string`
36183537
3619### Header Parameters
3538#### Headers
36203539
36213540- `"anthropic-beta": optional array of AnthropicBeta`
36223541
from line 3613
36943613
36953614 - `"mid-conversation-tool-changes-2026-07-01"`
36963615
3697### Body Parameters
3616#### Body parameters
36983617
36993618- `metadata: map[string]`
37003619
37013620 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata.
37023621
3703### Returns
3704
3705- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
3622#### Returns
3623
3624- `BetaSelfHostedWork object`
37063625
37073626 Work resource representing a unit of work in a self-hosted environment.
37083627
from line 3653
37343653
37353654 Type of work data
37363655
3737 - `"session"`
3738
37393656 - `environment_id: string`
37403657
37413658 Environment identifier this work belongs to (e.g., `env_...`)
from line 3699
37823699
37833700 The type of object (always 'work')
37843701
3785 - `"work"`
3786
3787### Example
3788
3789```http
3702 default: work
3703
3704#### Example
3705
3706```bash
37903707curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \
37913708 -H 'Content-Type: application/json' \
37923709 -H 'anthropic-version: 2023-06-01' \
from line 3716
37993716 }'
38003717```
38013718
3802#### Response
3719##### Response (200)
38033720
38043721```json
38053722{
from line 3741
38243741}
38253742```
38263743
3827## Get Queue Statistics
3828
3829**get** `/v1/environments/{environment_id}/work/stats`
3744### Get Queue Statistics
3745
3746**GET** `/v1/environments/{environment_id}/work/stats`
38303747
38313748Get statistics about the work queue for an environment.
38323749
3833### Path Parameters
3750#### Path parameters
38343751
38353752- `environment_id: string`
38363753
3837### Header Parameters
3754#### Headers
38383755
38393756- `"anthropic-beta": optional array of AnthropicBeta`
38403757
from line 3829
39123829
39133830 - `"mid-conversation-tool-changes-2026-07-01"`
39143831
3915### Returns
3916
3917- `BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }`
3832#### Returns
3833
3834- `BetaSelfHostedWorkQueueStats object`
39183835
39193836 Statistics about the work queue for an environment.
39203837
from line 3849
39323849
39333850 Number of work items being processed (polled but not acknowledged)
39343851
3852 default: 0
3853
39353854 - `type: "work_queue_stats"`
39363855
39373856 The type of object
39383857
3939 - `"work_queue_stats"`
3858 default: work_queue_stats
39403859
39413860 - `workers_polling: number or null`
39423861
39433862 Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests.
39443863
3945### Example
3946
3947```http
3864#### Example
3865
3866```bash
39483867curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/stats \
39493868 -H 'anthropic-version: 2023-06-01' \
39503869 -H 'anthropic-beta: managed-agents-2026-04-01' \
39513870 -H "X-Api-Key: $ANTHROPIC_API_KEY"
39523871```
39533872
3954#### Response
3873##### Response (200)
39553874
39563875```json
39573876{
from line 3881
39623881 "workers_polling": 0
39633882}
39643883```
3965
3966## Domain Types
3967
3968### Beta Self Hosted Work
3969
3970- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
3971
3972 Work resource representing a unit of work in a self-hosted environment.
3973
3974 Work items are queued when sessions are created or when long-dormant sessions
3975 receive new messages. The environment worker polls for work to execute in a
3976 self-hosted sandbox.
3977
3978 - `id: string`
3979
3980 Work identifier (e.g., 'work_...')
3981
3982 - `acknowledged_at: string or null`
3983
3984 RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox
3985
3986 - `created_at: string`
3987
3988 RFC 3339 timestamp when work was created
3989
3990 - `data: BetaSessionWorkData`
3991
3992 The actual work to be performed
3993
3994 - `id: string`
3995
3996 Session identifier (e.g., 'session_...')
3997
3998 - `type: "session"`
3999
4000 Type of work data
4001
4002 - `"session"`
4003
4004 - `environment_id: string`
4005
4006 Environment identifier this work belongs to (e.g., `env_...`)
4007
4008 - `latest_heartbeat_at: string or null`
4009
4010 RFC 3339 timestamp of the most recent heartbeat
4011
4012 - `metadata: map[string]`
4013
4014 User-provided metadata key-value pairs associated with this work item
4015
4016 - `secret: string or null`
4017
4018 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.
4019
4020 - `started_at: string or null`
4021
4022 RFC 3339 timestamp when work execution started
4023
4024 - `state: "queued" or "starting" or "active" or 2 more`
4025
4026 Current state of the work item
4027
4028 - `"queued"`
4029
4030 - `"starting"`
4031
4032 - `"active"`
4033
4034 - `"stopping"`
4035
4036 - `"stopped"`
4037
4038 - `stop_requested_at: string or null`
4039
4040 RFC 3339 timestamp when stop was requested
4041
4042 - `stopped_at: string or null`
4043
4044 RFC 3339 timestamp when work execution stopped
4045
4046 - `type: "work"`
4047
4048 The type of object (always 'work')
4049
4050 - `"work"`
4051
4052### Beta Self Hosted Work Heartbeat Response
4053
4054- `BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }`
4055
4056 Response after recording a heartbeat for a work item.
4057
4058 - `last_heartbeat: string`
4059
4060 RFC 3339 timestamp of the actual heartbeat from DB
4061
4062 - `lease_extended: boolean`
4063
4064 Whether the heartbeat succeeded in extending the lease
4065
4066 - `state: "queued" or "starting" or "active" or 2 more`
4067
4068 Current state of the work item (active/stopping/stopped)
4069
4070 - `"queued"`
4071
4072 - `"starting"`
4073
4074 - `"active"`
4075
4076 - `"stopping"`
4077
4078 - `"stopped"`
4079
4080 - `ttl_seconds: number`
4081
4082 Effective TTL applied to the lease
4083
4084 - `type: "work_heartbeat"`
4085
4086 The type of response
4087
4088 - `"work_heartbeat"`
4089
4090### Beta Self Hosted Work List Response
4091
4092- `BetaSelfHostedWorkListResponse object { data, next_page }`
4093
4094 Response when listing work items with cursor-based pagination.
4095
4096 - `data: array of BetaSelfHostedWork`
4097
4098 List of work items
4099
4100 - `id: string`
4101
4102 Work identifier (e.g., 'work_...')
4103
4104 - `acknowledged_at: string or null`
4105
4106 RFC 3339 timestamp when the work item was acknowledged and assigned to a self-hosted sandbox
4107
4108 - `created_at: string`
4109
4110 RFC 3339 timestamp when work was created
4111
4112 - `data: BetaSessionWorkData`
4113
4114 The actual work to be performed
4115
4116 - `id: string`
4117
4118 Session identifier (e.g., 'session_...')
4119
4120 - `type: "session"`
4121
4122 Type of work data
4123
4124 - `"session"`
4125
4126 - `environment_id: string`
4127
4128 Environment identifier this work belongs to (e.g., `env_...`)
4129
4130 - `latest_heartbeat_at: string or null`
4131
4132 RFC 3339 timestamp of the most recent heartbeat
4133
4134 - `metadata: map[string]`
4135
4136 User-provided metadata key-value pairs associated with this work item
4137
4138 - `secret: string or null`
4139
4140 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.
4141
4142 - `started_at: string or null`
4143
4144 RFC 3339 timestamp when work execution started
4145
4146 - `state: "queued" or "starting" or "active" or 2 more`
4147
4148 Current state of the work item
4149
4150 - `"queued"`
4151
4152 - `"starting"`
4153
4154 - `"active"`
4155
4156 - `"stopping"`
4157
4158 - `"stopped"`
4159
4160 - `stop_requested_at: string or null`
4161
4162 RFC 3339 timestamp when stop was requested
4163
4164 - `stopped_at: string or null`
4165
4166 RFC 3339 timestamp when work execution stopped
4167
4168 - `type: "work"`
4169
4170 The type of object (always 'work')
4171
4172 - `"work"`
4173
4174 - `next_page: string or null`
4175
4176 Opaque cursor for fetching the next page of results
4177
4178### Beta Self Hosted Work Queue Stats
4179
4180- `BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }`
4181
4182 Statistics about the work queue for an environment.
4183
4184 Uses Redis Stream consumer group metrics for O(1) queries.
4185
4186 - `depth: number`
4187
4188 Number of work items waiting to be picked up (lag from consumer group)
4189
4190 - `oldest_queued_at: string or null`
4191
4192 RFC 3339 timestamp of oldest item in the work stream (includes both queued and pending items), null if stream empty
4193
4194 - `pending: number`
4195
4196 Number of work items being processed (polled but not acknowledged)
4197
4198 - `type: "work_queue_stats"`
4199
4200 The type of object
4201
4202 - `"work_queue_stats"`
4203
4204 - `workers_polling: number or null`
4205
4206 Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests.
4207
4208### Beta Self Hosted Work Stop Request
4209
4210- `BetaSelfHostedWorkStopRequest object { force }`
4211
4212 Request to stop a work item.
4213
4214 - `force: optional boolean`
4215
4216 If true, immediately stop work without graceful shutdown
4217
4218### Beta Self Hosted Work Update Request
4219
4220- `BetaSelfHostedWorkUpdateRequest object { metadata }`
4221
4222 Request to update work item metadata.
4223
4224 - `metadata: map[string]`
4225
4226 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve existing metadata.
4227
4228### Beta Session Work Data
4229
4230- `BetaSessionWorkData object { id, type }`
4231
4232 Work data for session work items.
4233
4234 This resource type is used when work represents a session that needs to be executed
4235 in a self-hosted environment.
4236
4237 - `id: string`
4238
4239 Session identifier (e.g., 'session_...')
4240
4241 - `type: "session"`
4242
4243 Type of work data
4244
4245 - `"session"`
42463884
api/beta/environments/archive Changed · +18 / -31 lines
# Archive Environment ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Archive Environment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Archive Environment
3url: https://platform.claude.com/docs/en/api/beta/environments/archive
4---
1# Archive Environment
52
6## Archive Environment
3**POST** `/v1/environments/{environment_id}/archive`
74
8**post** `/v1/environments/{environment_id}/archive`
9
105Archive an environment by ID. Archived environments cannot be used to create new sessions.
116
12### Path Parameters
7## Path parameters
138
149- `environment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaEnvironment object { id, archived_at, config, 7 more }`
91- `BetaEnvironment object`
9792
9893 Unified Environment resource for both cloud and self-hosted environments.
9994
from line 104
109104
110105 Environment configuration (either Anthropic Cloud or self-hosted)
111106
112 - `BetaCloudConfig object { networking, packages, type }`
107 - `BetaCloudConfig object`
113108
114109 `cloud` environment configuration.
115110
from line 112
117112
118113 Network configuration policy.
119114
120 - `BetaUnrestrictedNetwork object { type }`
115 - `BetaUnrestrictedNetwork object`
121116
122117 Unrestricted network access.
123118
from line 120
125120
126121 Network policy type
127122
128 - `"unrestricted"`
123 - `BetaLimitedNetwork object`
129124
130 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
131
132125 Limited network access.
133126
134127 - `allow_mcp_servers: boolean`
from line 140
147140
148141 Network policy type
149142
150 - `"limited"`
151
152143 - `packages: BetaPackages`
153144
154145 Package manager configuration.
from line 172
181172
182173 Package configuration type
183174
184 - `"packages"`
175 default: packages
185176
186177 - `type: "cloud"`
187178
188179 Environment type
189180
190 - `"cloud"`
181 - `BetaSelfHostedConfig object`
191182
192 - `BetaSelfHostedConfig object { type }`
193
194183 Configuration for self-hosted environments.
195184
196185 - `type: "self_hosted"`
from line 186
197186
198187 Environment type
199188
200 - `"self_hosted"`
201
202189 - `created_at: string`
203190
204191 RFC 3339 timestamp when environment was created
from line 206
219206
220207 The type of object (always 'environment')
221208
222 - `"environment"`
209 default: environment
223210
224211 - `updated_at: string`
225212
from line 220
233220
234221 - `"account"`
235222
236### Example
223## Example
237224
238```http
225```bash
239226curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/archive \
240227 -X POST \
241228 -H 'anthropic-version: 2023-06-01' \
from line 230
243230 -H "X-Api-Key: $ANTHROPIC_API_KEY"
244231```
245232
246#### Response
233### Response (200)
247234
248235```json
249236{
api/beta/environments/create Changed · +28 / -45 lines
# Create Environment ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Create Environment ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Create Environment
3url: https://platform.claude.com/docs/en/api/beta/environments/create
4---
1# Create Environment
52
6## Create Environment
3**POST** `/v1/environments`
74
8**post** `/v1/environments`
9
105Create a new environment with the specified configuration.
116
12### Header Parameters
7## Headers
138
149- `"anthropic-beta": optional array of AnthropicBeta`
1510
from line 82
8782
8883 - `"mid-conversation-tool-changes-2026-07-01"`
8984
90### Body Parameters
85## Body parameters
9186
9287- `name: string`
9388
9489 Human-readable name for the environment
9590
91 maxLength: 256, minLength: 1
92
9693- `config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams or null`
9794
9895 Environment configuration
9996
100 - `BetaCloudConfigParams object { type, networking, packages }`
97 - `BetaCloudConfigParams object`
10198
10299 Request params for `cloud` environment configuration.
103100
from line 105
108105
109106 Environment type
110107
111 - `"cloud"`
112
113108 - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null`
114109
115110 Network configuration policy. Omit on update to preserve the existing value.
116111
117 - `BetaUnrestrictedNetwork object { type }`
112 - `BetaUnrestrictedNetwork object`
118113
119114 Unrestricted network access.
120115
from line 117
122117
123118 Network policy type
124119
125 - `"unrestricted"`
120 - `BetaLimitedNetworkParams object`
126121
127 - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }`
128
129122 Limited network request params.
130123
131124 Fields default to null; on update, omitted fields preserve the
from line 128
135128
136129 Network policy type
137130
138 - `"limited"`
139
140131 - `allow_mcp_servers: optional boolean or null`
141132
142133 Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
from line 174
183174
184175 Package configuration type
185176
186 - `"packages"`
177 default: packages
187178
188 - `BetaSelfHostedConfigParams object { type }`
179 - `BetaSelfHostedConfigParams object`
189180
190181 Request params for `self_hosted` environment configuration.
191182
from line 184
193184
194185 Environment type
195186
196 - `"self_hosted"`
197
198187- `description: optional string or null`
199188
200189 Optional description of the environment
201190
191 maxLength: 1024
192
202193- `metadata: optional map[string]`
203194
204195 User-provided metadata key-value pairs
from line 202
211202
212203 - `"account"`
213204
214### Returns
205## Returns
215206
216- `BetaEnvironment object { id, archived_at, config, 7 more }`
207- `BetaEnvironment object`
217208
218209 Unified Environment resource for both cloud and self-hosted environments.
219210
from line 220
229220
230221 Environment configuration (either Anthropic Cloud or self-hosted)
231222
232 - `BetaCloudConfig object { networking, packages, type }`
223 - `BetaCloudConfig object`
233224
234225 `cloud` environment configuration.
235226
from line 228
237228
238229 Network configuration policy.
239230
240 - `BetaUnrestrictedNetwork object { type }`
231 - `BetaUnrestrictedNetwork object`
241232
242233 Unrestricted network access.
243234
from line 236
245236
246237 Network policy type
247238
248 - `"unrestricted"`
239 - `BetaLimitedNetwork object`
249240
250 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
251
252241 Limited network access.
253242
254243 - `allow_mcp_servers: boolean`
from line 256
267256
268257 Network policy type
269258
270 - `"limited"`
271
272259 - `packages: BetaPackages`
273260
274261 Package manager configuration.
from line 288
301288
302289 Package configuration type
303290
304 - `"packages"`
291 default: packages
305292
306293 - `type: "cloud"`
307294
308295 Environment type
309296
310 - `"cloud"`
297 - `BetaSelfHostedConfig object`
311298
312 - `BetaSelfHostedConfig object { type }`
313
314299 Configuration for self-hosted environments.
315300
316301 - `type: "self_hosted"`
from line 302
317302
318303 Environment type
319304
320 - `"self_hosted"`
321
322305 - `created_at: string`
323306
324307 RFC 3339 timestamp when environment was created
from line 322
339322
340323 The type of object (always 'environment')
341324
342 - `"environment"`
325 default: environment
343326
344327 - `updated_at: string`
345328
from line 336
353336
354337 - `"account"`
355338
356### Example
339## Example
357340
358```http
341```bash
359342curl https://api.anthropic.com/v1/environments \
360343 -H 'Content-Type: application/json' \
361344 -H 'anthropic-version: 2023-06-01' \
from line 366
383366 }'
384367```
385368
386#### Response
369### Response (200)
387370
388371```json
389372{
api/beta/environments/delete Changed · +10 / -15 lines
# Delete Environment ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Delete Environment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Delete Environment
3url: https://platform.claude.com/docs/en/api/beta/environments/delete
4---
1# Delete Environment
52
6## Delete Environment
3**DELETE** `/v1/environments/{environment_id}`
74
8**delete** `/v1/environments/{environment_id}`
9
105Delete an environment by ID. Returns a confirmation of the deletion.
116
12### Path Parameters
7## Path parameters
138
149- `environment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaEnvironmentDeleteResponse object { id, type }`
91- `BetaEnvironmentDeleteResponse object`
9792
9893 Response after deleting an environment.
9994
from line 100
105100
106101 The type of response
107102
108 - `"environment_deleted"`
103 default: environment_deleted
109104
110### Example
105## Example
111106
112```http
107```bash
113108curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
114109 -X DELETE \
115110 -H 'anthropic-version: 2023-06-01' \
from line 112
117112 -H "X-Api-Key: $ANTHROPIC_API_KEY"
118113```
119114
120#### Response
115### Response (200)
121116
122117```json
123118{
api/beta/environments/list Changed · +20 / -29 lines
# List Environments ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Environments ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Environments
3url: https://platform.claude.com/docs/en/api/beta/environments/list
4---
1# List Environments
52
6## List Environments
3**GET** `/v1/environments`
74
8**get** `/v1/environments`
9
105List environments with pagination support.
116
12### Query Parameters
7## Query parameters
138
149- `include_archived: optional boolean`
1510
1611 Include archived environments in the response
1712
13 default: false
14
1815- `limit: optional number`
1916
2017 Maximum number of environments to return
2118
19 default: 20, maximum: 1000, minimum: 1
20
2221- `page: optional string`
2322
2423 Opaque cursor from previous response for pagination. Pass the `next_page` value from the previous response.
2524
26### Header Parameters
25## Headers
2726
2827- `"anthropic-beta": optional array of AnthropicBeta`
2928
from line 100
101100
102101 - `"mid-conversation-tool-changes-2026-07-01"`
103102
104### Returns
103## Returns
105104
106105- `data: array of BetaEnvironment`
107106
from line 118
119118
120119 Environment configuration (either Anthropic Cloud or self-hosted)
121120
122 - `BetaCloudConfig object { networking, packages, type }`
121 - `BetaCloudConfig object`
123122
124123 `cloud` environment configuration.
125124
from line 126
127126
128127 Network configuration policy.
129128
130 - `BetaUnrestrictedNetwork object { type }`
129 - `BetaUnrestrictedNetwork object`
131130
132131 Unrestricted network access.
133132
from line 134
135134
136135 Network policy type
137136
138 - `"unrestricted"`
137 - `BetaLimitedNetwork object`
139138
140 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
141
142139 Limited network access.
143140
144141 - `allow_mcp_servers: boolean`
from line 154
157154
158155 Network policy type
159156
160 - `"limited"`
161
162157 - `packages: BetaPackages`
163158
164159 Package manager configuration.
from line 186
191186
192187 Package configuration type
193188
194 - `"packages"`
189 default: packages
195190
196191 - `type: "cloud"`
197192
198193 Environment type
199194
200 - `"cloud"`
195 - `BetaSelfHostedConfig object`
201196
202 - `BetaSelfHostedConfig object { type }`
203
204197 Configuration for self-hosted environments.
205198
206199 - `type: "self_hosted"`
from line 200
207200
208201 Environment type
209202
210 - `"self_hosted"`
211
212203 - `created_at: string`
213204
214205 RFC 3339 timestamp when environment was created
from line 220
229220
230221 The type of object (always 'environment')
231222
232 - `"environment"`
223 default: environment
233224
234225 - `updated_at: string`
235226
from line 238
247238
248239 Token for fetching the next page of results. If `null`, there are no more results available. Pass this value to the `page` parameter in the next request.
249240
250### Example
241## Example
251242
252```http
243```bash
253244curl https://api.anthropic.com/v1/environments \
254245 -H 'anthropic-version: 2023-06-01' \
255246 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 247
256247 -H "X-Api-Key: $ANTHROPIC_API_KEY"
257248```
258249
259#### Response
250### Response (200)
260251
261252```json
262253{
api/beta/environments/retrieve Changed · +18 / -31 lines
# Get Environment ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Environment ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Environment
3url: https://platform.claude.com/docs/en/api/beta/environments/retrieve
4---
1# Get Environment
52
6## Get Environment
3**GET** `/v1/environments/{environment_id}`
74
8**get** `/v1/environments/{environment_id}`
9
105Retrieve a specific environment by ID.
116
12### Path Parameters
7## Path parameters
138
149- `environment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaEnvironment object { id, archived_at, config, 7 more }`
91- `BetaEnvironment object`
9792
9893 Unified Environment resource for both cloud and self-hosted environments.
9994
from line 104
109104
110105 Environment configuration (either Anthropic Cloud or self-hosted)
111106
112 - `BetaCloudConfig object { networking, packages, type }`
107 - `BetaCloudConfig object`
113108
114109 `cloud` environment configuration.
115110
from line 112
117112
118113 Network configuration policy.
119114
120 - `BetaUnrestrictedNetwork object { type }`
115 - `BetaUnrestrictedNetwork object`
121116
122117 Unrestricted network access.
123118
from line 120
125120
126121 Network policy type
127122
128 - `"unrestricted"`
123 - `BetaLimitedNetwork object`
129124
130 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
131
132125 Limited network access.
133126
134127 - `allow_mcp_servers: boolean`
from line 140
147140
148141 Network policy type
149142
150 - `"limited"`
151
152143 - `packages: BetaPackages`
153144
154145 Package manager configuration.
from line 172
181172
182173 Package configuration type
183174
184 - `"packages"`
175 default: packages
185176
186177 - `type: "cloud"`
187178
188179 Environment type
189180
190 - `"cloud"`
181 - `BetaSelfHostedConfig object`
191182
192 - `BetaSelfHostedConfig object { type }`
193
194183 Configuration for self-hosted environments.
195184
196185 - `type: "self_hosted"`
from line 186
197186
198187 Environment type
199188
200 - `"self_hosted"`
201
202189 - `created_at: string`
203190
204191 RFC 3339 timestamp when environment was created
from line 206
219206
220207 The type of object (always 'environment')
221208
222 - `"environment"`
209 default: environment
223210
224211 - `updated_at: string`
225212
from line 220
233220
234221 - `"account"`
235222
236### Example
223## Example
237224
238```http
225```bash
239226curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
240227 -H 'anthropic-version: 2023-06-01' \
241228 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 229
242229 -H "X-Api-Key: $ANTHROPIC_API_KEY"
243230```
244231
245#### Response
232### Response (200)
246233
247234```json
248235{
api/beta/environments/update Changed · +29 / -46 lines
# Update Environment ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Update Environment ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Update Environment
3url: https://platform.claude.com/docs/en/api/beta/environments/update
4---
1# Update Environment
52
6## Update Environment
3**POST** `/v1/environments/{environment_id}`
74
8**post** `/v1/environments/{environment_id}`
9
105Update an existing environment's configuration.
116
12### Path Parameters
7## Path parameters
138
149- `environment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Body Parameters
89## Body parameters
9590
9691- `config: optional BetaCloudConfigParams or BetaSelfHostedConfigParams or null`
9792
9893 Updated environment configuration
9994
100 - `BetaCloudConfigParams object { type, networking, packages }`
95 - `BetaCloudConfigParams object`
10196
10297 Request params for `cloud` environment configuration.
10398
from line 103
108103
109104 Environment type
110105
111 - `"cloud"`
112
113106 - `networking: optional BetaUnrestrictedNetwork or BetaLimitedNetworkParams or null`
114107
115108 Network configuration policy. Omit on update to preserve the existing value.
116109
117 - `BetaUnrestrictedNetwork object { type }`
110 - `BetaUnrestrictedNetwork object`
118111
119112 Unrestricted network access.
120113
from line 115
122115
123116 Network policy type
124117
125 - `"unrestricted"`
118 - `BetaLimitedNetworkParams object`
126119
127 - `BetaLimitedNetworkParams object { type, allow_mcp_servers, allow_package_managers, allowed_hosts }`
128
129120 Limited network request params.
130121
131122 Fields default to null; on update, omitted fields preserve the
from line 126
135126
136127 Network policy type
137128
138 - `"limited"`
139
140129 - `allow_mcp_servers: optional boolean or null`
141130
142131 Permits outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` array. Defaults to `false`.
from line 172
183172
184173 Package configuration type
185174
186 - `"packages"`
175 default: packages
187176
188 - `BetaSelfHostedConfigParams object { type }`
177 - `BetaSelfHostedConfigParams object`
189178
190179 Request params for `self_hosted` environment configuration.
191180
from line 182
193182
194183 Environment type
195184
196 - `"self_hosted"`
197
198185- `description: optional string or null`
199186
200187 Updated description of the environment. Omit to preserve; null clears to null; an empty string is stored as an empty string.
201188
189 maxLength: 1024
190
202191- `metadata: optional map[string]`
203192
204193 User-provided metadata key-value pairs. Set a value to null or empty string to delete the key.
from line 196
207196
208197 Updated name for the environment
209198
199 maxLength: 256, minLength: 1
200
210201- `scope: optional "organization" or "account" or null`
211202
212203 The visibility scope for this environment. 'organization' makes the environment visible to all accounts. 'account' restricts visibility to the owning account only.
from line 206
215206
216207 - `"account"`
217208
218### Returns
209## Returns
219210
220- `BetaEnvironment object { id, archived_at, config, 7 more }`
211- `BetaEnvironment object`
221212
222213 Unified Environment resource for both cloud and self-hosted environments.
223214
from line 224
233224
234225 Environment configuration (either Anthropic Cloud or self-hosted)
235226
236 - `BetaCloudConfig object { networking, packages, type }`
227 - `BetaCloudConfig object`
237228
238229 `cloud` environment configuration.
239230
from line 232
241232
242233 Network configuration policy.
243234
244 - `BetaUnrestrictedNetwork object { type }`
235 - `BetaUnrestrictedNetwork object`
245236
246237 Unrestricted network access.
247238
from line 240
249240
250241 Network policy type
251242
252 - `"unrestricted"`
243 - `BetaLimitedNetwork object`
253244
254 - `BetaLimitedNetwork object { allow_mcp_servers, allow_package_managers, allowed_hosts, type }`
255
256245 Limited network access.
257246
258247 - `allow_mcp_servers: boolean`
from line 260
271260
272261 Network policy type
273262
274 - `"limited"`
275
276263 - `packages: BetaPackages`
277264
278265 Package manager configuration.
from line 292
305292
306293 Package configuration type
307294
308 - `"packages"`
295 default: packages
309296
310297 - `type: "cloud"`
311298
312299 Environment type
313300
314 - `"cloud"`
301 - `BetaSelfHostedConfig object`
315302
316 - `BetaSelfHostedConfig object { type }`
317
318303 Configuration for self-hosted environments.
319304
320305 - `type: "self_hosted"`
from line 306
321306
322307 Environment type
323308
324 - `"self_hosted"`
325
326309 - `created_at: string`
327310
328311 RFC 3339 timestamp when environment was created
from line 326
343326
344327 The type of object (always 'environment')
345328
346 - `"environment"`
329 default: environment
347330
348331 - `updated_at: string`
349332
from line 340
357340
358341 - `"account"`
359342
360### Example
343## Example
361344
362```http
345```bash
363346curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID \
364347 -H 'Content-Type: application/json' \
365348 -H 'anthropic-version: 2023-06-01' \
from line 353
370353 }'
371354```
372355
373#### Response
356### Response (200)
374357
375358```json
376359{
api/beta/environments/work Changed · +87 / -96 lines
### Path parameters ### Headers #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Headers ### Body parameters #### Response (200) ### Path parameters ### Headers #### Response (200) ## Domain types ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Header Parameters ### Body Parameters #### Response ### Path Parameters ### Header Parameters #### Response ## Domain Types
from line 1
1---
2title: Work
3url: https://platform.claude.com/docs/en/api/beta/environments/work
4---
5
61# Work
72
83## Get Work Item
94
10**get** `/v1/environments/{environment_id}/work/{work_id}`
5**GET** `/v1/environments/{environment_id}/work/{work_id}`
116
127Note: 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.
138
149Retrieve detailed information about a specific work item.
1510
16### Path Parameters
11### Path parameters
1712
1813- `environment_id: string`
1914
2015- `work_id: string`
2116
22### Header Parameters
17### Headers
2318
2419- `"anthropic-beta": optional array of AnthropicBeta`
2520
from line 94
9994
10095### Returns
10196
102- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
97- `BetaSelfHostedWork object`
10398
10499 Work resource representing a unit of work in a self-hosted environment.
105100
from line 126
131126
132127 Type of work data
133128
134 - `"session"`
135
136129 - `environment_id: string`
137130
138131 Environment identifier this work belongs to (e.g., `env_...`)
from line 172
179172
180173 The type of object (always 'work')
181174
182 - `"work"`
175 default: work
183176
184177### Example
185178
186```http
179```bash
187180curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \
188181 -H 'anthropic-version: 2023-06-01' \
189182 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 183
190183 -H "X-Api-Key: $ANTHROPIC_API_KEY"
191184```
192185
193#### Response
186#### Response (200)
194187
195188```json
196189{
from line 210
217210
218211## Poll for Work
219212
220**get** `/v1/environments/{environment_id}/work/poll`
213**GET** `/v1/environments/{environment_id}/work/poll`
221214
222215Note: 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.
223216
224217Long poll for work items in the queue.
225218
226### Path Parameters
219### Path parameters
227220
228221- `environment_id: string`
229222
230### Query Parameters
223### Query parameters
231224
232225- `block_ms: optional number`
233226
234227 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).
235228
229 minimum: 1
230
236231- `reclaim_older_than_ms: optional number`
237232
238233 Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms).
239234
240### Header Parameters
235 minimum: 1
241236
237### Headers
238
242239- `"anthropic-beta": optional array of AnthropicBeta`
243240
244241 Optional header to specify the beta version(s) you want to use.
from line 318
321318
322319### Returns
323320
324- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
321- `BetaSelfHostedWork object`
325322
326323 Work resource representing a unit of work in a self-hosted environment.
327324
from line 350
353350
354351 Type of work data
355352
356 - `"session"`
357
358353 - `environment_id: string`
359354
360355 Environment identifier this work belongs to (e.g., `env_...`)
from line 396
401396
402397 The type of object (always 'work')
403398
404 - `"work"`
399 default: work
405400
406401### Example
407402
408```http
403```bash
409404curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/poll \
410405 -H 'anthropic-version: 2023-06-01' \
411406 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 407
412407 -H "X-Api-Key: $ANTHROPIC_API_KEY"
413408```
414409
415#### Response
410#### Response (200)
416411
417412```json
418413{
from line 434
439434
440435## Acknowledge Work
441436
442**post** `/v1/environments/{environment_id}/work/{work_id}/ack`
437**POST** `/v1/environments/{environment_id}/work/{work_id}/ack`
443438
444439Note: 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.
445440
446441Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue.
447442
448### Path Parameters
443### Path parameters
449444
450445- `environment_id: string`
451446
452447- `work_id: string`
453448
454### Header Parameters
449### Headers
455450
456451- `"anthropic-beta": optional array of AnthropicBeta`
457452
from line 526
531526
532527### Returns
533528
534- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
529- `BetaSelfHostedWork object`
535530
536531 Work resource representing a unit of work in a self-hosted environment.
537532
from line 558
563558
564559 Type of work data
565560
566 - `"session"`
567
568561 - `environment_id: string`
569562
570563 Environment identifier this work belongs to (e.g., `env_...`)
from line 604
611604
612605 The type of object (always 'work')
613606
614 - `"work"`
607 default: work
615608
616609### Example
617610
618```http
611```bash
619612curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/ack \
620613 -X POST \
621614 -H 'anthropic-version: 2023-06-01' \
from line 616
623616 -H "X-Api-Key: $ANTHROPIC_API_KEY"
624617```
625618
626#### Response
619#### Response (200)
627620
628621```json
629622{
from line 643
650643
651644## Record Heartbeat
652645
653**post** `/v1/environments/{environment_id}/work/{work_id}/heartbeat`
646**POST** `/v1/environments/{environment_id}/work/{work_id}/heartbeat`
654647
655648Note: 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.
656649
657650Record a heartbeat for a work item to maintain the lease.
658651
659### Path Parameters
652### Path parameters
660653
661654- `environment_id: string`
662655
663656- `work_id: string`
664657
665### Query Parameters
658### Query parameters
666659
667660- `desired_ttl_seconds: optional number`
668661
from line 665
672665
673666 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.
674667
675### Header Parameters
668### Headers
676669
677670- `"anthropic-beta": optional array of AnthropicBeta`
678671
from line 745
752745
753746### Returns
754747
755- `BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }`
748- `BetaSelfHostedWorkHeartbeatResponse object`
756749
757750 Response after recording a heartbeat for a work item.
758751
from line 779
786779
787780 The type of response
788781
789 - `"work_heartbeat"`
782 default: work_heartbeat
790783
791784### Example
792785
793```http
786```bash
794787curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/heartbeat \
795788 -X POST \
796789 -H 'anthropic-version: 2023-06-01' \
from line 791
798791 -H "X-Api-Key: $ANTHROPIC_API_KEY"
799792```
800793
801#### Response
794#### Response (200)
802795
803796```json
804797{
from line 805
812805
813806## Stop Work
814807
815**post** `/v1/environments/{environment_id}/work/{work_id}/stop`
808**POST** `/v1/environments/{environment_id}/work/{work_id}/stop`
816809
817810Note: 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.
818811
819812Stop a work item, initiating graceful or forced shutdown.
820813
821### Path Parameters
814### Path parameters
822815
823816- `environment_id: string`
824817
825818- `work_id: string`
826819
827### Header Parameters
820### Headers
828821
829822- `"anthropic-beta": optional array of AnthropicBeta`
830823
from line 895
902895
903896 - `"mid-conversation-tool-changes-2026-07-01"`
904897
905### Body Parameters
898### Body parameters
906899
907900- `force: optional boolean`
908901
909902 If true, immediately stop work without graceful shutdown
910903
904 default: false
905
911906### Returns
912907
913- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
908- `BetaSelfHostedWork object`
914909
915910 Work resource representing a unit of work in a self-hosted environment.
916911
from line 937
942937
943938 Type of work data
944939
945 - `"session"`
946
947940 - `environment_id: string`
948941
949942 Environment identifier this work belongs to (e.g., `env_...`)
from line 983
990983
991984 The type of object (always 'work')
992985
993 - `"work"`
986 default: work
994987
995988### Example
996989
997```http
990```bash
998991curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/stop \
999992 -H 'Content-Type: application/json' \
1000993 -H 'anthropic-version: 2023-06-01' \
from line 996
1003996 -d '{}'
1004997```
1005998
1006#### Response
999#### Response (200)
10071000
10081001```json
10091002{
from line 1023
10301023
10311024## List Work Items
10321025
1033**get** `/v1/environments/{environment_id}/work`
1026**GET** `/v1/environments/{environment_id}/work`
10341027
10351028Note: 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.
10361029
10371030List work items in an environment.
10381031
1039### Path Parameters
1032### Path parameters
10401033
10411034- `environment_id: string`
10421035
1043### Query Parameters
1036### Query parameters
10441037
10451038- `limit: optional number`
10461039
10471040 Maximum number of work items to return
10481041
1042 default: 20, maximum: 1000, minimum: 1
1043
10491044- `page: optional string`
10501045
10511046 Opaque cursor from previous response for pagination
10521047
1053### Header Parameters
1048### Headers
10541049
10551050- `"anthropic-beta": optional array of AnthropicBeta`
10561051
from line 1125
11301125
11311126### Returns
11321127
1133- `BetaSelfHostedWorkListResponse object { data, next_page }`
1128- `BetaSelfHostedWorkListResponse object`
11341129
11351130 Response when listing work items with cursor-based pagination.
11361131
from line 1157
11621157
11631158 Type of work data
11641159
1165 - `"session"`
1166
11671160 - `environment_id: string`
11681161
11691162 Environment identifier this work belongs to (e.g., `env_...`)
from line 1203
12101203
12111204 The type of object (always 'work')
12121205
1213 - `"work"`
1206 default: work
12141207
12151208 - `next_page: string or null`
12161209
from line 1211
12181211
12191212### Example
12201213
1221```http
1214```bash
12221215curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work \
12231216 -H 'anthropic-version: 2023-06-01' \
12241217 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 1218
12251218 -H "X-Api-Key: $ANTHROPIC_API_KEY"
12261219```
12271220
1228#### Response
1221#### Response (200)
12291222
12301223```json
12311224{
from line 1250
12571250
12581251## Update Work Item
12591252
1260**post** `/v1/environments/{environment_id}/work/{work_id}`
1253**POST** `/v1/environments/{environment_id}/work/{work_id}`
12611254
12621255Note: 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.
12631256
12641257Update work item metadata with merge semantics.
12651258
1266### Path Parameters
1259### Path parameters
12671260
12681261- `environment_id: string`
12691262
12701263- `work_id: string`
12711264
1272### Header Parameters
1265### Headers
12731266
12741267- `"anthropic-beta": optional array of AnthropicBeta`
12751268
from line 1340
13471340
13481341 - `"mid-conversation-tool-changes-2026-07-01"`
13491342
1350### Body Parameters
1343### Body parameters
13511344
13521345- `metadata: map[string]`
13531346
from line 1348
13551348
13561349### Returns
13571350
1358- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
1351- `BetaSelfHostedWork object`
13591352
13601353 Work resource representing a unit of work in a self-hosted environment.
13611354
from line 1380
13871380
13881381 Type of work data
13891382
1390 - `"session"`
1391
13921383 - `environment_id: string`
13931384
13941385 Environment identifier this work belongs to (e.g., `env_...`)
from line 1426
14351426
14361427 The type of object (always 'work')
14371428
1438 - `"work"`
1429 default: work
14391430
14401431### Example
14411432
1442```http
1433```bash
14431434curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \
14441435 -H 'Content-Type: application/json' \
14451436 -H 'anthropic-version: 2023-06-01' \
from line 1443
14521443 }'
14531444```
14541445
1455#### Response
1446#### Response (200)
14561447
14571448```json
14581449{
from line 1470
14791470
14801471## Get Queue Statistics
14811472
1482**get** `/v1/environments/{environment_id}/work/stats`
1473**GET** `/v1/environments/{environment_id}/work/stats`
14831474
14841475Get statistics about the work queue for an environment.
14851476
1486### Path Parameters
1477### Path parameters
14871478
14881479- `environment_id: string`
14891480
1490### Header Parameters
1481### Headers
14911482
14921483- `"anthropic-beta": optional array of AnthropicBeta`
14931484
from line 1558
15671558
15681559### Returns
15691560
1570- `BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }`
1561- `BetaSelfHostedWorkQueueStats object`
15711562
15721563 Statistics about the work queue for an environment.
15731564
from line 1576
15851576
15861577 Number of work items being processed (polled but not acknowledged)
15871578
1579 default: 0
1580
15881581 - `type: "work_queue_stats"`
15891582
15901583 The type of object
15911584
1592 - `"work_queue_stats"`
1585 default: work_queue_stats
15931586
15941587 - `workers_polling: number or null`
15951588
from line 1590
15971590
15981591### Example
15991592
1600```http
1593```bash
16011594curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/stats \
16021595 -H 'anthropic-version: 2023-06-01' \
16031596 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 1597
16041597 -H "X-Api-Key: $ANTHROPIC_API_KEY"
16051598```
16061599
1607#### Response
1600#### Response (200)
16081601
16091602```json
16101603{
from line 1609
16161609}
16171610```
16181611
1619## Domain Types
1612## Domain types
16201613
16211614### Beta Self Hosted Work
16221615
1623- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
1616- `BetaSelfHostedWork object`
16241617
16251618 Work resource representing a unit of work in a self-hosted environment.
16261619
from line 1645
16521645
16531646 Type of work data
16541647
1655 - `"session"`
1656
16571648 - `environment_id: string`
16581649
16591650 Environment identifier this work belongs to (e.g., `env_...`)
from line 1691
17001691
17011692 The type of object (always 'work')
17021693
1703 - `"work"`
1694 default: work
17041695
17051696### Beta Self Hosted Work Heartbeat Response
17061697
1707- `BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }`
1698- `BetaSelfHostedWorkHeartbeatResponse object`
17081699
17091700 Response after recording a heartbeat for a work item.
17101701
from line 1729
17381729
17391730 The type of response
17401731
1741 - `"work_heartbeat"`
1732 default: work_heartbeat
17421733
17431734### Beta Self Hosted Work List Response
17441735
1745- `BetaSelfHostedWorkListResponse object { data, next_page }`
1736- `BetaSelfHostedWorkListResponse object`
17461737
17471738 Response when listing work items with cursor-based pagination.
17481739
from line 1765
17741765
17751766 Type of work data
17761767
1777 - `"session"`
1778
17791768 - `environment_id: string`
17801769
17811770 Environment identifier this work belongs to (e.g., `env_...`)
from line 1811
18221811
18231812 The type of object (always 'work')
18241813
1825 - `"work"`
1814 default: work
18261815
18271816 - `next_page: string or null`
18281817
from line 1819
18301819
18311820### Beta Self Hosted Work Queue Stats
18321821
1833- `BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }`
1822- `BetaSelfHostedWorkQueueStats object`
18341823
18351824 Statistics about the work queue for an environment.
18361825
from line 1837
18481837
18491838 Number of work items being processed (polled but not acknowledged)
18501839
1840 default: 0
1841
18511842 - `type: "work_queue_stats"`
18521843
18531844 The type of object
18541845
1855 - `"work_queue_stats"`
1846 default: work_queue_stats
18561847
18571848 - `workers_polling: number or null`
18581849
from line 1851
18601851
18611852### Beta Self Hosted Work Stop Request
18621853
1863- `BetaSelfHostedWorkStopRequest object { force }`
1854- `BetaSelfHostedWorkStopRequest object`
18641855
18651856 Request to stop a work item.
18661857
from line 1859
18681859
18691860 If true, immediately stop work without graceful shutdown
18701861
1862 default: false
1863
18711864### Beta Self Hosted Work Update Request
18721865
1873- `BetaSelfHostedWorkUpdateRequest object { metadata }`
1866- `BetaSelfHostedWorkUpdateRequest object`
18741867
18751868 Request to update work item metadata.
18761869
from line 1873
18801873
18811874### Beta Session Work Data
18821875
1883- `BetaSessionWorkData object { id, type }`
1876- `BetaSessionWorkData object`
18841877
18851878 Work data for session work items.
18861879
from line 1887
18941887 - `type: "session"`
18951888
18961889 Type of work data
1897
1898 - `"session"`
18991890
api/beta/environments/work/ack Changed · +14 / -21 lines
# Acknowledge Work ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Acknowledge Work ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Acknowledge Work
3url: https://platform.claude.com/docs/en/api/beta/environments/work/ack
4---
1# Acknowledge Work
52
6## Acknowledge Work
3**POST** `/v1/environments/{environment_id}/work/{work_id}/ack`
74
8**post** `/v1/environments/{environment_id}/work/{work_id}/ack`
9
105Note: 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.
116
127Acknowledge receipt of a work item, transitioning it from 'queued' to 'starting' and removing it from the queue.
138
14### Path Parameters
9## Path parameters
1510
1611- `environment_id: string`
1712
1813- `work_id: string`
1914
20### Header Parameters
15## Headers
2116
2217- `"anthropic-beta": optional array of AnthropicBeta`
2318
from line 90
9590
9691 - `"mid-conversation-tool-changes-2026-07-01"`
9792
98### Returns
93## Returns
9994
100- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
95- `BetaSelfHostedWork object`
10196
10297 Work resource representing a unit of work in a self-hosted environment.
10398
from line 124
129124
130125 Type of work data
131126
132 - `"session"`
133
134127 - `environment_id: string`
135128
136129 Environment identifier this work belongs to (e.g., `env_...`)
from line 170
177170
178171 The type of object (always 'work')
179172
180 - `"work"`
173 default: work
181174
182### Example
175## Example
183176
184```http
177```bash
185178curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/ack \
186179 -X POST \
187180 -H 'anthropic-version: 2023-06-01' \
from line 182
189182 -H "X-Api-Key: $ANTHROPIC_API_KEY"
190183```
191184
192#### Response
185### Response (200)
193186
194187```json
195188{
api/beta/environments/work/heartbeat Changed · +11 / -16 lines
# Record Heartbeat ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## Record Heartbeat ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Record Heartbeat
3url: https://platform.claude.com/docs/en/api/beta/environments/work/heartbeat
4---
1# Record Heartbeat
52
6## Record Heartbeat
3**POST** `/v1/environments/{environment_id}/work/{work_id}/heartbeat`
74
8**post** `/v1/environments/{environment_id}/work/{work_id}/heartbeat`
9
105Note: 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.
116
127Record a heartbeat for a work item to maintain the lease.
138
14### Path Parameters
9## Path parameters
1510
1611- `environment_id: string`
1712
1813- `work_id: string`
1914
20### Query Parameters
15## Query parameters
2116
2217- `desired_ttl_seconds: optional number`
2318
from line 22
2722
2823 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.
2924
30### Header Parameters
25## Headers
3126
3227- `"anthropic-beta": optional array of AnthropicBeta`
3328
from line 100
105100
106101 - `"mid-conversation-tool-changes-2026-07-01"`
107102
108### Returns
103## Returns
109104
110- `BetaSelfHostedWorkHeartbeatResponse object { last_heartbeat, lease_extended, state, 2 more }`
105- `BetaSelfHostedWorkHeartbeatResponse object`
111106
112107 Response after recording a heartbeat for a work item.
113108
from line 136
141136
142137 The type of response
143138
144 - `"work_heartbeat"`
139 default: work_heartbeat
145140
146### Example
141## Example
147142
148```http
143```bash
149144curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/heartbeat \
150145 -X POST \
151146 -H 'anthropic-version: 2023-06-01' \
from line 148
153148 -H "X-Api-Key: $ANTHROPIC_API_KEY"
154149```
155150
156#### Response
151### Response (200)
157152
158153```json
159154{
api/beta/environments/work/list Changed · +16 / -21 lines
# List Work Items ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## List Work Items ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: List Work Items
3url: https://platform.claude.com/docs/en/api/beta/environments/work/list
4---
1# List Work Items
52
6## List Work Items
3**GET** `/v1/environments/{environment_id}/work`
74
8**get** `/v1/environments/{environment_id}/work`
9
105Note: 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.
116
127List work items in an environment.
138
14### Path Parameters
9## Path parameters
1510
1611- `environment_id: string`
1712
18### Query Parameters
13## Query parameters
1914
2015- `limit: optional number`
2116
2217 Maximum number of work items to return
2318
19 default: 20, maximum: 1000, minimum: 1
20
2421- `page: optional string`
2522
2623 Opaque cursor from previous response for pagination
2724
28### Header Parameters
25## Headers
2926
3027- `"anthropic-beta": optional array of AnthropicBeta`
3128
from line 100
103100
104101 - `"mid-conversation-tool-changes-2026-07-01"`
105102
106### Returns
103## Returns
107104
108- `BetaSelfHostedWorkListResponse object { data, next_page }`
105- `BetaSelfHostedWorkListResponse object`
109106
110107 Response when listing work items with cursor-based pagination.
111108
from line 134
137134
138135 Type of work data
139136
140 - `"session"`
141
142137 - `environment_id: string`
143138
144139 Environment identifier this work belongs to (e.g., `env_...`)
from line 180
185180
186181 The type of object (always 'work')
187182
188 - `"work"`
183 default: work
189184
190185 - `next_page: string or null`
191186
192187 Opaque cursor for fetching the next page of results
193188
194### Example
189## Example
195190
196```http
191```bash
197192curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work \
198193 -H 'anthropic-version: 2023-06-01' \
199194 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 195
200195 -H "X-Api-Key: $ANTHROPIC_API_KEY"
201196```
202197
203#### Response
198### Response (200)
204199
205200```json
206201{
api/beta/environments/work/poll Changed · +19 / -22 lines
# Poll for Work ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## Poll for Work ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Poll for Work
3url: https://platform.claude.com/docs/en/api/beta/environments/work/poll
4---
1# Poll for Work
52
6## Poll for Work
3**GET** `/v1/environments/{environment_id}/work/poll`
74
8**get** `/v1/environments/{environment_id}/work/poll`
9
105Note: 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.
116
127Long poll for work items in the queue.
138
14### Path Parameters
9## Path parameters
1510
1611- `environment_id: string`
1712
18### Query Parameters
13## Query parameters
1914
2015- `block_ms: optional number`
2116
2217 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).
2318
19 minimum: 1
20
2421- `reclaim_older_than_ms: optional number`
2522
2623 Reclaim unacknowledged work items older than this many milliseconds. If omitted, uses the default (5000ms).
2724
28### Header Parameters
25 minimum: 1
2926
27## Headers
28
3029- `"anthropic-beta": optional array of AnthropicBeta`
3130
3231 Optional header to specify the beta version(s) you want to use.
from line 106
107106
108107 Unique identifier for the specific worker polling, used to track aggregated environment-level work metrics in Console
109108
110### Returns
109## Returns
111110
112- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
111- `BetaSelfHostedWork object`
113112
114113 Work resource representing a unit of work in a self-hosted environment.
115114
from line 140
141140
142141 Type of work data
143142
144 - `"session"`
145
146143 - `environment_id: string`
147144
148145 Environment identifier this work belongs to (e.g., `env_...`)
from line 186
189186
190187 The type of object (always 'work')
191188
192 - `"work"`
189 default: work
193190
194### Example
191## Example
195192
196```http
193```bash
197194curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/poll \
198195 -H 'anthropic-version: 2023-06-01' \
199196 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 197
200197 -H "X-Api-Key: $ANTHROPIC_API_KEY"
201198```
202199
203#### Response
200### Response (200)
204201
205202```json
206203{
api/beta/environments/work/retrieve Changed · +14 / -21 lines
# Get Work Item ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Work Item ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Work Item
3url: https://platform.claude.com/docs/en/api/beta/environments/work/retrieve
4---
1# Get Work Item
52
6## Get Work Item
3**GET** `/v1/environments/{environment_id}/work/{work_id}`
74
8**get** `/v1/environments/{environment_id}/work/{work_id}`
9
105Note: 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.
116
127Retrieve detailed information about a specific work item.
138
14### Path Parameters
9## Path parameters
1510
1611- `environment_id: string`
1712
1813- `work_id: string`
1914
20### Header Parameters
15## Headers
2116
2217- `"anthropic-beta": optional array of AnthropicBeta`
2318
from line 90
9590
9691 - `"mid-conversation-tool-changes-2026-07-01"`
9792
98### Returns
93## Returns
9994
100- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
95- `BetaSelfHostedWork object`
10196
10297 Work resource representing a unit of work in a self-hosted environment.
10398
from line 124
129124
130125 Type of work data
131126
132 - `"session"`
133
134127 - `environment_id: string`
135128
136129 Environment identifier this work belongs to (e.g., `env_...`)
from line 170
177170
178171 The type of object (always 'work')
179172
180 - `"work"`
173 default: work
181174
182### Example
175## Example
183176
184```http
177```bash
185178curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID \
186179 -H 'anthropic-version: 2023-06-01' \
187180 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 181
188181 -H "X-Api-Key: $ANTHROPIC_API_KEY"
189182```
190183
191#### Response
184### Response (200)
192185
193186```json
194187{
api/beta/environments/work/stats Changed · +12 / -15 lines
# Get Queue Statistics ## Path parameters ## Headers ## Returns ## Example ### Response (200) ## Get Queue Statistics ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Get Queue Statistics
3url: https://platform.claude.com/docs/en/api/beta/environments/work/stats
4---
1# Get Queue Statistics
52
6## Get Queue Statistics
3**GET** `/v1/environments/{environment_id}/work/stats`
74
8**get** `/v1/environments/{environment_id}/work/stats`
9
105Get statistics about the work queue for an environment.
116
12### Path Parameters
7## Path parameters
138
149- `environment_id: string`
1510
16### Header Parameters
11## Headers
1712
1813- `"anthropic-beta": optional array of AnthropicBeta`
1914
from line 86
9186
9287 - `"mid-conversation-tool-changes-2026-07-01"`
9388
94### Returns
89## Returns
9590
96- `BetaSelfHostedWorkQueueStats object { depth, oldest_queued_at, pending, 2 more }`
91- `BetaSelfHostedWorkQueueStats object`
9792
9893 Statistics about the work queue for an environment.
9994
from line 106
111106
112107 Number of work items being processed (polled but not acknowledged)
113108
109 default: 0
110
114111 - `type: "work_queue_stats"`
115112
116113 The type of object
117114
118 - `"work_queue_stats"`
115 default: work_queue_stats
119116
120117 - `workers_polling: number or null`
121118
122119 Number of workers that have polled for work in the last 30 seconds. Requires worker_id to be sent with poll requests.
123120
124### Example
121## Example
125122
126```http
123```bash
127124curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/stats \
128125 -H 'anthropic-version: 2023-06-01' \
129126 -H 'anthropic-beta: managed-agents-2026-04-01' \
from line 127
130127 -H "X-Api-Key: $ANTHROPIC_API_KEY"
131128```
132129
133#### Response
130### Response (200)
134131
135132```json
136133{
api/beta/environments/work/stop Changed · +17 / -22 lines
# Stop Work ## Path parameters ## Headers ## Body parameters ## Returns ## Example ### Response (200) ## Stop Work ### Path Parameters ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
from line 1
1---
2title: Stop Work
3url: https://platform.claude.com/docs/en/api/beta/environments/work/stop
4---
1# Stop Work
52
6## Stop Work
3**POST** `/v1/environments/{environment_id}/work/{work_id}/stop`
74
8**post** `/v1/environments/{environment_id}/work/{work_id}/stop`
9
105Note: 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.
116
127Stop a work item, initiating graceful or forced shutdown.
138
14### Path Parameters
9## Path parameters
1510
1611- `environment_id: string`
1712
1813- `work_id: string`
1914
20### Header Parameters
15## Headers
2116
2217- `"anthropic-beta": optional array of AnthropicBeta`
2318
from line 90
9590
9691 - `"mid-conversation-tool-changes-2026-07-01"`
9792
98### Body Parameters
93## Body parameters
9994
10095- `force: optional boolean`
10196
10297 If true, immediately stop work without graceful shutdown
10398
104### Returns
99 default: false
105100
106- `BetaSelfHostedWork object { id, acknowledged_at, created_at, 10 more }`
101## Returns
107102
103- `BetaSelfHostedWork object`
104
108105 Work resource representing a unit of work in a self-hosted environment.
109106
110107 Work items are queued when sessions are created or when long-dormant sessions
from line 132
135132
136133 Type of work data
137134
138 - `"session"`
139
140135 - `environment_id: string`
141136
142137 Environment identifier this work belongs to (e.g., `env_...`)
from line 178
183178
184179 The type of object (always 'work')
185180
186 - `"work"`
181 default: work
187182
188### Example
183## Example
189184
190```http
185```bash
191186curl https://api.anthropic.com/v1/environments/$ENVIRONMENT_ID/work/$WORK_ID/stop \
192187 -H 'Content-Type: application/json' \
193188 -H 'anthropic-version: 2023-06-01' \
from line 191
196191 -d '{}'
197192```
198193
199#### Response
194### Response (200)
200195
201196```json
202197{