Create Report

post/extensions/roboledger/{graph_id}/operations/create-report

Generates report facts from the ledger and marks the report as published.

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

Header parameters

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

Request body

Required, application/json.

Field Type Description

namerequired

string

Human-readable report name shown in lists and headers.

taxonomy_idoptional

string

Taxonomy that defines the structures (BS / IS / CF / Equity / Schedules) this report can render. Accepts either an exact tenant-specific taxonomy UUID or a standard name (e.g. 'rs-gaap'). Standard names resolve to the latest reporting_standard taxonomy with that name. Defaults to 'rs-gaap', the canonical reporting vocabulary.

Default: rs-gaap

mapping_idrequired

string

Mapping structure that rolls up the tenant's chart of accounts to the taxonomy's reporting concepts. Created via `create-mapping-association` / `auto-map-elements`.

period_startrequired

string (date)

Current-period start (inclusive). Ignored when `periods` is supplied.

period_endrequired

string (date)

Current-period end (inclusive). Must be >= `period_start`. Ignored when `periods` is supplied.

period_typeoptional

string

Period cadence: `monthly`, `quarterly`, or `annual`.

Default: quarterly

comparativeoptional

boolean

When true, automatically generates a prior-period column (same length as the current period). Ignored when `periods` is supplied.

Default: true

periodsoptional

PeriodSpec[]

Explicit period columns. When set, overrides `period_start`/`period_end`/`comparative`. Use for multi-period layouts (YTD-by-quarter, multi-year, custom rolling windows).

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').

Example request

curl

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-report" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "comparative": true,
  "mapping_id": "map_01HVF8T0M2YTAY3BBNRH0V0",
  "name": "Q3 2026 Financials",
  "period_end": "2026-09-30",
  "period_start": "2026-07-01",
  "period_type": "quarterly",
  "taxonomy_id": "tax_usgaap_reporting"
}'

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

ReportResponse

Command-specific result payload

ReportResponse fields

Field Type Description

idrequired

string

Report identifier (ULID).

namerequired

string

Human-readable report name.

taxonomy_idrequired

string

Taxonomy this report renders against.

generation_statusrequired

string

Computation lifecycle: `generating`, `published`, `failed`. Orthogonal to `filing_status`.

period_typerequired

string

Period cadence: `monthly`, `quarterly`, `annual`.

period_startoptional

string (date)

Current-period start.

period_endoptional

string (date)

Current-period end.

comparativerequired

boolean

True when an auto-generated prior-period column is included.

periodsoptional

PeriodSpec[]

Explicit period columns when the report was created with a multi-period layout.

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').

mapping_idoptional

string

CoA → taxonomy mapping the facts were rolled up through.

ai_generatedoptional

boolean

True when the report was created by an AI agent rather than a user.

Default: false

created_atrequired

string (date-time)

When the report row was created.

last_generatedoptional

string (date-time)

When the facts were last (re)generated.

structuresoptional

StructureSummary[]

Structures available for this report's taxonomy — renderable sections (BS / IS / CF / Equity / Schedules).

StructureSummary fields

Field	Type	Description
`id`required	string	Structure identifier.
`name`required	string	Human-readable structure name.
`block_type`required	string	Structure category: `balance_sheet`, `income_statement`, `cash_flow_statement`, `equity_statement`, `schedule`.

entity_nameoptional

string

Display name of the primary entity the report is tagged to.

filing_statusoptional

string

Filing lifecycle (orthogonal to `generation_status`): `draft`, `under_review`, `filed`, `archived`.

Default: draft

filed_atoptional

string (date-time)

When the report was transitioned to `filed`.

filed_byoptional

string

User ID that transitioned the report to `filed`.

supersedes_idoptional

string

When this report restates an earlier filing, the predecessor's report ID.

superseded_by_idoptional

string

When this report has been restated, the successor's report ID.

source_graph_idoptional

string

Origin graph for received (shared) reports — populated only on the recipient's copy.

source_report_idoptional

string

Origin report ID for received (shared) reports — populated only on the recipient's copy.

shared_atoptional

string (date-time)

When the report was shared into this graph (recipient side).

rule_summaryoptional

object

Counts by rule outcome (e.g. `{'passed': 12, 'failed': 1}`) from the most recent evaluation. Null until rules run.

atrequired

string

ISO-8601 UTC timestamp

createdByoptional

string

User ID that initiated the operation (null for legacy callers)

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