CrankCrank HTTP and agent contract
All paths begin /api/crank. GET requests need a current session or agent
credential; trigger credentials cannot read. Cookie POSTs require the exact
configured Origin. Bearer requests use Authorization: Bearer <credential>.
Bodies are JSON objects. Core requests are limited to 64 KiB. Import requests
allow a 128 KiB source in a 256 KiB JSON envelope. Errors are JSON {error}.
| Method and path | Role | Meaning |
|---|---|---|
GET /state |
Person or agent | Flows, last 200 runs, matching decisions and attempts; owners also see token metadata |
GET /flows/:id, /runs/:id |
Person or agent | Exact record |
POST /flows |
Owner, admin, agent | Draft with name,source_app,destination_app,target_url |
POST /flows/:id/activate, /pause |
Native/dev owner | Start/stop admitting new events |
POST /flows/:id/runs |
Owner, admin, agent | Prepare {event_id,input} for approval |
POST /flows/:id/trigger |
Scoped trigger key | Same event envelope; exactly one authorized flow |
POST /runs/:id/approve, /reject |
Native/dev owner | Immutable recorded decision; approve makes first delivery attempt |
POST /runs/:id/replay |
Native/dev owner | One further delivery for a failed/expired attempt, same bytes and key |
POST /tokens |
Native/dev owner | {label,scope:"agent"} or {label,scope:"trigger",flow_id}; one-time token |
POST /tokens/:id/revoke |
Native/dev owner | Immediately revoke |
POST /imports/plan |
Native/dev owner | {namespace,source}; no native writes |
POST /imports/apply |
Native/dev owner | Same input plus reviewed fingerprint |
GET /imports |
Native/dev owner | Last 100 durable import jobs and approvals |
POST /imports/:id/undo |
Native/dev owner | Undo unused drafts, refusing target drift |
POST /data/export |
Native/dev owner | Download installation archive |
POST /data/restore |
Native/dev owner | {archive,confirm:"RESTORE",journal?}; empty destination only |
POST /data/erase |
Native/dev owner | {run_id,confirm:"ERASE"}; paused flow, terminal run |
POSTs without other fields use {}. A failed HTTP attempt records a safe status
code, uncertainty and timing, never arbitrary destination response content.
An interrupted delivery lease becomes failed when state is next read; it never
automatically retries. Rejected and successful runs cannot replay. A replay
of an expired first attempt still uses the same receiver idempotency key.
Pause stops new admission. It does not cancel an already-approved network request. Pending runs may still be deliberately approved or rejected by the owner. Erasure does not undo destination effects or erase the source app's records. Run IDs, event digests and value-free deletion records remain for deduplication and restoration fences. Data archives contain sensitive workflow inputs.