Consolidation Worksheet

post/extensions/roboledger/{graph_id}/operations/consolidation-worksheet

The group's statement for one window with the entity as the column, read live from the tenant's OLTP ledger: the parent and each member consolidated in full, their combined sum, the consolidation entity's adjustments, the consolidated total, and each equity-method or cost member beside the sum, never in it. Every column renders under the group parent's Reporting Style. Rejected on shared-repository graphs.

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
`statement_type`required	string	income_statement \| balance_sheet \| cash_flow_statement \| equity_statement.
`period_start`optional	string (date)	Explicit window start. Overrides period_type/fiscal_year.
`period_end`optional	string (date)	Explicit window end. Overrides period_type/fiscal_year.
`period_type`optional	string	annual \| quarterly \| instant (ignored when dates supplied)
`fiscal_year`optional	integer	Fiscal year for annual window (anchored on FiscalCalendar)
`limit`optional	integer	Max rows returned. Defaults to the ceiling: the whole statement. Default: `1000` Constraints: 1–1000

Example request

curl

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

ConsolidationWorksheetResponse

Command-specific result payload

ConsolidationWorksheetResponse fields

Field Type Description

graph_idrequired

string

The graph read.

entity_idrequired

string

The group parent.

statement_typerequired

string

The statement rendered.

periodrequired

PeriodSpec

The window every column reads. The cash flow also pivots the prior window of equal length as its delta basis; it is 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').

columnsrequired

WorksheetColumn[]

The parent, each member consolidated in full, combined, the consolidation entity's adjustments (when the group has one), consolidated, then the equity-method and cost members outside the sum. A member outside its membership interval for the period has no column.

WorksheetColumn fields

Field	Type	Description
`key`required	string	The entity id for an entity's column; `combined` and `consolidated` for the two totals.
`label`required	string	The entity's name, or the total's.
`kind`required	string	`member`: the parent or a member consolidated in full. `combined`: the members' sum, nothing eliminated. `adjustments`: the consolidation entity's entries. `consolidated`: combined plus the adjustments. `not_summed`: an equity-method or cost member, shown beside the sum and never in it. One of: `member`, `combined`, `adjustments`, `consolidated`, `not_summed`
`entity_id`optional	string	The entity the column reads; null on a total.
`consolidation_method`optional	string	The entity's `consolidation_method`; null on a total.
`ownership_pct`optional	number	The parent's share of the entity, where it has one.
`in_sum`required	boolean	Whether the column is part of the consolidated total.

rowsrequired

WorksheetRow[]

The union of every column's lines in the parent's Style order; a line zero in every column is left out.

WorksheetRow fields

Field	Type	Description
`qname`required	string	The rs-gaap concept of the line.
`name`required	string	The line's label.
`trait`optional	string	The concept's classification.
`values`required	number[]	One value per column, aligned with `columns`.
`depth`optional	integer	Indentation in the statement. Default: `0`
`is_subtotal`optional	boolean	Whether the line is a total. 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.

validationoptional

ValidationCheckResponse

The guard-rail outcome for the consolidated column, the same checks live-financial-statement runs.

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_entity_idsoptional

string[]

Entities with no CoA mapping yet, so with no column.

unmapped_countoptional

integer

Unmapped accounts across the summed columns.

Default: 0

truncatedoptional

boolean

Whether limit cut rows.

Default: false

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