RoboLedger: Ledger & Events

Preview Event Block

Dry-run: resolve the matching handler and evaluate the transaction template without writing any rows. Returns the matched handler + planned debit/credit lines + any validation errors. Use this before create-event-block(apply_handlers=True) to confirm the GL plan.

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/preview-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/preview-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

entity_idstring nullable

The entity whose books the event lands in, by id; every GL row its handler writes follows it. Omit for the group parent.

event_typestring required

Open vocabulary: 'invoice_issued' | 'contract_signed' | 'bank_transaction' | ...

REA classification. Economic categories (sales, purchase, financing, payroll, treasury, adjustment, recognition, other) require event_class='economic'. Support categories (control, approval, reconciliation, inquiry) require event_class='support'. The DB CHECK rejects mismatched pairings.

event_class'economic' | 'support'

REA event class. 'economic' events change resources and drive GL postings; 'support' events are audit-trail / value-chain primitives (typically captured with apply_handlers=False).

Canonical action verb refining event_category. Disambiguates concepts ERPs collapse: transferAllRights (ownership transfer, no physical movement) vs transferCustody (physical only, no rights transfer) — load-bearing for consignment, drop-shipping, marketplace settlement, escrow. Optional; null is valid for legacy events and during adapter rollout.

agent_idstring nullable

ID of the counterparty agent (customer, vendor, employee, lender) involved in the event. null for internal-only events.

REA resource kind being exchanged. One of: goods, services, money, right, obligation, information, labor.

resource_element_idstring nullable

ID of the specific element being exchanged, when known (e.g. the cash account for a treasury movement, the inventory item for a sale).

occurred_atstring date-time required

When the event happened in the real world

effective_atstring date-time nullable

Accounting recognition date, if different from occurred_at

sourcestring required

'manual' | 'system' | 'schedule', a connected provider name (e.g. 'quickbooks'), or a source_name registered via an 'external' connection. Validated against the graph's registered connections.

external_idstring nullable

Source-system dedup key. (source, external_id) is enforced unique when external_id is provided, so retries from external adapters are idempotent at the DB level.

external_urlstring nullable

Deep link back to source-system record

amountinteger nullable

Economic value of the event in cents of currency, signed. Sign convention follows the perspective of the entity that owns the graph: inflows positive, outflows negative. null for non-economic events (e.g. event_class='support').

currencystring

ISO 4217 currency code for amount.

descriptionstring nullable

Free-text human-readable summary of the event.

metadataobject

Free-form payload, opaque to the event surface. When apply_handlers=True, the matched handler's metadata schema validates this dict — required keys depend on the handler registered for event_type. Use preview-event-block to discover the expected shape without writing.

dimension_idsstring[]

IDs of dimension members tagging this event (e.g. department, fund, project). Propagate to the GL entries produced by the handler.

obligated_by_event_idstring nullable

Forward-materialization link: the event that scheduled or obligated this one (e.g. depreciation entries point at the asset_acquired event).

discharges_event_idstring nullable

Settlement link: the obligation this event discharges (e.g. cash_received pointing at the originating sale_invoiced).

document_idstring nullable

The stored document this event rests on, as evidence: the invoice PDF, the vendor bill, the receipt photo (upload it with create-document-upload and complete-document-upload). Must be a document on this graph. While the event is live, the document cannot be deleted.

apply_handlersboolean

When True, resolves the event_type to a handler (Python registry first, then DSL) and fires it atomically with event creation.

Example request

{
  "agent_id": "ent_customer_acme",
  "amount": 250000,
  "currency": "USD",
  "description": "April consulting retainer — Acme Corp",
  "dimension_ids": [
    "dim_dept_consulting"
  ],
  "event_category": "sales",
  "event_class": "economic",
  "event_type": "invoice_issued",
  "external_id": "qb_inv_4521",
  "external_url": "https://app.qbo.intuit.com/app/invoice?txnId=4521",
  "metadata": {
    "invoice_number": "INV-2026-0421",
    "terms": "net_30"
  },
  "occurred_at": "2026-05-01T14:30:00Z",
  "resource_type": "services",
  "source": "quickbooks"
}

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.