The whole hunk
from line 1, old and new numbered
/
lines
from line 1
1---
2title: Create Deployment
3url: https://platform.claude.com/docs/en/api/beta/deployments/create
4---
5
16# Create Deployment
27
38**POST** `/v1/deployments`
from line 17
1217
1318 - `string`
1419
15 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
20 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
1621
1722 - `"message-batches-2024-09-24"`
1823
from line 65
6065
6166 - `"user-profiles-2026-08-18"`
6267
68 - `"user-profiles-2026-09-04"`
69
6370 - `"advisor-tool-2026-03-01"`
6471
6572 - `"managed-agents-2026-04-01"`
from line 109
102109
103110 - `"mid-conversation-system-clear-at-2026-08-21"`
104111
112- `"anthropic-workspace-id": optional string`
113
105114## Body parameters
106115
107116- `agent: string or BetaManagedAgentsAgentParams`
from line 123
114123
115124 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
116125
126 - `type: "agent"`
127
117128 - `id: string`
118129
119130 The `agent` ID.
from line 131
120131
121132 minLength: 1, maxLength: 128
122133
123 - `type: "agent"`
124
125134 - `version: optional number`
126135
127136 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
from line 151
142151
143152 Parameters for sending a user message to the session.
144153
154 - `type: "user.message"`
155
145156 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
146157
147158 Array of content blocks for the user message.
from line 161
150161
151162 Regular text content.
152163
164 - `type: "text"`
165
153166 - `text: string`
154167
155168 The text content.
from line 169
156169
157170 minLength: 1
158171
159 - `type: "text"`
160
161172 - `BetaManagedAgentsImageBlock object`
162173
163174 Image content specified directly as base64 data or as a reference via a URL.
164175
176 - `type: "image"`
177
165178 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
166179
167180 Union type for image source variants.
from line 183
170183
171184 Base64-encoded image data.
172185
186 - `type: "base64"`
187
173188 - `data: string`
174189
175190 Base64-encoded image data.
from line 197
182197
183198 minLength: 1
184199
185 - `type: "base64"`
186
187200 - `BetaManagedAgentsURLImageSource object`
188201
189202 Image referenced by URL.
from line 213
200213
201214 Image referenced by file ID.
202215
216 - `type: "file"`
217
203218 - `file_id: string`
204219
205220 ID of a previously uploaded file.
from line 221
206221
207222 minLength: 1
208223
209 - `type: "file"`
210
211 - `type: "image"`
212
213224 - `BetaManagedAgentsDocumentBlock object`
214225
215226 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
216227
228 - `type: "document"`
229
217230 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
218231
219232 Union type for document source variants.
from line 235
222235
223236 Base64-encoded document data.
224237
238 - `type: "base64"`
239
225240 - `data: string`
226241
227242 Base64-encoded document data.
from line 249
234249
235250 minLength: 1
236251
237 - `type: "base64"`
238
239252 - `BetaManagedAgentsPlainTextDocumentSource object`
240253
241254 Plain text document content.
242255
256 - `type: "text"`
257
243258 - `data: string`
244259
245260 The plain text content.
from line 265
250265
251266 MIME type of the text content. Must be "text/plain".
252267
253 - `type: "text"`
254
255268 - `BetaManagedAgentsURLDocumentSource object`
256269
257270 Document referenced by URL.
from line 281
268281
269282 Document referenced by file ID.
270283
284 - `type: "file"`
285
271286 - `file_id: string`
272287
273288 ID of a previously uploaded file.
from line 289
274289
275290 minLength: 1
276291
277 - `type: "file"`
278
279 - `type: "document"`
280
281292 - `context: optional string or null`
282293
283294 Additional context about the document for the model.
from line 303
292303
293304 - `type: "redacted"`
294305
295 - `type: "user.message"`
296
297306 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
298307
299308 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
300309
310 - `type: "user.define_outcome"`
311
301312 - `description: string`
302313
303314 What the agent should produce. This is the task specification.
from line 321
310321
311322 Rubric referenced by a file uploaded via the Files API.
312323
324 - `type: "file"`
325
313326 - `file_id: string`
314327
315328 ID of the rubric file.
316329
317 - `type: "file"`
318
319330 - `BetaManagedAgentsTextRubricParams object`
320331
321332 Rubric content provided inline as text.
322333
334 - `type: "text"`
335
323336 - `content: string`
324337
325338 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
from line 339
326339
327340 maxLength: 262144
328341
329 - `type: "text"`
330
331 - `type: "user.define_outcome"`
332
333342 - `max_iterations: optional number or null`
334343
335344 Eval→revision cycles before giving up. Default 3, max 20.
from line 349
340349
341350 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.
342351
352 - `type: "system.message"`
353
343354 - `content: array of BetaManagedAgentsSystemContentBlock`
344355
345356 System content blocks to append. Text-only.
346357
358 - `type: "text"`
359
347360 - `text: string`
348361
349362 The text content.
from line 363
350363
351364 minLength: 1
352365
353 - `type: "text"`
354
355 - `type: "system.message"`
356
357366- `name: string`
358367
359368 Human-readable name for the deployment.
from line 373
364373
365374 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
366375
376 - `type: "limit"`
377
367378 - `max_list_cost: BetaMonetaryAmount`
368379
369380 A monetary amount in a specific currency.
from line 387
376387
377388 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.
378389
379 - `type: "limit"`
380
381390- `description: optional string or null`
382391
383392 Description of what the deployment does.
from line 405
396405
397406 Mount a GitHub repository into the session's container.
398407
399 - `authorization_token: string`
400
401 GitHub authorization token used to clone the repository.
402
403 minLength: 1, maxLength: 4096
404
405408 - `type: "github_repository"`
406409
407410 - `url: string`
from line 413
410413
411414 minLength: 1, maxLength: 2048
412415
416 - `authorization_token: optional string`
417
418 GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.
419
420 minLength: 1, maxLength: 4096
421
413422 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
414423
415424 Branch or commit to check out. Defaults to the repository's default branch.
from line 425
416425
417426 - `BetaManagedAgentsBranchCheckout object`
418427
428 - `type: "branch"`
429
419430 - `name: string`
420431
421432 Branch name to check out.
from line 433
422433
423434 minLength: 1, maxLength: 255
424435
425 - `type: "branch"`
426
427436 - `BetaManagedAgentsCommitCheckout object`
428437
438 - `type: "commit"`
439
429440 - `sha: string`
430441
431442 Full commit SHA to check out.
from line 443
432443
433444 minLength: 7, maxLength: 64
434445
435 - `type: "commit"`
436
437446 - `mount_path: optional string or null`
438447
439448 Mount path in the container. Defaults to `/workspace/<repo-name>`.
from line 453
444453
445454 Mount a file uploaded via the Files API into the session.
446455
456 - `type: "file"`
457
447458 - `file_id: string`
448459
449460 ID of a previously uploaded file.
from line 461
450461
451462 minLength: 1, maxLength: 128
452463
453 - `type: "file"`
454
455464 - `mount_path: optional string or null`
456465
457466 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
from line 471
462471
463472 Parameters for attaching a memory store to an agent session.
464473
474 - `type: "memory_store"`
475
465476 - `memory_store_id: string`
466477
467478 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
468479
469 - `type: "memory_store"`
470
471480 - `access: optional "read_write" or "read_only" or null`
472481
473482 Access mode for an attached memory store.
from line 495
486495
487496 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
488497
498 - `type: "cron"`
499
489500 - `expression: string`
490501
491502 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).
from line 509
498509
499510 minLength: 1
500511
501 - `type: "cron"`
502
503512- `vault_ids: optional array of string`
504513
505514 Vault IDs for stored credentials the agent can use during sessions created from this deployment. Maximum 50.
from line 519
510519
511520 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.
512521
522 - `type: "deployment"`
523
513524 - `id: string`
514525
515526 Unique identifier for this deployment.
from line 529
518529
519530 A resolved agent reference with a concrete version.
520531
521 - `id: string`
522
523532 - `type: "agent"`
524533
534 - `id: string`
535
525536 - `version: number`
526537
527538 format: int32
from line 565
554565
555566 A user message sent to the session.
556567
568 - `type: "user.message"`
569
557570 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
558571
559572 Array of content blocks for the user message.
from line 575
562575
563576 Regular text content.
564577
578 - `type: "text"`
579
565580 - `text: string`
566581
567582 The text content.
from line 583
568583
569584 minLength: 1
570585
571 - `type: "text"`
572
573586 - `BetaManagedAgentsImageBlock object`
574587
575588 Image content specified directly as base64 data or as a reference via a URL.
576589
590 - `type: "image"`
591
577592 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
578593
579594 Union type for image source variants.
from line 597
582597
583598 Base64-encoded image data.
584599
600 - `type: "base64"`
601
585602 - `data: string`
586603
587604 Base64-encoded image data.
from line 611
594611
595612 minLength: 1
596613
597 - `type: "base64"`
598
599614 - `BetaManagedAgentsURLImageSource object`
600615
601616 Image referenced by URL.
from line 627
612627
613628 Image referenced by file ID.
614629
630 - `type: "file"`
631
615632 - `file_id: string`
616633
617634 ID of a previously uploaded file.
from line 635
618635
619636 minLength: 1
620637
621 - `type: "file"`
622
623 - `type: "image"`
624
625638 - `BetaManagedAgentsDocumentBlock object`
626639
627640 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
628641
642 - `type: "document"`
643
629644 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
630645
631646 Union type for document source variants.
from line 649
634649
635650 Base64-encoded document data.
636651
652 - `type: "base64"`
653
637654 - `data: string`
638655
639656 Base64-encoded document data.
from line 663
646663
647664 minLength: 1
648665
649 - `type: "base64"`
650
651666 - `BetaManagedAgentsPlainTextDocumentSource object`
652667
653668 Plain text document content.
654669
670 - `type: "text"`
671
655672 - `data: string`
656673
657674 The plain text content.
from line 679
662679
663680 MIME type of the text content. Must be "text/plain".
664681
665 - `type: "text"`
666
667682 - `BetaManagedAgentsURLDocumentSource object`
668683
669684 Document referenced by URL.
from line 695
680695
681696 Document referenced by file ID.
682697
698 - `type: "file"`
699
683700 - `file_id: string`
684701
685702 ID of a previously uploaded file.
from line 703
686703
687704 minLength: 1
688705
689 - `type: "file"`
690
691 - `type: "document"`
692
693706 - `context: optional string or null`
694707
695708 Additional context about the document for the model.
from line 717
704717
705718 - `type: "redacted"`
706719
707 - `type: "user.message"`
708
709720 - `BetaManagedAgentsDeploymentUserDefineOutcomeEvent object`
710721
711722 An outcome the agent should work toward. The agent begins work on receipt.
712723
724 - `type: "user.define_outcome"`
725
713726 - `description: string`
714727
715728 What the agent should produce. This is the task specification.
from line 735
722735
723736 Rubric referenced by a file uploaded via the Files API.
724737
738 - `type: "file"`
739
725740 - `file_id: string`
726741
727742 ID of the rubric file.
728743
729 - `type: "file"`
730
731744 - `BetaManagedAgentsTextRubric object`
732745
733746 Rubric content provided inline as text.
734747
748 - `type: "text"`
749
735750 - `content: string`
736751
737752 Rubric content. Plain text or markdown — the grader treats it as freeform text.
738753
739 - `type: "text"`
740
741 - `type: "user.define_outcome"`
742
743754 - `max_iterations: optional number or null`
744755
745756 Eval→revision cycles before giving up. Default 3, max 20.
from line 761
750761
751762 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.
752763
764 - `type: "system.message"`
765
753766 - `content: array of BetaManagedAgentsSystemContentBlock`
754767
755768 System content blocks to append. Text-only.
756769
770 - `type: "text"`
771
757772 - `text: string`
758773
759774 The text content.
from line 775
760775
761776 minLength: 1
762777
763 - `type: "text"`
764
765 - `type: "system.message"`
766
767778 - `metadata: map[string]`
768779
769780 Arbitrary key-value metadata. Maximum 16 pairs.
from line 797
786797
787798 A scheduled fire recorded a failed run whose error auto-pauses the deployment.
788799
800 - `type: "error"`
801
789802 - `error: BetaManagedAgentsDeploymentPausedReasonError`
790803
791804 The error that triggered an auto-pause. Matches the failed run's `error.type`.
from line 887
874887
875888 - `type: "mcp_egress_blocked_error"`
876889
877 - `type: "error"`
878
879890 - `resources: array of BetaManagedAgentsSessionResourceConfig`
880891
881892 Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
from line 907
896907
897908 - `BetaManagedAgentsBranchCheckout object`
898909
910 - `type: "branch"`
911
899912 - `name: string`
900913
901914 Branch name to check out.
from line 915
902915
903916 minLength: 1, maxLength: 255
904917
905 - `type: "branch"`
906
907918 - `BetaManagedAgentsCommitCheckout object`
908919
920 - `type: "commit"`
921
909922 - `sha: string`
910923
911924 Full commit SHA to check out.
from line 925
912925
913926 minLength: 7, maxLength: 64
914927
915 - `type: "commit"`
916
917928 - `mount_path: optional string or null`
918929
919930 Mount path in the container. Defaults to `/workspace/<repo-name>`.
from line 933
922933
923934 A file mounted into each session's container.
924935
936 - `type: "file"`
937
925938 - `file_id: string`
926939
927940 ID of a previously uploaded file.
928941
929 - `type: "file"`
930
931942 - `mount_path: optional string or null`
932943
933944 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
from line 947
936947
937948 A memory store attached to each session created from this deployment.
938949
950 - `type: "memory_store"`
951
939952 - `memory_store_id: string`
940953
941954 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
942955
943 - `type: "memory_store"`
944
945956 - `access: optional "read_write" or "read_only" or null`
946957
947958 Access mode for an attached memory store.
from line 969
958969
959970 5-field POSIX cron schedule with computed runtime timestamps.
960971
972 - `type: "cron"`
973
961974 - `expression: string`
962975
963976 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).
from line 983
970983
971984 minLength: 1
972985
973 - `type: "cron"`
974
975986 - `last_run_at: optional string or null`
976987
977988 A timestamp in RFC 3339 format
from line 1001
9901001
9911002 - `"paused"`
9921003
993 - `type: "deployment"`
994
9951004 - `updated_at: string`
9961005
9971006 A timestamp in RFC 3339 format
from line 1015
10061015
10071016 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
10081017
1018 - `type: "limit"`
1019
10091020 - `max_list_cost: BetaMonetaryAmount`
10101021
10111022 A monetary amount in a specific currency.
from line 1028
10171028 - `currency: BetaCurrency`
10181029
10191030 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.
1020
1021 - `type: "limit"`
10221031
10231032## Example
10241033