---
title: "Update Deployment"
method: POST
path: "/v1/deployments/{deployment_id}?beta=true"
---

# Update Deployment

`POST /v1/deployments/{deployment_id}?beta=true`

## Path parameters

- `deployment_id` string, required

## Headers

- `anthropic-version` string
- `anthropic-beta` string

## Request body

- BetaManagedAgentsUpdateDeploymentParams — Request parameters for updating a `deployment`. Omit a field to preserve its current value.
  - `name` string — Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.
  - `description` string, nullable — Description. Omit to preserve; send empty string or null to clear.
  - `agent` union
    - string
    - BetaManagedAgentsAgentParams — Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
      - `type` 'agent', required
      - `id` string, required — The `agent` ID.
      - `version` integer — The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
  - `environment_id` string — ID of the `environment` where sessions run. Omit to preserve. Cannot be cleared.
  - `vault_ids` string[], nullable — Vault IDs. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 50.
  - `initial_events` BetaManagedAgentsDeploymentInitialEventParams[] — Initial events. Full replacement. Omit to preserve. Cannot be cleared. At least 1, maximum 50.
    - union — An event sent to a session immediately after it is created. Supports `user.message`, `user.define_outcome`, and `system.message`.
      - object — Parameters for sending a user message to the session.
        - `type` 'user.message', required
        - `content` BetaManagedAgentsUserContentBlock[], required — Array of content blocks for the user message.
          - union — Content block in a user message. Can be `text`, `image`, or `document`.
            - object — Regular text content.
              - …
            - object — Image content specified directly as base64 data or as a reference via a URL.
              - …
            - object — Document content, either specified directly as base64 data, as text, or as a reference via a URL.
              - …
            - object — Placeholder for content withheld by Anthropic model policy.
              - …
      - object — Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
        - `type` 'user.define_outcome', required
        - `description` string, required — What the agent should produce. This is the task specification.
        - `rubric` union, required — Rubric for grading the quality of an outcome.
          - BetaManagedAgentsFileRubricParams — Rubric referenced by a file uploaded via the Files API.
            - `type` 'file', required
            - `file_id` string, required — ID of the rubric file.
          - BetaManagedAgentsTextRubricParams — Rubric content provided inline as text.
            - `type` 'text', required
            - `content` string, required — Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
        - `max_iterations` integer, nullable — Eval→revision cycles before giving up. Default 3, max 20.
      - object — 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.
        - `type` 'system.message', required
        - `content` BetaManagedAgentsSystemContentBlock[], required — System content blocks to append. Text-only.
          - `type` 'text', required
          - `text` string, required — The text content.
  - `resources` BetaManagedAgentsSessionResourceParams[], nullable — Session resources. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 500.
    - union — Union of resources that can be mounted into a session.
      - object — Mount a GitHub repository into the session's container.
        - `type` 'github_repository', required
        - `url` string, required — Github URL of the repository
        - `authorization_token` string, required — GitHub authorization token used to clone the repository.
        - `mount_path` string, nullable — Mount path in the container. Defaults to `/workspace/<repo-name>`.
        - `checkout` union
          - object
            - `type` 'branch', required
            - `name` string, required — Branch name to check out.
          - object
            - `type` 'commit', required
            - `sha` string, required — Full commit SHA to check out.
      - object — Mount a file uploaded via the Files API into the session.
        - `type` 'file', required
        - `file_id` string, required — ID of a previously uploaded file.
        - `mount_path` string, nullable — Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
      - object — Parameters for attaching a memory store to an agent session.
        - `type` 'memory_store', required
        - `memory_store_id` string, required — The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
        - `access` 'read_write' | 'read_only' — Access mode for an attached memory store.
        - `instructions` string, nullable — Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
  - `metadata` object, nullable — 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.
  - `schedule` BetaManagedAgentsScheduleParams — 5-field POSIX cron schedule. Literal wall-clock matching in the configured timezone.
    - `type` 'cron', required
    - `expression` string, required — 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).
    - `timezone` string, required — Required. IANA timezone identifier (e.g., "America/Los_Angeles", "UTC"). Validated against the IANA timezone database.
  - `budget` BetaManagedAgentsBudget — A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
    - `type` 'limit', required
    - `max_list_cost` BetaMonetaryAmount, required — A monetary amount in a specific currency.
      - `currency` 'USD', required
      - `amount` string, required — Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.

