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

# Execute Event Block

`POST /extensions/roboledger/{graph_id}/operations/execute-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/execute-event-block`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

For events on a connection with write_policy='qb_authoritative' or 'hybrid', publish the event's draft GL entries to the source-of-truth system (QuickBooks), each as its own JournalEntry. Records the QuickBooks ids per entry on event.metadata.qb_entry_ids and promotes the published entries to 'posted'; the event goes 'fulfilled' once no draft remains, or 'pending' on rejection (what landed is kept). Native-policy events fast-path through with no QB write — RoboSystems is the system of record.

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

- ExecuteEventBlockRequest: Request to publish an event to the source-of-truth system. For events on a connection with `write_policy='qb_authoritative'` (or `'hybrid'`), this triggers a synchronous write to QuickBooks: each draft entry posts as its own JournalEntry, with the entry id as the RequestId, and its QuickBooks id is recorded per entry on `event.metadata.qb_entry_ids`. The event goes `fulfilled` once no draft remains, or `pending` when QuickBooks rejects an entry (what landed is kept). `'native'`-policy events fast-path through with no QB write — RoboSystems IS the source of truth, no outbound publish needed.
  - `event_id` string, required: Event ID (`evt_*` ULID) to publish. The event's `metadata.connection_id` determines which QB connection to write to; the connection's `write_policy` governs whether a write fires.
  - `connection_id` string, nullable: Override for the connection to route the write through. Used by the close-period batch path where schedule-originated events don't carry `connection_id` in their metadata. When unset, the command reads `event.metadata.connection_id`.

## Response `200`

Successful Response

- OperationEnvelopeExecuteEventBlockResponse
  - `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` ExecuteEventBlockResponse: Outcome of an `execute-event-block` call.
    - `event_id` string, required: Echo of the event ID.
    - `status` string, required: The event's status after the call. Unchanged when no write fired (native policy, a source that does not publish) or when drafts in a later period are still unpublished. `'fulfilled'` once every draft entry of the event is in QuickBooks and posted. `'pending'` when QuickBooks rejected an entry — see `qb_error`; retry after fixing the underlying issue.
    - `qb_external_id` string, nullable: QuickBooks JournalEntry ID of the first entry this call published. Null when nothing was published. When a call publishes several entries, `qb_entry_ids` holds them all.
    - `qb_entry_ids` object, nullable: Every entry of the event now in QuickBooks: ledger entry ID → QuickBooks JournalEntry ID. Null when none are.
    - `qb_error` object, nullable: QB rejection detail when a publish failed. Shape: `{code, message, qb_response_at}`. Operator retries after fixing CoA mapping / amount validation / closed-period.
  - `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)