Update Event Block

post/extensions/roboledger/{graph_id}/operations/update-event-block

Apply a status transition (captured → classified | committed | voided) and/or field corrections (description, effective_at, metadata_patch) to an existing event block. Only supplied fields are updated. captured → classified records an account choice without posting — for a bank-feed line, patch metadata.classified_element_id (or accept_suggestion: true) in the same call. When the transition is captured/classified → committed, the registered Python handler (else the matching event handler's template) fires against the captured metadata to produce the GL rows, unless it already wrote them when the event was created; an event with a handler cannot skip to pending or fulfilled without rows. A bank-feed line with no account chosen and no matching rule is refused. Errors from the handler (validation, element resolution, closed period, unbalanced lines) surface as 422 here so the inbox UI can display the failure reason without retry. A bank line's flow is a second classification beside its account, overriding the account's default flow on the cash flow and equity statements: patch classified_flow_qname (or flow_qname on each classified_allocations part) with an rs-gaap flow concept such as rs-gaap:ProceedsFromIssuanceOfLongTermDebt. On a line that has already posted, this re-tags its lines in place, in a closed month too, since no balance moves; an empty string clears it. A payment or bank line records the invoices or bills it settles with discharge_allocations (positive cents per document, together at most its amount) or one discharges_event_id; each is checked: an invoice for money in, a bill for money out, on its own entity, not voided.

Idempotency: supply an Idempotency-Key header to make safe retries; replays within 24 hours return the same envelope. Reusing the key with a different body returns HTTP 409 Conflict.

Authentication

Authenticate in any one of these ways — not all of them:

API key in the X-API-Key header.
Bearer token in the Authorization header.

Path parameters

Name	Type	Description
`graph_id`required	string	Graph Id Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

Name	Type	Description
`Idempotency-Key`optional	string	Idempotency-Key

Request body

Required, application/json.

Field Type Description

event_idrequired

string

Target event ID.

transition_tooptional

string

Status transition. Valid moves depend on current status: captured → classified | committed | voided | superseded; classified → committed | pending | fulfilled | voided | superseded; committed → pending | fulfilled | voided | superseded; pending → fulfilled | voided | superseded; fulfilled → voided | superseded. A retraction (voided, superseded) is final and is refused from any status once the event's ledger rows have posted or it has published to QuickBooks — reverse the posted entries instead. captured → classified records an account choice without posting (bank-feed lines: patch classified_element_id, or accept_suggestion: true, in the same call); the later commit fires the handler. Note: classified and fulfilled are otherwise set by handlers, not by callers, but the transition is allowed for corrections.

One of: classified, committed, pending, fulfilled, voided, superseded

superseded_by_idoptional

string

New event id that replaces this one. Required when transition_to='superseded'.

descriptionoptional

string

Replacement free-text summary. Unset = unchanged; pass an empty string to clear.

effective_atoptional

string (date-time)

New accounting recognition date. Unset = unchanged. Useful when an event was captured against the wrong period.

due_dateoptional

string (date)

New due date of an obligation (an invoice_issued or a bill_received), such as an extension granted. Unset = unchanged. It moves no ledger row, so it is accepted in a closed period.

metadata_patchoptional

object

Key-value pairs merged into existing metadata (additive patch, not replace).

event_actionoptional

string

Set or correct the canonical action verb. Unset = unchanged. Useful when an adapter improvement makes a previously-NULL verb fillable, or when reclassifying after the fact.

One of: produce, raise, consume, lower, use, cite, work, deliverService, pickup, dropoff, accept, transferCustody, transferAllRights, transfer, move, modify, combine, separate, copy

obligated_by_event_idoptional

string

Set/update the forward-materialization link.

discharges_event_idoptional

string

Set the settlement link: the one invoice or bill this payment settles, at its full amount; an empty string clears it. Replaces any discharge_allocations. Checked as they are.

discharge_allocationsoptional

DischargeAllocation[]

What this payment settles, document by document: one row per invoice or bill with the positive cents applied to it, together at most the payment's amount (the rest is unapplied). Replaces any held; an empty list clears them, and the settlement link becomes the first row's. Each must be an obligation of this event's entity, not voided: an invoice for money in, a bill for money out. A person chooses them; the open items a bank line may settle are dischargeCandidates over GraphQL.

DischargeAllocation fields

Field Type Description

obligation_event_idrequired

string

The invoice_issued or bill_received event it settles.

amountrequired

integer

Positive cents of the payment applied to it.

Constraints: greater than 0

document_idoptional

string

Set or replace the stored document the event rests on; an empty string detaches it. Must be a document on this graph. Unset = unchanged.

Example request

curl · example 1 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-event-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "evt_abc123",
  "transition_to": "committed"
}'

curl · example 2 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-event-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Reviewed and approved by controller",
  "effective_at": "2026-04-30T23:59:59Z",
  "event_id": "evt_abc123",
  "metadata_patch": {
    "review_note": "Recognized in April per terms",
    "reviewed_by": "usr_controller_jane"
  }
}'

