The open queue-log format, version 1
Any queue that can export a log can feed the Autonomy Ladder. A queue sends six kinds of events: what the steps are, each item as it arrives, each step a person or an agent did, how each disagreement was settled, what an audit found, and who signed off a promotion. The same events can be sent as JSON (POST /v1/events) or as one flat CSV (POST /v1/events/csv) for teams that can only export spreadsheets.
- JSON Schema:
docs/log-format.schema.json(draft 2020-12). The API validates every event against it; nothing invalid is stored. - Examples:
docs/examples/events.jsonand the same events as CSV indocs/examples/events.csv. - Version: every event carries
"v": 1. A later version will add fields, never change the meaning of these.
Common fields (every event)
| Field | Required | Meaning |
|---|---|---|
v | yes | Format version, 1. |
id | yes | Your id for this event. Sending the same id twice stores it once, so a failed upload can simply be sent again. Letters, digits and . _ : / # @ -, up to 128 characters. |
type | yes | One of queue.defined, item.created, step.done, settlement, audit.result, signoff. |
at | yes | When it happened at the source, ISO 8601 with a time zone (2026-01-05T08:02:10Z). The Ladder's weeks run Monday to Sunday, UTC, counted from the workspace's first item. |
queue | yes | The queue id inside the workspace (a workspace can hold several queues). |
workspace | no | The workspace comes from the key. If you include it, it must match. |
1. queue.defined: workspace, queue and steps
Send once, and again whenever a step is added or changed (the latest definition wins).
| Field | Meaning |
|---|---|
queue_name | Plain name of the queue. |
steps[].id, name, order | The step and where it sits in the flow. |
steps[].money_moving | true if the step moves money or commits the business to a payment. Promotion of such a step to Auto needs a named person's signoff. |
steps[].inputs | Item features this step reads (for example ["doc_format"]). The Ladder watches their mix for input shift. |
steps[].fields | How each output field is compared: text (case and spacing differences are cosmetic), id, code, number, decision, money, party, critical_decision, ignore. Any real difference in money, party or critical_decision is critical. |
steps[].audit_rate | Share of items audited while the step runs in Auto (default 0.10). |
steps[].minutes | A person's minutes per item, used to count hours freed. |
2. item.created: an item arrives
| Field | Meaning |
|---|---|
item | Your item id (a bill number, a load number, a ticket number). |
features | Input features as flat key-value pairs: text, numbers or true/false. Include anything that describes what kind of input this is, such as the document format id, the channel, the customer segment. |
3. step.done: a person or an agent did a step
| Field | Meaning | |
|---|---|---|
item, step | Which item and which step. | |
actor | `{ "kind": "operator" | "agent", "id": "...", "version": "..." }`. Give agents a version; a new version is visible in the ledger. |
role | work: a person did it alone. shadow: the agent did it unseen. proposal: the agent proposed. confirm: a person's final answer after seeing a proposal. act: the agent acted alone. | |
output.fields | The step's output at field level. | |
output.decision | The step's main decision, if it has one (it is compared as a critical_decision unless fields says otherwise). | |
confidence | The agent's own confidence, 0 to 1, if it has one. | |
started_at, ended_at | When the work started and ended. | |
route_id | The id of the /v1/route answer the agent acted on. |
The Ladder pairs the agent's output with the person's for the same item and step, field by field, and types the difference: none, cosmetic, material or critical.
4. settlement: who was right in a disagreement
| Field | Meaning | ||
|---|---|---|---|
item, step | The disagreement being settled. | ||
verdict | agent_right, operator_right or both_wrong. | ||
settler | `{ "kind": "person" | "model" | "rule", "id": "..." }`. |
reason | One line on why, from the evidence. | ||
evidence_ref | Where the evidence lives (a document link, a recording id). |
5. audit.result: an audited Auto item
While a step runs in Auto, the route API picks a seeded sample of items for audit. A person checks the agent's output and reports:
| Field | Meaning |
|---|---|
item, step, auditor.id | What was audited and by whom. |
verdict | pass or fail. |
severity | For a fail: cosmetic, material or critical. A critical fail demotes the step. |
reason, evidence_ref | As for settlement. |
6. signoff: a person approves a promotion
| Field | Meaning |
|---|---|
step, lane | The step and the lane it may move to (auto for money-moving steps). |
decision | approved or declined. |
by | { "id": "...", "role": "..." }, the named approver. |
request_id | The id from the signoff.requested webhook, if this answers one. |
The flat CSV layout
One row per event, with these fixed columns (leave a cell empty when it does not apply):
v,id,type,at,queue,item,step,actor_kind,actor_id,actor_version,role,decision,confidence,started_at,ended_at,route_id,
verdict,settler_kind,settler_id,reason,evidence_ref,auditor_id,severity,lane,by_id,by_role,signoff_decision,request_id,
queue_name,step_name,step_order,money_moving,step_inputs,step_audit_rate,step_minutesand three families of open columns:
out.<field>: one column per output field ofstep.done(for exampleout.total_cents);feat.<name>: one column per item feature ofitem.created(for examplefeat.doc_format);rule.<field>: the comparison rule of a field in a step definition (for examplerule.total_cents=money).
A queue definition is written as one step.defined row per step, all with the same id; they are read back as one queue.defined event. step_inputs is a semicolon list. Cells are read back as: empty = null, true/false = true/false, plain numbers without a leading zero = numbers, anything else = text. See docs/examples/events.csv.
Exports from ServiceNow and Salesforce do not need converting by hand: the API's adapters map them to this format (see docs/api.md).