Skip to main content
POST
Request durable-run cancellation
Request cancellation of a durable Praxa run and reconcile the run until it reaches an authoritative terminal outcome.
Availability: Production partner preview. Required scope: runs:write.

Authenticate safely

Create a disposable personal workspace API key with exactly runs:write. Send it as Authorization: Bearer $PRAXA_API_KEY. A Gateway OAuth token, Supabase JWT, provider credential, or organization memory key is not interchangeable with this key. The hosted playground sends the credential from your browser session to the documented API through the configured playground proxy. Use test data, never share the key, and revoke it when the check ends.

Request fields

string
required
id path parameter.

Runnable request examples

What success means

A 200 response acknowledges the cancellation request and returns a run projection; it does not imply rollback or immediate cancellation.

Successful response

200 — Updated run projection. Acceptance does not imply rollback or an immediate cancelled state. Internal cancelling and reconcile_required states both map to running until the run reaches a terminal outcome.
v1
required
apiVersion response field.
string
required
run_id response field.
string
required
requestId response field.
task
required
mode response field.
queued | running | awaiting_approval | completed | failed | cancelled
required
Public lifecycle status. Internal cancelling and reconcile_required states project as running; reconciliation is not terminal.
string
required
createdAt response field.
string
required
updatedAt response field.
string
completedAt response field.
object
Present only when Praxa can derive the exact recorded browser action and bind it to the stored action digest. The summary contains the exact recorded instruction or steps followed by the target host.
object
Present only for schema-valid, digest-matched verified text.
object
failure response field.
links response field.

Handle failures

Example problem

Verify the result

  1. Confirm the returned run ID matches the target.
  2. Continue run or event readback until terminal.
  3. Do not report cancellation while the projection remains running.

Retry, cleanup, and production use

  • Treat 401, 403, and 409 as authority or state signals, not generic retry prompts.
  • For 429 or retryable 5xx responses, follow server retry guidance and keep a bounded attempt budget.
  • Move the request into a trusted application backend before production; never ship the Praxa key in browser or mobile code.
  • Revoke the disposable key, disable test webhooks, and erase disposable candidate data after validation.
Continue with API authentication, the failure and retry guide, and the end-to-end coverage matrix.
Last modified on August 14, 2026