Live Financial Statement

post/extensions/roboledger/{graph_id}/operations/live-financial-statement

Generate an ad-hoc financial statement directly from the tenant's OLTP ledger data using the active CoA→GAAP mapping. This is the authoritative source for RoboLedger entity graphs — no graph materialization required. One entity's books: entity_id names a subsidiary, omitted means the group parent. On the parent, scope: combined sums every member consolidated in full at the rs-gaap concepts for the months each was a member, nothing eliminated, and scope: consolidated adds the consolidation entity's entries — the eliminations and noncontrolling interest. dimension slices an income statement by department, class, location or project: one member's lines, or a column per member with Unallocated and Total. Rejected on shared-repository graphs; those should use financial-statement-analysis instead.

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_idoptional

string

The entity whose books this acts on, by id. Omit for the group parent — the single-entity default.

statement_typerequired

string

income_statement | balance_sheet | cash_flow_statement | equity_statement. equity_statement is provisional — equity balances, not a rollforward — and is not offered on the MCP surface until it articulates.

period_startoptional

string (date)

Explicit window start. Overrides period_type/fiscal_year.

period_endoptional

string (date)

Explicit window end. Overrides period_type/fiscal_year.

period_typeoptional

string

annual | quarterly | instant (ignored when dates supplied)

fiscal_yearoptional

integer

Fiscal year for annual window (anchored on FiscalCalendar)

scopeoptional

string

entity (the default): one entity's own books. combined: on the group parent, every member consolidated in full rendered under the parent's Reporting Style and summed per rs-gaap concept, each for the months it was a member — the pre-adjustment total, nothing eliminated. consolidated: the same sum plus the consolidation entity, whose eliminations and noncontrolling interest are the adjustments column, so a group that posts its consolidating entries there reads its consolidated statement. An equity-method or cost member is never summed (its consolidation_method says so). Both group scopes are read on the group parent only (422 on a subsidiary). An entity with no CoA mapping yet contributes nothing and is left out of combined_entity_ids.

One of: entity, combined, consolidated

consolidatedoptional

boolean

The older spelling of scope: consolidated, kept for callers that pass it; scope wins when both are given.

Default: false

limitoptional

integer

Max fact rows returned. Defaults to the ceiling so a statement is never cut mid-section — visible rows would stop footing to visible subtotals. Lower it only for a preview.

Default: 1000

Constraints: 1–1000

dimensionoptional

StatementDimension

Slice an income statement by a management dimension (department, class, location, project). {type, member_id} reads one member's lines, current and prior; member_id: unallocated reads the lines no member of the axis tags. {type} alone reads the current window with one column per member, then Unallocated, then Total, and says in dimension.ties_out whether every row's members plus Unallocated equal its Total. Composes with scope and entity_id; a consolidation entity's lines are untagged, so eliminations read as Unallocated. Refused (422) on any other statement.

StatementDimension fields

Field	Type	Description
`type`required	string	The axis to slice by: `department`, `class`, and so on.
`member_id`optional	string	One member's lines only, by id, or `unallocated` for the lines no member of the axis tags. Omitted, a statement returns one column per member, then Unallocated, then Total, for the current window.

include_sourcesoptional

boolean

Add each row's origin and, per column, the accounts its figure was summed from (sources), each keyed by the entity whose books hold it, so a figure opens on the account registers behind it. Consolidated figures list each member's accounts and the consolidation entity's. Off by default: it multiplies the response. Refused (422) with a dimension read by column.

Default: false

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/live-financial-statement" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "statement_type": "string"
}'

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

LiveFinancialStatementResponse

Command-specific result payload

LiveFinancialStatementResponse fields

Field Type Description

graph_idrequired string

entity_idoptional

string

The entity whose books were rendered.

scopeoptional

string

