Update Deployment

post/v1/deployments/{deployment_id}?beta=true

Path parameters

deployment_idstring required

Path parameter deployment_id

Headers

anthropic-versionstring

anthropic-betastring

Request body

namestring

Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.

descriptionstring nullable

Description. Omit to preserve; send empty string or null to clear.

environment_idstring

ID of the environment where sessions run. Omit to preserve. Cannot be cleared.

vault_idsstring[] nullable

Vault IDs. Full replacement. Omit to preserve; send empty array or null to clear. Maximum 50.

metadataobject 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.

Example request

{
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Where is my order #1234?"
        }
      ]
    }
  ],
  "resources": [
    {
      "type": "github_repository",
      "url": "https://github.com/example-org/example-repo",
      "authorization_token": "ghp_exampletoken"
    }
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "America/Los_Angeles"
  },
  "budget": {
    "max_list_cost": {
      "currency": "USD",
      "amount": "2500"
    }
  }
}

Response

Successful response (OK)

type'deployment' required

idstring required

Unique identifier for this deployment.

namestring required

Human-readable name.

descriptionstring nullable required

Description of what the deployment does.

environment_idstring required

ID of the environment where sessions run.

vault_idsstring[] required

Vault IDs supplying stored credentials for sessions created from this deployment.

metadataobject required

Arbitrary key-value metadata. Maximum 16 pairs.

status'active' | 'paused' required

Lifecycle status of a deployment.

created_atstring date-time required

A timestamp in RFC 3339 format

updated_atstring date-time required

A timestamp in RFC 3339 format

archived_atstring date-time required

A timestamp in RFC 3339 format

Example response

{
  "type": "deployment",
  "id": "depl_011CZkZcDH3vPqd7xnEfwTai",
  "name": "Daily order report",
  "description": "Compiles yesterday's orders into a report every weekday morning.",
  "agent": {
    "type": "agent",
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "version": 1
  },
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "initial_events": [
    {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Compile yesterday's orders into report.md."
        }
      ]
    }
  ],
  "resources": [],
  "metadata": {},
  "schedule": {
    "type": "cron",
    "expression": "0 9 * * 1-5",
    "timezone": "America/Los_Angeles",
    "last_run_at": "2026-03-16T16:00:09Z",
    "upcoming_runs_at": [
      "2026-03-17T16:00:00Z",
      "2026-03-18T16:00:00Z"
    ]
  },
  "status": "active",
  "paused_reason": null,
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": null
}

Changes

Changed in 3 of the 68 revisions of this API.17227

Aug 17, 2026d2b230555b7f16221See the full diff
- ▲
  the request property budget became not nullable
  request-property-became-not-nullable
- ▲
  the request property description became not nullable
  request-property-became-not-nullable
- ▲
  the request property initial_events/items/oneOf[BetaManagedAgentsUserDefineOutcomeEventParams]/max_iterations became not nullable
  request-property-became-not-nullable
- ▲
  the request property initial_events/items/oneOf[BetaManagedAgentsUserMessageEventParams]/content/items/oneOf[BetaManagedAgentsDocumentBlock]/context became not nullable
  request-property-became-not-nullable
- ▲
  the request property initial_events/items/oneOf[BetaManagedAgentsUserMessageEventParams]/content/items/oneOf[BetaManagedAgentsDocumentBlock]/title became not nullable
  request-property-became-not-nullable
- ▲
  the request property metadata became not nullable
  request-property-became-not-nullable
- ▲
  the request property resources became not nullable
  request-property-became-not-nullable
- ▲
  the request property schedule became not nullable
  request-property-became-not-nullable
- ▲
  the request property vault_ids became not nullable
  request-property-became-not-nullable
