Create Information Block
/extensions/roboledger/{graph_id}/operations/create-information-blockPart of RoboLedger: Information Blocks.
Generic Information Block construction entry. block_type selects the registered block type; payload is validated against that type's creation schema at dispatch. Schedule dispatches to the existing Schedule machinery; statement block types raise 501 (use create-report instead). Authoring schedules for a close? Call get-close-playbook (mode='initiate') first — one schedule is a single debit/credit element pair, so multi-line entries become multiple schedules, and element ids must be real (discover via get-graph-schema / get-unmapped-elements / suggest-mapping).
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-Keyheader. - Bearer token in the
Authorizationheader.
Path parameters
| Name | Type | Description |
|---|---|---|
graph_idrequired | string | Graph Id Constraints: matches |
Header parameters
| Name | Type | Description |
|---|---|---|
Idempotency-Keyoptional | string | Idempotency-Key |
Request body
Required, application/json.
One of 4 shapes, chosen by block_type.
block_type = schedule
Create-information-block body for block_type="schedule".
Carries a typed schedule payload — full schedule shape is exposed inline in the OpenAPI schema so SDK callers see every required field.
| Field | Type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
block_typerequired | string | Discriminator value selecting this arm. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payloadrequired | CreateScheduleRequest | Schedule creation payload. CreateScheduleRequest fields
|
block_type = rollforward
Create-information-block body for block_type="rollforward".
Carries a typed rollforward payload. The block decomposes the period change in a BS source element across the declared attribution filters.
| Field | Type | Description | |||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
block_typerequired | string | Discriminator value selecting this arm. | |||||||||||||||||||||||||||||||||
payloadrequired | CreateRollforwardRequest | Rollforward creation payload. CreateRollforwardRequest fields
|
block_type = forecast
Create-information-block body for block_type="forecast".
Carries a typed forecast payload — the authored scenario container:
scenario identity, horizon, base period, lever assertions on
rs-driver:* catalog elements. Run compute-forecast after
creating to derive the forward months.
| Field | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
block_typerequired | string | Discriminator value selecting this arm. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payloadrequired | CreateForecastRequest | Forecast creation payload. CreateForecastRequest fields
|
block_type = balance_sheet, cash_flow_statement, comprehensive_income, equity_statement, income_statement, metric, reconciliation, regulatory_disclosure
Create-information-block body for block types that don't yet have a typed construction path at the API boundary.
Statement-family blocks (balance_sheet, income_statement,
cash_flow_statement, equity_statement, comprehensive_income) are
constructed via create-report, not this endpoint. Disclosure
structures (regulatory_disclosure) are vocabulary, authored via
create-taxonomy-block; their facts land when create-report
picks them. Metric blocks are recognized but their evaluator has
not shipped. Calling this endpoint with one of these block types
returns HTTP 501 with a hint pointing to the correct construction
path.
| Field | Type | Description |
|---|---|---|
block_typerequired | string | Statement-family or metric block type. The endpoint returns 501 for these values — statements are constructed via One of: |
payloadoptional | object | Untyped payload — typed-arm validation is skipped because the dispatch handler raises 501 before the payload is consumed. |
Example request
curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-information-block" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Idempotency-Key: <Idempotency-Key>" \
-H "Content-Type: application/json" \
-d '{
"block_type": "schedule",
"payload": {
"element_ids": [
"<depreciation_expense_element_id>",
"<accumulated_depreciation_element_id>"
],
"entry_template": {
"credit_element_id": "<accumulated_depreciation_element_id>",
"debit_element_id": "<depreciation_expense_element_id>",
"entry_type": "adjusting"
},
"monthly_amount": 83333,
"name": "Office Building Depreciation",
"period_end": "2030-12-31",
"period_start": "2026-01-01"
}
}'curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-information-block" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Idempotency-Key: <Idempotency-Key>" \
-H "Content-Type: application/json" \
-d '{
"block_type": "rollforward",
"payload": {
"attribution_filters": [
{
"predicate": {
"field": "transaction_description_code",
"kind": "line_item_metadata_field",
"values": [
"mini:ProceedsFromInvestmentsByOwner"
]
},
"target_qname": "mini:ProceedsFromInvestmentsByOwner"
}
],
"bs_source_qname": "mini:CashAndCashEquivalents",
"name": "Cash and Cash Equivalents Rollforward"
}
}'curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/create-information-block" \
-H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
-H "Idempotency-Key: <Idempotency-Key>" \
-H "Content-Type: application/json" \
-d '{
"block_type": "forecast",
"payload": {
"horizon_months": 12,
"levers": [
{
"qname": "rs-driver:RevenueGrowthRate",
"value": 0.03
},
{
"qname": "rs-driver:CostOfRevenueRate",
"value": 0.62
},
{
"qname": "rs-driver:DaysSalesOutstanding",
"value": 45
},
{
"qname": "rs-driver:DaysPayableOutstanding",
"value": 30
}
],
"name": "FY26 Operating Budget",
"scenario_kind": "budget"
}
}'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: | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
resultoptional | InformationBlockEnvelope | Command-specific result payload InformationBlockEnvelope fields
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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: |
| 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 |