---
title: "Checkpoint workspace"
method: POST
path: "/api/v1/agent/persistent/scheduler/checkpoint_workspace"
tags: ["agent"]
---

# Checkpoint workspace

`POST /api/v1/agent/persistent/scheduler/checkpoint_workspace`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/agent/persistent/scheduler/checkpoint_workspace`
- Auth: HTTP bearer

Publish capsule and canonical continuation pointer in one fenced Git transaction. Preserve existing model decisions, action receipts, task limits and generation. Retry an uncertain publication using the identical original head, operation and snapshot; never substitute private payloads.

## Request body

- object
  - `organization_id` string, required
  - `agent_id` string, required
  - `task_id` string, required
  - `first_execution_run_id` string, required
  - `scope` PersistentAgentWorkerScope, required
    - `task_id` string, required
    - `segment_id` string, required
    - `generation` integer, required
    - `claim_id` string, required
  - `expected_head` string, required
  - `operation_key` string, required
  - `snapshot` PersistentAgentWorkspaceSnapshot, required: Bounded portable snapshot: exact declared file order, at most 512 KiB decoded total and 1 MiB canonical JSON. No image/runtime authority or provider allocation is stored.
    - `schema` 1, required
    - `spec` PersistentAgentWorkspaceSpec, required
      - `task_id` string, required
      - `configuration_commit` string, required
      - `image` string, required: Explicit nonmoving provider image version; the trusted runtime independently verifies the applied image.
      - `setup_digest` string, required
      - `durable_paths` string[], required: Sorted relative regular-file paths; no overlaps, credentials or reserved paths.
    - `files` PersistentAgentWorkspaceFile[], required
      - `path` string, required
      - `mode` 384 | 448, required
      - `size` integer, required
      - `sha256` string, required
      - `content` string, required: Canonical strict base64; decoded bytes must match size and sha256.

## Response `200`

No-store trusted Activity response

- PersistentAgentWorkspaceCheckpointReceipt
  - `scope` PersistentAgentWorkerScope, required
    - `task_id` string, required
    - `segment_id` string, required
    - `generation` integer, required
    - `claim_id` string, required
  - `workspace` PersistentAgentWorkspacePointer, required
    - `sequence` integer, required
    - `sha256` string, required
  - `version` string, required

## Other responses

- `401`: Invalid platform scheduler credential
- `403`: Current task authority unavailable
- `404`: Task or organization unavailable
- `409`: Canonical state or generation requires reconciliation
- `422`: Invalid or oversized request
- `502`: Bad gateway
- `503`: Canonical state or scheduler unavailable

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/74298a24e040?raw)