Interrupt the targeted turn only
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.
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
target_turn_id*string1 <= lengthThe interrupt is stored (accepted), or the turn had already ended (succeeded, no_op: true on the receipt).
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/interrupt' \ -H 'Idempotency-Key: string' \ -H 'Content-Type: application/json' \ -d '{ "target_turn_id": "2"}'{ "receipt_id": "c4a1e9d2-7b3f-4e8a-a6c5-1d2e3f4a5b6c", "receipt_status": "accepted"}