Update a Session's title or metadata

Sets or clears a Session’s display title and correlation metadata; title is required and null clears it, while metadata is optional — omitting it leaves the bag untouched and sending {} clears it. Metadata is replaced whole rather than merged per key, because the platform never reads the keys it stores. Both are display and correlation data only, with no admission, authorization, or routing meaning, and updating is last-write-wins and allowed while a turn is active or after the Session is terminal. A material change appends a content-free session.title_updated or session.metadata_updated marker — neither title text nor metadata keys and values enter the event ledger — while a non-null title or a non-empty bag is denied for zero-data-retention Sessions. Returns the updated Session.

Checkfu support posture: alpha; hosted. Required evidence journey: session-turn. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

PATCH /v1/sessions/{id}

Update a Session's title or metadata

cURL

curl --request PATCH \
  --url https://api.checkfu.com/v1/sessions/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --data '
{
  "title": "<string>",
  "metadata": {}
}
'

200

{
  "id": "<string>",
  "workspace_id": "<string>",
  "agent_id": "<string>",
  "agent_deployment_id": "<string>",
  "agent_deployment_revision_number": 1,
  "execution_target_type": "managed",
  "principal": "<string>",
  "status": "pending",
  "agent_release_number": 1,
  "release_hash": "<string>",
  "acted_as": "<string>",
  "agent_installation_id": "<string>",
  "surface_scope_id": "<string>",
  "admitted_at": "<string>",
  "vault_ids": [
    "<string>"
  ],
  "resources": [
    {
      "id": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "mount_path": "<string>",
      "type": "github_repository",
      "url": "<string>",
      "checkout": {
        "type": "branch",
        "name": "<string>"
      }
    }
  ],
  "mounts": [
    {
      "id": "<string>",
      "kind": "project",
      "project_id": "<string>",
      "mount_path": "<string>",
      "revision_policy": {
        "kind": "latest"
      },
      "access": "read_only",
      "writeback": null
    }
  ],
  "wire_version": "<string>",
  "created_at": "<string>",
  "archived_at": "<string>",
  "title": "<string>",
  "client_reference": "<string>",
  "metadata": {},
  "automation": "<string>",
  "session_template_id": "<string>",
  "session_template_version": 1,
  "work_environment": {
    "disposition": "resolved",
    "resolver_version": "work-environment-resolver/v1",
    "preset_catalog_version": 1,
    "normalized_requirements": {
      "schema_version": 1,
      "execution": [
        "shell"
      ],
      "lifetime": "run",
      "presentation": "none",
      "human_access": "none",
      "placement": [
        "managed"
      ],
      "isolation": {
        "filesystem": "attachment",
        "browser_profile": "attachment",
        "process_namespace": "attachment",
        "credentials": "grant_bound",
        "clipboard": "disabled",
        "downloads": "attachment"
      },
      "recovery": "none",
      "retention": {
        "mode": "ephemeral_zdr",
        "maximum_seconds": 157680000,
        "export": "forbidden"
      },
      "network": {
        "mode": "none",
        "policy": {
          "action_policy_id": "<string>",
          "action_policy_version": 1
        }
      },
      "locality": {
        "regions": [
          "<string>"
        ],
        "residency_required": true
      },
      "resources": {
        "minimum_vcpu": 512,
        "minimum_memory_mib": 2097152,
        "minimum_disk_mib": 536870912,
        "gpu": "forbidden"
      }
    },
    "resolved_kind": "none",
    "requires_screen": true,
    "forced_by": [
      "<string>"
    ],
    "selected_provider": {
      "provider": "<string>",
      "tuple_digest": "<string>",
      "evidence_grade": "double"
    },
    "considered": [
      {
        "provider": "<string>",
        "tuple_digest": "<string>",
        "qualified": true,
        "reasons": [
          {
            "code": "live_qualification_missing",
            "requirement_path": "<string>",
            "expected": "<string>",
            "observed": "<string>",
            "evidence_reference": "<string>"
          }
        ]
      }
    ],
    "warnings": [
      {
        "code": "shared_profile_credentials",
        "message": "<string>",
        "acknowledgement_required": true
      }
    ],
    "estimated_usage_dimensions": [
      "compute_seconds"
    ],
    "refusal": {
      "code": "human_access_requires_presentation",
      "requirement_path": "<string>",
      "message": "<string>"
    },
    "portability": "not_applicable",
    "candidate_set_digest": "<string>",
    "resolution_digest": "<string>"
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version · enum<string> · required

Available options: 2026-08-24

Path Parameters

id · string · required

Pattern: ^sess_[0-9a-f]{32}$

Body

application/json

title · string | null · required

Required string length: 1 - 255

metadata · object

at most 16 correlation pairs with keys of 1 to 64 characters

Show child attributes

Response

200

application/json

Success

id · string · required

Pattern: ^sess_[0-9a-f]{32}$

workspace_id · string · required

Pattern: ^wrkspc_[0-9a-f]{32}$

agent_id · string · required

Pattern: ^agent_[0-9a-f]{32}$

agent_deployment_id · string | null · required

Pattern: ^adep_[0-9a-f]{32}$

agent_deployment_revision_number · integer | null · required

Required range: x > 0

execution_target_type · enum<string> | null · required

Available options: managed, connected

principal · string · required

Pattern: ^prin_[0-9a-f]{32}$

status · enum<string> · required

Available options: pending, provisioning, running, reconciling, waiting, idle, paused, completed, failed, canceled

agent_release_number · integer | null · required

Required range: x > 0

release_hash · string | null · required

Pattern: ^sha256:[0-9a-f]{64}$

acted_as · string | null · required

Pattern: ^prin_[0-9a-f]{32}$

agent_installation_id · string | null · required

Pattern: ^aini_[0-9a-f]{32}$

surface_scope_id · string | null · required

Pattern: ^surf_[0-9a-f]{32}$

admitted_at · string | null · required

vault_ids · string[] · required

Pattern: ^vlt_[0-9a-f]{32}$

resources · object[] · required

Option 1

Option 2

Option 3

Show child attributes

mounts · object[] · required

Option 1

Option 2

Option 3

Option 4

Show child attributes

wire_version · string · required

created_at · string · required

archived_at · string | null · required

title · string

Required string length: 1 - 255

client_reference · string

Required string length: 1 - 255

metadata · object

at most 16 correlation pairs with keys of 1 to 64 characters

Show child attributes

automation · string

Pattern: ^auto_[0-9a-f]{32}$

session_template_id · string

Pattern: ^stpl_[0-9a-f]{32}$

session_template_version · integer

Required range: x > 0

work_environment · object

A deterministic allocation-free explanation of work-environment admission.

Show child attributes