## Response `200`

Successful response (OK)

- BetaManagedAgentsDeployment — 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.
  - `type` 'deployment', required
  - `id` string, required — Unique identifier for this deployment.
  - `name` string, required — Human-readable name.
  - `description` string, nullable, required — Description of what the deployment does.
  - `agent` BetaManagedAgentsAgentReference, required — A resolved agent reference with a concrete version.
    - `type` 'agent', required
    - `id` string, required
    - `version` integer, required
  - `environment_id` string, required — ID of the `environment` where sessions run.
  - `vault_ids` string[], required — Vault IDs supplying stored credentials for sessions created from this deployment.
  - `initial_events` BetaManagedAgentsDeploymentInitialEvent[], required — Events sent to each session immediately after creation.
    - union — An event sent to a session immediately after it is created. Supports `user.message`, `user.define_outcome`, and `system.message`.
      - object — A user message sent to the session.
        - `type` 'user.message', required
        - `content` BetaManagedAgentsUserContentBlock[], required — Array of content blocks for the user message.
          - union — Content block in a user message. Can be `text`, `image`, or `document`.
            - object — Regular text content.
              - …
            - object — Image content specified directly as base64 data or as a reference via a URL.
              - …
            - object — Document content, either specified directly as base64 data, as text, or as a reference via a URL.
              - …
            - object — Placeholder for content withheld by Anthropic model policy.
              - …
      - object — An outcome the agent should work toward. The agent begins work on receipt.
        - `type` 'user.define_outcome', required
        - `description` string, required — What the agent should produce. This is the task specification.
        - `rubric` union, required — Rubric for grading the quality of an outcome.
          - BetaManagedAgentsFileRubric — Rubric referenced by a file uploaded via the Files API.
            - `type` 'file', required
            - `file_id` string, required — ID of the rubric file.
          - BetaManagedAgentsTextRubric — Rubric content provided inline as text.
            - `type` 'text', required
            - `content` string, required — Rubric content. Plain text or markdown — the grader treats it as freeform text.
        - `max_iterations` integer, nullable — Eval→revision cycles before giving up. Default 3, max 20.
      - object — 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.
        - `type` 'system.message', required
        - `content` BetaManagedAgentsSystemContentBlock[], required — System content blocks to append. Text-only.
          - `type` 'text', required
          - `text` string, required — The text content.
  - `resources` BetaManagedAgentsSessionResourceConfig[], required — Resources attached to sessions created from this deployment. Echoes the input minus write-only credentials.
    - union — A configured session resource. Echoes the input minus write-only credentials.
      - object — A GitHub repository mounted into each session's container. The authorization token is write-only and never returned.
        - `type` 'github_repository', required
        - `url` string, required — Github URL of the repository
        - `mount_path` string, nullable — Mount path in the container. Defaults to `/workspace/<repo-name>`.
        - `checkout` union
          - object
            - `type` 'branch', required
            - `name` string, required — Branch name to check out.
          - object
            - `type` 'commit', required
            - `sha` string, required — Full commit SHA to check out.
      - object — A file mounted into each session's container.
        - `type` 'file', required
        - `file_id` string, required — ID of a previously uploaded file.
        - `mount_path` string, nullable — Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
      - object — A memory store attached to each session created from this deployment.
        - `type` 'memory_store', required
        - `memory_store_id` string, required — The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
        - `access` 'read_write' | 'read_only' — Access mode for an attached memory store.
        - `instructions` string, nullable — Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars.
  - `metadata` object, required — Arbitrary key-value metadata. Maximum 16 pairs.
  - `schedule` BetaManagedAgentsSchedule, required — 5-field POSIX cron schedule with computed runtime timestamps.
    - `type` 'cron', required
    - `expression` string, required — 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).
    - `timezone` string, required — IANA timezone identifier (e.g., "America/Los_Angeles", "UTC").
    - `last_run_at` string, date-time — A timestamp in RFC 3339 format
    - `upcoming_runs_at` BetaTimestamp[] — 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.
  - `status` 'active' | 'paused', required — Lifecycle status of a deployment.
  - `paused_reason` union, required — Why a deployment is paused. Non-null exactly when `status` is `paused`.
    - object — The caller invoked the pause endpoint on the deployment.
      - `type` 'manual', required
    - object — A scheduled fire recorded a failed run whose error auto-pauses the deployment.
      - `type` 'error', required
      - `error` union, required — The error that triggered an auto-pause. Matches the failed run's `error.type`.
        - object — The deployment's environment was archived.
          - `type` 'environment_archived_error', required
        - object — The deployment's agent was archived.
          - `type` 'agent_archived_error', required
        - object — The deployment's environment no longer exists.
          - `type` 'environment_not_found_error', required
        - object — A vault referenced by the deployment no longer exists.
          - `type` 'vault_not_found_error', required
        - object — A file resource referenced by the deployment no longer exists.
          - `type` 'file_not_found_error', required
        - object — A referenced resource no longer exists and its kind was not reported.
          - `type` 'session_resource_not_found_error', required
        - object — The deployment's workspace was archived.
          - `type` 'workspace_archived_error', required
        - object — The deployment's organization is disabled.
          - `type` 'organization_disabled_error', required
        - object — A memory store referenced by the deployment is archived.
          - `type` 'memory_store_archived_error', required
        - object — A skill referenced by the deployment's agent no longer exists.
          - `type` 'skill_not_found_error', required
        - object — A vault referenced by the deployment is archived.
          - `type` 'vault_archived_error', required
        - object — An unrecognized error auto-paused the deployment. A fallback variant; matches a run whose `error.type` is `unknown_error`.
          - `type` 'unknown_error', required
        - object — The deployment configures resources, but its environment is self-hosted and cannot mount them.
          - `type` 'self_hosted_resources_unsupported_error', required
        - object — An MCP server host used by the deployment's agent is blocked by the environment's network policy.
          - `type` 'mcp_egress_blocked_error', required
  - `budget` BetaManagedAgentsBudget — A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
    - `type` 'limit', required
    - `max_list_cost` BetaMonetaryAmount, required — A monetary amount in a specific currency.
      - `currency` 'USD', required
      - `amount` string, required — Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
  - `created_at` string, date-time, required — A timestamp in RFC 3339 format
  - `updated_at` string, date-time, required — A timestamp in RFC 3339 format
  - `archived_at` string, date-time, required — A timestamp in RFC 3339 format

## Other responses

- `400` — Invalid argument - The client specified an invalid argument
- `401` — Unauthenticated - The request does not have valid authentication credentials
- `403` — Permission denied - The caller does not have permission to execute the specified operation
- `404` — Not found - Some requested entity was not found
- `408` — Deadline exceeded - The deadline expired before the operation could complete
- `409` — Aborted - The operation was aborted due to concurrency issue
- `412` — Failed precondition - Operation was rejected because the system is not in required state
- `413` — Out of range - Operation was attempted past the valid range
- `429` — Resource exhausted - Some resource has been exhausted (rate limiting)
- `431` — Request header fields too large - Request metadata was too large
- `499` — Cancelled - The operation was cancelled by the client
- `500` — Internal - Internal server error
- `501` — Unimplemented - The operation is not implemented or supported
- `503` — Unavailable - The service is currently unavailable
- `504` — Deadline exceeded - Upstream service did not respond in time

---

[API](https://skmtc.net/anthropics/apis/anthropic-api.md) · [All operations](https://skmtc.net/anthropics/apis/anthropic-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/anthropics/anthropic-api/versions/93d8fd7d6493/schema)