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 fires against the captured metadata to produce the GL 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.

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

Header parameters

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

Request body

Required, application/json.

Field	Type	Description
`event_id`required	string	Target event ID.
`transition_to`optional	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_id`optional	string	New event id that replaces this one. Required when transition_to='superseded'.
`description`optional	string	Replacement free-text summary. Unset = unchanged; pass an empty string to clear.
`effective_at`optional	string (date-time)	New accounting recognition date. Unset = unchanged. Useful when an event was captured against the wrong period.
`metadata_patch`optional	object	Key-value pairs merged into existing metadata (additive patch, not replace).
`event_action`optional	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_id`optional	string	Set/update the forward-materialization link.
`discharges_event_id`optional	string	Set/update the settlement link.

Example request

curl

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"
}'

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`.
`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`).
`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 (null for legacy callers)

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