What was rendered: entity, combined (the members summed, nothing eliminated) or consolidated (the members plus the consolidation entity's adjustments).

Default: entity

consolidatedoptional

boolean

Whether the group's entities were summed into this — true for the combined and consolidated scopes.

Default: false

combined_entity_idsoptional

string[]

The entities summed, parent first; on consolidated the consolidation entity comes last.

presentationoptional

string

Always 'live': the books as they stand, through the current mapping. A closed month's figures as its close stamped them (as_closed on build-fact-grid and on statement columns) can differ once a mapping was reclassified after the close.

Default: live

statement_typerequired string

periodsrequired

PeriodSpec[]

Rendered columns, aligned with each row's values. Current and prior for income_statement and balance_sheet; current only for cash_flow_statement — the prior period is pivoted as the indirect-method delta basis and not rendered.

PeriodSpec fields

Field	Type	Description
`start`required	string (date)	Period start date (inclusive). Window the column rolls up.
`end`required	string (date)	Period end date (inclusive). Window the column rolls up.
`label`required	string	Column header label (e.g. 'FY2025 Q3', '2024', 'YTD').

omitted_periodsoptional

PeriodSpec[]

Columns left out because they reach back before the books begin: on books that start from an opening balance, a flow statement column that starts before the first day it covers, or a balance sheet dated before it. They would show a partial figure, not the months before the books. On a group read, also a cash flow or equity statement column a member joined or left the group within.

PeriodSpec fields

Field	Type	Description
`start`required	string (date)	Period start date (inclusive). Window the column rolls up.
`end`required	string (date)	Period end date (inclusive). Window the column rolls up.
`label`required	string	Column header label (e.g. 'FY2025 Q3', '2024', 'YTD').

factsrequired

LiveStatementFactRow[]

A single row of an OLTP-backed ad-hoc statement.

LiveStatementFactRow fields

Field	Type	Description
`qname`required	string
`name`required	string
`trait`optional	string
`values`required	number[]
`depth`optional	integer	Default: `0`
`is_subtotal`optional	boolean	Default: `false`
`period_role`optional	string	On the equity roll-forward, `start` for the beginning-balance row and `end` for the ending-balance row. Null elsewhere.
`origin`optional	string	With `include_sources`, how the figure was made: `accounts` (summed from accounts in at least one column; read each column's `sources`, which may be empty where they do not add up), `subtotal` (the rows beneath it), or `computed` (derived from other figures, or a flow, with no accounts of its own). Null without `include_sources`. One of: `accounts`, `subtotal`, `computed`
`sources`optional	StatementRowSource[][]	With `include_sources`, per column (aligned with `values`), the accounts the figure was summed from, largest first; their values add up to the figure. Empty for a column with nothing to show, and for a subtotal or computed row.

fact_countrequired integer

validationoptional

ValidationCheckResponse

Guard-rail outcome for the rendered columns — accounting equation, net-income equation, totals footing, operating-plug size. Null only when no structure rendered.

ValidationCheckResponse fields

Field	Type	Description
`passed`required	boolean	True iff at least one rule ran and every rule produced zero failures on every rendered column. False when nothing was checked (`status == 'inconclusive'`).
`status`required	string	`passed` — every rule ran on every column with zero failures; `failed` — at least one rule failed; `inconclusive` — no validation rules exist for this block type, so nothing was checked.
`checks`required	string[]	Names of rules that were evaluated.
`failures`required	string[]	Human-readable descriptions of rule failures.
`warnings`required	string[]	Non-blocking advisories from rule evaluation.

unmapped_countoptional

integer

Default: 0

truncatedoptional

boolean

Default: false

dimensionoptional

StatementDimensionResponse

How the statement was sliced by a management dimension, when it was: the axis, the one member read, or the columns and whether they tie out to the Total.

StatementDimensionResponse fields

Field	Type	Description
`type`required	string	The axis the statement was sliced by.
`member_id`optional	string	The one member read, when the statement was filtered to one; null when it was read by column.
`columns`optional	StatementDimensionColumn[]	Read by column: one per member, then Unallocated, then Total, aligned with each row's `values` and with `periods`. Empty when filtered to one member.
`ties_out`optional	boolean	Read by column: whether every row's members plus Unallocated equal its Total. Null when filtered to one member.
`differences`optional	string[]	The rows whose members plus Unallocated miss the Total, by qname.

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