リファレンスHTTP APISession control

Block dispatch and force the execution down

POST
/v1/sessions/{id}/terminate

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.

Authorization

headerAuthorizationBearer <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

Path Parameters

id*string

The session's id.

Match^([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)$
Formatuuid

Header Parameters

Idempotency-Key*string

Required, 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.

Length1 <= length <= 255
X-Requested-With?"werft-web"

Required with a cookie session: the literal werft-web.

Value in"werft-web"

Request Body

application/json
  1. body
expected_revision*integer
Range0 <= value <= 2147483647
reason?string
Length1 <= length

Response Body

The terminate is stored (accepted), or there was nothing to kill and the session is stopped (succeeded).

application/json
  1. response
receipt_id*string
Match^([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)$
Formatuuid
receipt_status*string
Value in"accepted""succeeded""failed""unknown"
external_effects_reverted*boolean
Example Request
curl -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"}'
Example Response
{  "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c",  "receipt_status": "accepted",  "external_effects_reverted": false}