Create Event Block

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

Persist a real-world business event. apply_handlers=False (default): capture-only, status='captured'. apply_handlers=True: resolves an event_handler, fires the template, creates GL entries atomically, status='classified'. Use preview-event-block to dry-run before committing. For journal_entry_recorded, whether the entry writes back to a connected source system follows source (schedule/manual publish; system does not) unless metadata.publish_to_source says otherwise — set it false for an alignment entry mirroring a change already made upstream, which would otherwise be applied twice. An invoice_issued or bill_received takes due_date, or terms_days (net N from occurred_at); with neither it is due on receipt. A later due date is a field correction on update-event-block.

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 Constraints: matches `^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?\|sec(?:_[a-zA-Z0-9]{1,20})?\|library)$`

Header parameters

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

Request body

Required, application/json.

Field	Type	Description
`entity_id`optional	string	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`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
`due_date`optional	string (date)	When an obligation falls due: an `invoice_issued` or a `bill_received`. Give it, or `terms_days`; with neither, the obligation is due on receipt. Refused on any other event type.
`terms_days`optional	integer	Net terms in days from `occurred_at` (30 for net 30), in place of `due_date`. Only on an `invoice_issued` or a `bill_received`. Constraints: 0–3650
`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[]	Management dimension members tagging this event (department, class, location, project), one per axis. Every line its handler writes carries them on the axes the line does not tag itself.
`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).
`document_id`optional	string	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`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 · example 1 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-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"
}'

curl · example 2 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-event-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": -125000,
  "apply_handlers": true,
  "currency": "USD",
  "description": "ACH out — Office rent May 2026",
  "event_category": "treasury",
  "event_class": "economic",
  "event_type": "bank_transaction",
  "external_id": "plaid_txn_abc123",
  "metadata": {
    "category": [
      "Rent"
    ],
    "merchant_name": "Westlake Properties LLC"
  },
  "occurred_at": "2026-05-03T00:00:00Z",
  "source": "plaid"
}'

curl · example 3 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-event-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Monthly bank reconciliation completed",
  "event_category": "control",
  "event_class": "support",
  "event_type": "control_executed",
  "metadata": {
    "control_id": "ctl_bank_recon_monthly",
    "reconciled_balance": 4287500
  },
  "occurred_at": "2026-05-06T16:00:00Z",
  "source": "manual"
}'

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`.
`due_date`optional	string (date)	When the obligation falls due (an `invoice_issued` or a `bill_received`); null when none was stated, which reads as due on receipt, and on every other event type.
`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`).
`document_id`optional	string	The stored document the event rests on (an invoice, a bill, a receipt, a statement); read it with get-document.
`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

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