ReferenceHTTP APISession control

Interrupt the targeted turn only

POST
/v1/sessions/{id}/interrupt

Asks the worker to stop turn target_turn_id while it runs; the session's admission state and its other turns are left alone. The event stream shows a status event with phase interrupting when the worker takes the request and engine_stopped when the engine has stopped the turn; the turn reads interrupted once its checkpoint commits. If the turn has not ended 60 seconds after acceptance, its execution is killed.

Accepted while the turn runs: the receipt settles when the turn ends, with a result of {turn_id, terminal, no_op}. A new request for a turn that has already ended answers receipt_status: succeeded at once, and its receipt says no_op: true with the terminal the turn reached on its own: the interrupt did nothing. An interrupt accepted while the turn ran is no_op: true too when the turn got to another terminal first; when the turn's outcome is unknown, so is the receipt (status: unknown, no_op: false). A replayed Idempotency-Key answers the receipt's current status instead.

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
target_turn_id*string
Length1 <= length

Response Body

The interrupt is stored (accepted), or the turn had already ended (succeeded, no_op: true on the receipt).

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"
Example Request
curl -X POST 'https://example.com/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08/interrupt' \  -H 'Idempotency-Key: string' \  -H 'Content-Type: application/json' \  -d '{  "target_turn_id": "2"}'
Example Response
{  "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c",  "receipt_status": "accepted"}