- ▲
  response property description list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property initial_events/items/oneOf[BetaManagedAgentsDeploymentUserDefineOutcomeEvent]/max_iterations list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property initial_events/items/oneOf[BetaManagedAgentsDeploymentUserMessageEvent]/content/items/oneOf[BetaManagedAgentsDocumentBlock]/context list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property initial_events/items/oneOf[BetaManagedAgentsDeploymentUserMessageEvent]/content/items/oneOf[BetaManagedAgentsDocumentBlock]/title list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property resources/items/oneOf[BetaManagedAgentsFileResourceConfig]/mount_path list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property resources/items/oneOf[BetaManagedAgentsGitHubRepositoryResourceConfig]/mount_path list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property resources/items/oneOf[BetaManagedAgentsMemoryStoreResourceConfig]/instructions list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ●
  removed BetaManagedAgentsBudget from the budget request property allOf list
  request-property-all-of-removed
- ●
  removed BetaManagedAgentsScheduleParams from the schedule request property allOf list
  request-property-all-of-removed
- ○
  added BetaManagedAgentsBudget subschema #2 to the budget request property anyOf list
  request-property-any-of-added
- ○
  added BetaManagedAgentsScheduleParams subschema #2 to the schedule request property anyOf list
  request-property-any-of-added
- ○
  request property description list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property initial_events/items/oneOf[BetaManagedAgentsUserDefineOutcomeEventParams]/max_iterations list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property initial_events/items/oneOf[BetaManagedAgentsUserMessageEventParams]/content/items/oneOf[BetaManagedAgentsDocumentBlock]/context list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property initial_events/items/oneOf[BetaManagedAgentsUserMessageEventParams]/content/items/oneOf[BetaManagedAgentsDocumentBlock]/title list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property metadata list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property resources list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property vault_ids list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  removed BetaManagedAgentsBudget from the budget response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  removed BetaManagedAgentsDeploymentPausedReason from the paused_reason response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  removed BetaManagedAgentsMountMode from the resources/items/oneOf[BetaManagedAgentsMemoryStoreResourceConfig]/access response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  removed BetaManagedAgentsRepositoryCheckout from the resources/items/oneOf[BetaManagedAgentsGitHubRepositoryResourceConfig]/checkout response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  removed BetaManagedAgentsSchedule from the schedule response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  removed BetaTimestamp from the archived_at response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  added BetaManagedAgentsBudget subschema #2 to the budget response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added BetaManagedAgentsDeploymentPausedReason subschema #2 to the paused_reason response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added BetaManagedAgentsMountMode subschema #2 to the resources/items/oneOf[BetaManagedAgentsMemoryStoreResourceConfig]/access response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added BetaManagedAgentsRepositoryCheckout subschema #2 to the resources/items/oneOf[BetaManagedAgentsGitHubRepositoryResourceConfig]/checkout response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added BetaManagedAgentsSchedule subschema #2 to the schedule response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added BetaTimestamp subschema #2 to the archived_at response property anyOf list for the response status 200
  response-property-any-of-added
Aug 6, 202693d8fd7d649315See the full diff
- ▲
  added BetaManagedAgentsRedactedBlock to the initial_events/items/oneOf[BetaManagedAgentsDeploymentUserMessageEvent]/content/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ○
  added the new optional request property budget
  new-optional-request-property
- ○
  added redacted discriminator mapping keys to the initial_events/items/oneOf[BetaManagedAgentsUserMessageEventParams]/content/items/ request property
  request-property-discriminator-mapping-added
- ○
  added BetaManagedAgentsRedactedBlock to the initial_events/items/oneOf[BetaManagedAgentsUserMessageEventParams]/content/items/ request property oneOf list
  request-property-one-of-added
- ○
  added the optional property budget to the response with the 200 status
  response-optional-property-added
- ○
  added redacted discriminator mapping keys to the initial_events/items/oneOf[BetaManagedAgentsDeploymentUserMessageEvent]/content/items/ response property for the response status 200
  response-property-discriminator-mapping-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jun 9, 20262336fecb081b1See the full diff
- ○
  endpoint added
  endpoint-added

Full history