curl · example 3 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-event-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "event_id": "evt_oldwrong",
  "superseded_by_id": "evt_newcorrect",
  "transition_to": "superseded"
}'

Responses

200 Successful Response

Field Type Description

operationrequired

string

Kebab-case operation name

operationIdrequired

string

op_-prefixed ULID for audit and SSE correlation

statusrequired

string

Operation lifecycle state

One of: completed, pending, failed

resultoptional

EventBlockEnvelope

Command-specific result payload

EventBlockEnvelope fields

Field	Type	Description
`id`required	string	Event ID (`evt_*` ULID).
`event_type`required	string	Open-vocabulary event type (e.g. `invoice_issued`, `bank_transaction`, `control_executed`).
`event_category`required	string	REA category, scoped by `event_class` — economic (`sales`, `purchase`, `financing`, `payroll`, `treasury`, `adjustment`, `recognition`, `other`), support (`control`, `approval`, `reconciliation`, `inquiry`), or operational (`pipeline`, `engagement`, `schedule`, `other`) for occurrences that drive no GL — a lead, a lifecycle change, an outreach, a schedule setup.
`status`required	string	Lifecycle state. One of: `captured` (raw, pre-classification), `classified` (handler ran, GL pending), `committed` (GL entries posted), `pending` (committed but awaiting fulfillment of an obligation), `fulfilled` (obligation discharged — retractable while its ledger rows are still drafts), `voided` (canceled — terminal), `superseded` (replaced by a corrected event — terminal). See `UpdateEventBlockRequest.transition_to` for the valid transition graph.
`occurred_at`required	string (date-time)	When the event happened in the real world (UTC).
`effective_at`optional	string (date-time)	Accounting recognition date, when different from `occurred_at`.
`due_date`optional	string (date)	When the obligation falls due (an `invoice_issued` or a `bill_received`); null when none was stated, which reads as due on receipt, and on every other event type.
`source`required	string	Capture source: `manual`, `system`, `schedule`, a connected provider name (e.g. `quickbooks`), or a registered external source_name. Used for adapter routing.
`external_id`optional	string	Source-system dedup key. Unique with `source` when set, so adapter retries are idempotent.
`external_url`optional	string	Deep link back to the source-system record.
`amount`optional	integer	Economic value in cents of `currency`, signed (inflows positive, outflows negative). `null` for non-economic events.
`currency`required	string	ISO 4217 currency code for `amount`.
`description`optional	string	Free-text human-readable summary.
`metadata`required	object	Free-form payload — handler-specific keys when the event ran through a handler, otherwise whatever the adapter captured.
`is_reconciling_item`optional	boolean	True when this event is a reconciling item: a source re-sync surfaced a changed upstream payload for an event whose GL is already posted (committed/fulfilled are immutable to sync) — the local books legitimately no longer mirror the source, and the difference awaits an explicit disposition (restate the affected months, or book a catch-up entry in the open period). The live payload and GL are untouched; the incoming payload is stashed in `metadata.drift_payload` with `metadata.drift_detected_at`. Default: `false`
`dimension_ids`required	string[]	Dimension-member IDs tagging this event (department, fund, project). Propagate to GL entries produced by the handler.
`event_class`required	string	REA event class — `economic` (drives GL postings) or `support` (audit-trail / value-chain primitive, no GL impact).
`event_action`optional	string	Canonical action verb refining `event_category`. Null when the source adapter or capture path didn't supply one. One of: `produce`, `raise`, `consume`, `lower`, `use`, `cite`, `work`, `deliverService`, `pickup`, `dropoff`, `accept`, `transferCustody`, `transferAllRights`, `transfer`, `move`, `modify`, `combine`, `separate`, `copy`
`agent_id`optional	string	Counterparty agent ID, when the event involves one.
`resource_type`optional	string	REA resource kind being exchanged (`goods`, `services`, `money`, `right`, `obligation`, `information`, `labor`).
`resource_element_id`optional	string	Specific element ID being exchanged, when known.
`replaced_by_event_id`optional	string	ID of the event that replaces this one. Set when this event was superseded (`status='superseded'`); points forward in the correction chain.
`replaces_event_id`optional	string	ID of the event this one replaces, when applicable. Points backward in the correction chain. Mirror of `replaced_by_event_id` on the predecessor.
`obligated_by_event_id`optional	string	Forward-materialization link — the event that scheduled or obligated this one (e.g. depreciation entries point at the originating `asset_acquired` event).
`discharges_event_id`optional	string	Settlement link — the obligation this event discharges (e.g. `cash_received` pointing at the originating `sale_invoiced`).
`document_id`optional	string	The stored document the event rests on (an invoice, a bill, a receipt, a statement); read it with get-document.
`created_at`required	string (date-time)	Row creation timestamp (UTC).
`created_by`required	string	ID of the user who captured the event. For adapter-sourced events, the system actor associated with the adapter.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation

idempotentReplayoptional

boolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

Status	Meaning
400	Invalid request
401	Authentication required
403	Access denied
404	Resource not found
409	Idempotency-Key conflict — key reused with different body
422	Validation error
429	Rate limit exceeded
500	Internal server error