Update Session

post/v1/sessions/{session_id}?beta=true

Path parameters

session_idstring required

Path parameter session_id

Headers

anthropic-versionstring

anthropic-betastring

Request body

titlestring nullable

Human-readable session title.

metadataobject nullable

Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.

vault_idsstring[]

Vault IDs (vlt_*) to attach to the session. Not yet supported; requests setting this field are rejected. Reserved for future use.

Example request

{
  "title": "Order #1234 inquiry"
}

Response

Successful response (OK)

type'session' required

idstring required

status'rescheduling' | 'running' | 'idle' | 'terminated' required

SessionStatus enum

created_atstring date-time required

A timestamp in RFC 3339 format

updated_atstring date-time required

A timestamp in RFC 3339 format

environment_idstring required

titlestring nullable required

metadataobject required

vault_idsstring[] required

Vault IDs attached to the session at creation. Empty when no vaults were supplied.

archived_atstring date-time required

A timestamp in RFC 3339 format

deployment_idstring nullable

Deployment ID when the session was created from a deployment reference. Null otherwise.

Example response

{
  "type": "session",
  "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
  "status": "idle",
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": null,
  "budget": null,
  "environment_id": "env_011CZkZ9X2dpNyB7HsEFoRfW",
  "title": "Order #1234 inquiry",
  "metadata": {},
  "agent": {
    "type": "agent",
    "id": "agent_011CZkYpogX7uDKUyvBTophP",
    "version": 1,
    "name": "My First Agent",
    "description": "A general-purpose starter agent.",
    "model": {
      "id": "claude-opus-5",
      "speed": "standard"
    },
    "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "default_config": {
          "enabled": true,
          "permission_policy": {
            "type": "always_ask"
          }
        },
        "configs": []
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "example-mcp",
        "url": "https://example-server.modelcontextprotocol.io/sse"
      }
    ],
    "skills": [
      {
        "type": "anthropic",
        "skill_id": "xlsx",
        "version": "1"
      },
      {
        "type": "custom",
        "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
        "version": "2"
      }
    ],
    "multiagent": null
  },
  "resources": [
    {
      "type": "file",
      "id": "sesrsc_011CZkZBJq5dWxk9fVLNcPht",
      "file_id": "file_011CNha8iCJcU1wXNR6q4V8w",
      "mount_path": "/uploads/receipt.pdf",
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z"
    },
    {
      "type": "github_repository",
      "id": "sesrsc_011CZkZCKr6eXyl0gWMOdQiu",
      "url": "https://github.com/example-org/example-repo",
      "mount_path": "/workspace/example-repo",
      "checkout": {
        "type": "branch",
        "name": "main"
      },
      "created_at": "2026-03-15T10:00:00Z",
      "updated_at": "2026-03-15T10:00:00Z"
    }
  ],
  "vault_ids": [
    "vlt_011CZkZDLs7fYzm1hXNPeRjv"
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "cache_read_input_tokens": 0
  },
  "stats": {
    "duration_seconds": 0,
    "active_seconds": 0
  },
  "outcome_evaluations": [
    {
      "type": "outcome_evaluation",
      "outcome_id": "outc_011CZkZRSw2kEfs6ncTVljxP",
      "description": "Produce a 2-page summary as summary.md",
      "result": "satisfied",
      "iteration": 0,
      "completed_at": "2026-03-15T10:02:31Z",
      "explanation": "All five sections present with inline citations."
    }
  ]
}

Changes

Changed in 17 of the 68 revisions of this API.46972

Sep 1, 2026d1d189d791d12See the full diff
- ○
  added subschema #2 to the // response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the ///////////////// response property anyOf list for the response status
  response-property-any-of-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 19, 20260042750ea1ee834See the full diff
- ▲
  added to the /////////////////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  added to the //////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  removed the required property //////////////////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////////////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////////////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ///////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ///////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property ///////// from the response with the status
  response-required-property-removed
- ●
  removed the request property /////////////
  request-property-removed
