Restore from the last committed checkpoint or cancel a pause
Brings a stopped or paused session back to active, or cancels a pause that is still draining. The receipt result is {resulting_admission_state, checkpoint_revision, queued_turn_count}.
- From
stopped: the session isactiveat once, the next worker restores the last committed checkpoint, queued input is dispatched, and the receipt issucceededin the response. - From
paused: the session goesresumingand a new worker restores the pause's checkpoint. The receipt staysaccepteduntil that worker reports ready; then the session isactiveand the receiptsucceeded. If the restore keeps failing, the receipt fails and the session goesrecovery_required. - From
pausing, before the stop is committed: the pause is cancelled (its receipt fails), the session isactiveagain, and this receipt issucceeded. Once the stop is committed the answer is409 PAUSE_COMMITTING.
Each change is a status event with admission_state on the stream.
Scope: sessions:control (API key or cookie session). Idempotency-Key: required.
AuthorizationBearer <token>For servers and scripts: an API key sent as an HTTP bearer token, Bearer <key>. It holds exactly the scopes it was issued with; a key issued before scopes existed holds none. It never needs the CSRF header, and it cannot manage agents, members, teams or API keys. Issue one in the web console under Settings → API keys; each operation names the scope it needs.
Scope: sessions:control
id*stringThe session's id.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidIdempotency-Key*stringRequired, 1–255 characters; a UUID per user intent works. A retry with the same key and the same body returns the original response and runs the command once; the same key with a different body answers 409 IDEMPOTENCY_CONFLICT. A missing or invalid key answers 400 BAD_REQUEST, after the body is read.
1 <= length <= 255X-Requested-With?"werft-web"Required with a cookie session: the literal werft-web.
"werft-web"application/json- body
expected_revision*integer0 <= value <= 2147483647The resume is stored: accepted while a worker restores a paused session, succeeded when it took effect in the request.
application/json- response
receipt_id*string^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidreceipt_status*string"accepted""succeeded""failed""unknown"curl -X POST 'https://example.com/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/resume' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "expected_revision": 8}'{ "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c", "receipt_status": "accepted"}