RoboLedger: Ledger & Events

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.

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/create-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/create-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' | ...

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_idstring 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_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.