- ●
  removed the request property /////////////
  request-property-removed
- ●
  removed the request property /////////////
  request-property-removed
- ○
  added discriminator to //////////// request property
  request-property-discriminator-added
- ○
  added to the //////////// request property oneOf list
  request-property-one-of-added
- ○
  added discriminator to /////////////////////// response property for the response status
  response-property-discriminator-added
- ○
  added discriminator to //////// response property for the response status
  response-property-discriminator-added
Aug 17, 2026d2b230555b7f19527See the full diff
- ▲
  the request property ///////////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property ///////////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property /////////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property ///////////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property ///////////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property /////////// became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  the request property became not nullable
  request-property-became-not-nullable
- ▲
  response property agent/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 agent/system 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 deployment_id 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 outcome_evaluations/items/explanation 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[BetaManagedAgentsMemoryStoreResource]/instructions 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[BetaManagedAgentsMemoryStoreResource]/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[BetaManagedAgentsMemoryStoreResource]/name 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 title list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  the ////// response property's maxLength was unset from 4096 for the response status
  response-property-max-length-unset
- ▲
  the ////// response's property type changed from object to no type for status
  response-property-type-changed
- ●
  removed from the /////////// request property allOf list
  request-property-all-of-removed
- ●
  removed from the request property allOf list
  request-property-all-of-removed
- ●
  removed from the /////////// request property allOf list
  request-property-all-of-removed
- ●
  removed from the ///////////// request property allOf list
  request-property-all-of-removed
- ●
  removed from the ///////////// request property allOf list
  request-property-all-of-removed
- ○
  added subschema #2 to the /////////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the /////////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the ///////////// request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the ///////////// request property anyOf list
  request-property-any-of-added
- ○
  request property ///////////// list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property ///////////// list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  the request property's minLength was decreased from 1 to 0
  request-property-min-length-decreased
- ○
  removed from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the ////// response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the ///// response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the / response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the ///// response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the response property allOf list for the response status
  response-property-all-of-removed
- ○
  removed from the // response property allOf list for the response status
  response-property-all-of-removed
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the ////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the ////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the ///// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the / response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the ///// response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the // response property anyOf list for the response status
  response-property-any-of-added
- ○
  removed discriminator from ////// response property for the response status
  response-property-discriminator-removed
- ○
  removed from the ////// response property oneOf list for the response status
  response-property-one-of-removed
Aug 6, 202693d8fd7d6493127See the full diff
- ▲
  added to the /////////// response property oneOf list for the response status
  response-property-one-of-added
- ▲
  the /////////// response's property type changed from object to no type for status
  response-property-type-changed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ▲
  removed the required property //////////// from the response with the status
  response-required-property-removed
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added the optional property ///// to the response with the status
  response-optional-property-added
- ○
  added discriminator to /////////// response property for the response status
  response-property-discriminator-added
- ○
  added the required property to the response with the status
  response-required-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 24, 2026a97790bd7f184See the full diff
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the // response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the ///////////// response property anyOf list for the response status
  response-property-any-of-added
- ○
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the // response property anyOf list for the response status
  response-property-any-of-removed
- ○
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the ///////////// response property anyOf list for the response status
  response-property-any-of-removed
Jul 22, 20265e4a8830793b2See the full diff
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property ///////////// to the response with the status
  response-optional-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 2, 2026ec00b28b50c21See the full diff
- ○
  the /////////// request property's maxLength was increased from 1024 to 4096
  request-property-max-length-increased
Jun 30, 20267caa9a75ddbc2See the full diff
- ○
  added subschema #2 to the // response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the ///////////// response property anyOf list for the response status
  response-property-any-of-added
Jun 9, 20262336fecb081b1See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Jun 9, 202600259327305f2See the full diff
- ○
  added subschema #2 to the // response property anyOf list for the response status
  response-property-any-of-added
- ○
  added subschema #2 to the ///////////// response property anyOf list for the response status
  response-property-any-of-added

Full history (17 revisions)