---
title: "Preview Event Block"
method: POST
path: "/extensions/roboledger/{graph_id}/operations/preview-event-block"
tags: ["RoboLedger: Ledger & Events"]
---

# Preview Event Block

`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

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.

## Path parameters

- `graph_id` string, required

## Headers

- `Idempotency-Key` string, nullable

## Request body

- CreateEventBlockRequest: Write surface for a single business event.
  - `entity_id` string, 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_type` string, required: Open vocabulary: 'invoice_issued' | 'contract_signed' | 'bank_transaction' | ...
  - `event_category` 'sales' | 'purchase' | 'financing' | 'payroll' | 'treasury' | 'adjustment' | 'recognition' | 'other' | 'control' | 'approval' | 'reconciliation' | 'inquiry', required: 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).
  - `event_action` 'produce' | 'raise' | 'consume' | 'lower' | 'use' | 'cite' | 'work' | 'deliverService' | 'pickup' | 'dropoff' | 'accept' | 'transferCustody' | 'transferAllRights' | 'transfer' | 'move' | 'modify' | 'combine' | 'separate' | 'copy', nullable: 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_id` string, nullable: ID of the counterparty agent (customer, vendor, employee, lender) involved in the event. `null` for internal-only events.
  - `resource_type` 'goods' | 'services' | 'money' | 'right' | 'obligation' | 'information' | 'labor', nullable: REA resource kind being exchanged. One of: `goods`, `services`, `money`, `right`, `obligation`, `information`, `labor`.
  - `resource_element_id` string, 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_at` string, date-time, required: When the event happened in the real world
  - `effective_at` string, date-time, nullable: Accounting recognition date, if different from occurred_at
  - `source` string, 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_id` string, 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_url` string, nullable: Deep link back to source-system record
  - `amount` integer, 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'`).
  - `currency` string: ISO 4217 currency code for `amount`.
  - `description` string, nullable: Free-text human-readable summary of the event.
  - `metadata` 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` 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` string, nullable: Forward-materialization link: the event that scheduled or obligated this one (e.g. depreciation entries point at the asset_acquired event).
  - `discharges_event_id` string, nullable: Settlement link: the obligation this event discharges (e.g. cash_received pointing at the originating sale_invoiced).
  - `document_id` string, 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_handlers` boolean: When True, resolves the event_type to a handler (Python registry first, then DSL) and fires it atomically with event creation.

## Response `200`

Successful Response

- OperationEnvelopePreviewEventBlockResponse
  - `operation` string, required: Kebab-case operation name
  - `operationId` string, required: op_-prefixed ULID for audit and SSE correlation
  - `status` 'completed' | 'pending' | 'failed', required: Operation lifecycle state
  - `result` PreviewEventBlockResponse: Dry-run result — what would happen if this event block were created.
    - `matched_handler` EventHandlerResponse
      - `id` string, required
      - `name` string, required
      - `description` string, nullable
      - `event_type` string, required
      - `event_category` string, nullable
      - `match_source` string, nullable
      - `match_agent_type` string, nullable
      - `match_resource_type` string, nullable
      - `match_metadata_expression` object, nullable
      - `transaction_template` object, required
      - `priority` integer, required
      - `is_active` boolean, required
      - `origin` string, required
      - `suggested_by` string, nullable
      - `confidence` number, nullable
      - `approved_by` string, nullable
      - `approved_at` string, date-time, nullable
      - `created_at` string, date-time, nullable
      - `updated_at` string, date-time, nullable
      - `created_by` string, nullable
    - `planned_transactions` TransactionPreview[]
      - `entry_index` integer, required
      - `debit_element_id` string, required
      - `credit_element_id` string, required
      - `amount_cents` integer, required
      - `interpolated_debit_amount` string, required
      - `interpolated_credit_amount` string, required
    - `validation_errors` string[]
    - `would_succeed` boolean, required
    - `handler_metadata` object: Handler-specific compute output. For Python handlers like 'asset_disposed', includes NBV, gain/loss, accumulated depreciation. Empty for DSL-handler previews.
  - `at` string, required: ISO-8601 UTC timestamp
  - `createdBy` string, nullable: User ID that initiated the operation
  - `idempotentReplay` boolean: True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

## Other responses

- `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

---

[API](https://skmtc.dev/robosystems/apis/robosystems-api.md) · [All operations](https://skmtc.dev/robosystems/apis/robosystems-api/llms.txt) · [OpenAPI document](https://skmtc.dev/robosystems/apis/robosystems-api/revisions/e661e2d5ca6a?raw)