Block dispatch and force the execution down
Stops the session by force, in any admission state but closed: dispatch is blocked, queued input is cancelled (each input's receipt fails with SESSION_STOPPED), open requests close and the execution is killed. The session goes stopping until the kill is observed, then stopped; with nothing to kill it is stopped at once and the receipt is succeeded in the response. A recovery_required session keeps that state. A turn the kill cut short may end outcome_unknown, which holds the session in recovery_required until POST /v1/sessions/{id}/recovery-decisions. The kill reverts nothing the execution already did outside (commits, pushes, API calls): the response and the receipt say external_effects_reverted: false. The receipt result is {execution_gone, checkpoint_revision, unconfirmed_turn_id, external_effects_reverted}. Resume a stopped session from its last checkpoint with POST /v1/sessions/{id}/resume. A pause or close still draining is overtaken: its receipt fails with CONTROL_SUPERSEDED. To end a session whose work is done, close it instead (POST /v1/sessions/{id}/close).
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 <= 2147483647reason?string1 <= lengthThe terminate is stored (accepted), or there was nothing to kill and the session is stopped (succeeded).
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"external_effects_reverted*booleancurl -X POST 'https://example.com/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/terminate' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "expected_revision": 7, "reason": "Runaway tool loop"}'{ "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c", "receipt_status": "accepted", "external_effects_reverted": false}