RoboLedger: Ledger & Events

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, unless it already wrote them when the event was created; 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.

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.

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

Request

  • Base URL: https://api.robosystems.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-event-block
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

event_idstring required

Target event ID.

transition_to'classified' | 'committed' | 'pending' | 'fulfilled' | 'voided' | 'superseded' nullable

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.

superseded_by_idstring nullable

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

descriptionstring nullable

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

effective_atstring date-time nullable

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

metadata_patchobject

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

event_action'produce' | 'raise' | 'consume' | 'lower' | 'use' | 'cite' | 'work' | 'deliverService' | 'pickup' | 'dropoff' | 'accept' | 'transferCustody' | 'transferAllRights' | 'transfer' | 'move' | 'modify' | 'combine' | 'separate' | 'copy' nullable

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.

obligated_by_event_idstring nullable

Set/update the forward-materialization link.

discharges_event_idstring nullable

Set/update the settlement link.

document_idstring nullable

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

{
  "event_id": "evt_abc123",
  "transition_to": "committed"
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

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

Changes

No recorded changes to this operation across all 1 revision of this API.