Preview Event Block

post/extensions/roboledger/{graph_id}/operations/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.

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_type`required	string	Open vocabulary: 'invoice_issued' \| 'contract_signed' \| 'bank_transaction' \| ...
`event_category`required	string	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. One of: `sales`, `purchase`, `financing`, `payroll`, `treasury`, `adjustment`, `recognition`, `other`, `control`, `approval`, `reconciliation`, `inquiry`
`event_class`optional	string	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). One of: `economic`, `support` Default: `economic`
`event_action`optional	string	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. 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	ID of the counterparty agent (customer, vendor, employee, lender) involved in the event. `null` for internal-only events.
`resource_type`optional	string	REA resource kind being exchanged. One of: `goods`, `services`, `money`, `right`, `obligation`, `information`, `labor`. One of: `goods`, `services`, `money`, `right`, `obligation`, `information`, `labor`
`resource_element_id`optional	string	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_at`required	string (date-time)	When the event happened in the real world
`effective_at`optional	string (date-time)	Accounting recognition date, if different from occurred_at
`source`required	string	'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_id`optional	string	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_url`optional	string	Deep link back to source-system record
`amount`optional	integer	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'`).
`currency`optional	string	ISO 4217 currency code for `amount`. Default: `USD`
`description`optional	string	Free-text human-readable summary of the event.
`metadata`optional	object	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_ids`optional	string[]	IDs of dimension members tagging this event (e.g. department, fund, project). Propagate to the GL entries produced by the handler.
`obligated_by_event_id`optional	string	Forward-materialization link: the event that scheduled or obligated this one (e.g. depreciation entries point at the 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).
`apply_handlers`optional	boolean	When True, resolves the event_type to a handler (Python registry first, then DSL) and fires it atomically with event creation. Default: `false`

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/preview-event-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'

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

PreviewEventBlockResponse

Command-specific result payload

PreviewEventBlockResponse fields

Field Type Description

matched_handleroptional

EventHandlerResponse

EventHandlerResponse fields

Field	Type	Description
`id`required	string
`name`required	string
`description`optional	string
`event_type`required	string
`event_category`optional	string
`match_source`optional	string
`match_agent_type`optional	string
`match_resource_type`optional	string
`match_metadata_expression`optional	object
`transaction_template`required	object
`priority`required	integer
`is_active`required	boolean
`origin`required	string
`suggested_by`optional	string
`confidence`optional	number
`approved_by`optional	string
`approved_at`optional	string (date-time)
`created_at`optional	string (date-time)
`updated_at`optional	string (date-time)
`created_by`optional	string

planned_transactionsoptional

TransactionPreview[]

A planned GL entry line from preview-event-block (no rows written).

TransactionPreview fields

Field	Type	Description
`entry_index`required	integer
`debit_element_id`required	string
`credit_element_id`required	string
`amount_cents`required	integer
`interpolated_debit_amount`required	string
`interpolated_credit_amount`required	string

validation_errorsoptional string[]

would_succeedrequired boolean

handler_metadataoptional

object

Handler-specific compute output. For Python handlers like 'asset_disposed', includes NBV, gain/loss, accumulated depreciation. Empty for DSL-handler previews.

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