Browse the extensions reference

Create Information Block

post/extensions/roboledger/{graph_id}/operations/create-information-block

Part 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-Key header.
  • Bearer token in the Authorization header.

Path parameters

NameTypeDescription
graph_idrequiredstringGraph Id

Constraints: matches ^(kg[a-f0-9]{16,}(?:_[a-zA-Z0-9]{1,20})?|sec(?:_[a-zA-Z0-9]{1,20})?|library)$

Header parameters

NameTypeDescription
Idempotency-KeyoptionalstringIdempotency-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.

FieldTypeDescription
block_typerequiredstring

Discriminator value selecting this arm.

payloadrequiredCreateScheduleRequest

Schedule creation payload.

CreateScheduleRequest fields
FieldTypeDescription
namerequiredstring

Schedule name

taxonomy_idoptionalstring

Taxonomy ID (auto-creates if omitted)

element_idsrequiredstring[]

CoA element ids the schedule touches (the id from get-unmapped-elements, not taxonomy qnames) — typically the same debit + credit ids used in entry_template.

period_startrequiredstring (date)

First period start

period_endrequiredstring (date)

Last period end

monthly_amountrequiredinteger

Monthly amount in cents

entry_templaterequiredEntryTemplateRequest
EntryTemplateRequest fields
FieldTypeDescription
debit_element_idrequiredstring

CoA element id to debit (e.g. Depreciation Expense). This is a chart-of-accounts element id — the id returned by get-unmapped-elements / get-graph-schema — NOT a taxonomy qname.

credit_element_idrequiredstring

CoA element id to credit (e.g. Accumulated Depreciation). A chart-of-accounts element id (see get-unmapped-elements), not a taxonomy qname. One template = one debit/credit pair; model a multi-account entry as several schedules.

entry_typeoptionalstring

Entry type for generated entries

One of: standard, adjusting, closing, reversing

Default: closing

memo_templateoptionalstring

Memo template ({structure_name} is replaced)

Default:

auto_reverseoptionalboolean

Auto-generate a reversing entry on the first day of the next period

Default: false

schedule_metadataoptionalScheduleMetadataRequest
ScheduleMetadataRequest fields
FieldTypeDescription
methodoptionalstring

Calculation method. 'straight_line' (default) distributes monthly_amount evenly across periods with the final period absorbing rounding. 'custom' requires periodic_amounts — the generator uses those values verbatim instead of computing. Other strings are labels only; fact values still come from monthly_amount or periodic_amounts.

Default: straight_line

original_amountoptionalinteger

Cost basis in cents

Default: 0

residual_valueoptionalinteger

Salvage value in cents. The schedule expenses original_amount less this; net book value ends at it.

Default: 0

useful_life_monthsoptionalinteger

Useful life in months

Default: 0

asset_element_idoptionalstring

BS asset element for net book value

booked_onoptionalstring (date)

The date the cost went on the books, when that is before the schedule's first period: a policy paid in December that starts amortizing in January, or an asset bought the month before it is placed in service. From this date until the first period the schedule carries its full cost, so the schedule reconciliation does not report that balance as unscheduled. Leave it out when the cost is booked in the first period.

periodic_amountsoptionalinteger[]

Explicit per-period amounts in cents. When set, the generator uses these values instead of monthly_amount — enabling non-straight-line schedules (effective-interest bond discount amortization, day-count interest accrual, variable lease payments, pre-computed effective-yield curves, etc.). Length must match the number of monthly periods between period_start and period_end; sum must equal original_amount less residual_value exactly. The auto-generated SumEquals rule proves that total regardless of the curve shape.

closed_throughoptionalstring (date)

Watermark for onboarding. Facts with period_end ≤ this date are flagged 'historical' and their schedule_entry_due obligations are emitted 'voided', so the close workflow starts drafting at the first open period. Set this to the last day of the fiscal calendar's closed_through month (calendar '2026-05' → '2026-05-31') whether those months were actually closed in RoboLedger or just baseline-watermarked at initialization. Omitting it (when prior periods exist) leaves pre-watermark periods as 'pending' obligations that block the first close.

source_transaction_idoptionalstring

Free-form reference to the originating GL transaction (e.g. an import ID, ledger entry ID, or external system key). Stored in artifact_mechanics for audit; no FK constraint.

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.

FieldTypeDescription
block_typerequiredstring

Discriminator value selecting this arm.

payloadrequiredCreateRollforwardRequest

Rollforward creation payload.

CreateRollforwardRequest fields
FieldTypeDescription
namerequiredstring

Human-readable block name.

bs_source_qnamerequiredstring

QName of the balance-sheet element whose period delta this block decomposes. Resolved to bs_source_element_id at create time.

default_change_tag_qnameoptionalstring

QName of the fallback flow concept (Tier 1 default change tag). Residual amount — Δ BS minus the sum of filter-matched amounts — is attributed to this concept. When omitted, residual surfaces unattributed; the validation_mode setting governs whether that's a hard error.

attribution_filtersoptionalAttributionFilter[]

Filter predicates routing LineItems to flow concepts.

AttributionFilter fields
FieldTypeDescription
target_qnamerequiredstring

QName of the flow concept this filter produces facts for — e.g. rs-gaap:ProceedsFromIssuanceOfCommonStock. Resolved to target_element_id at create time.

target_element_idoptionalstring

Resolved element id for target_qname. Null at create time; populated by the handler before persistence. Round-tripped in the envelope.

predicaterequiredLineItemMetadataPredicate

Predicate that determines which LineItems match this filter.

validation_modeoptionalstring

How the renderer arbitrates when Σ filter matches != Δ BS. strict raises; residual_as_default emits the residual as a default-tag fact (the common case); warn_only logs and lets the imbalance pass.

One of: strict, residual_as_default, warn_only

Default: residual_as_default

taxonomy_idoptionalstring

Owning taxonomy id (auto-resolved from bs_source_qname when omitted).

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.

FieldTypeDescription
block_typerequiredstring

Discriminator value selecting this arm.

payloadrequiredCreateForecastRequest

Forecast creation payload.

CreateForecastRequest fields
FieldTypeDescription
namerequiredstring

Human-readable scenario name.

scenario_kindoptionalstring

What kind of scenario this is — metadata for display/filtering, not machinery. All kinds compute identically.

One of: budget, forecast, projection

Default: forecast

horizon_monthsoptionalinteger

Forward months to project past the base period.

Default: 12

Constraints: 1–36

base_periodoptionalstring

Seed month (YYYY-MM) the walk projects forward from. Defaults to the fiscal calendar's closed-through period, else the newest actual report month. Resolved and stored at create time, and it never moves afterwards — every lever is keyed to a month inside base_period + 1 … + horizon_months, so moving it would mean restating all of them. base_anchor decides whether the walk still *seeds* here once months close under it.

Constraints: matches ^\d{4}-(0[1-9]|1[0-2])$

base_anchoroptionalstring

Where the walk takes its opening balances as periods close. seam (default) re-anchors on the newest closed month inside the horizon, so the scenario survives a close untouched and its first forward month rolls off real balances. fixed pins the walk to base_period — the deliberate counterfactual, whose balances are meant to diverge from actuals.

One of: seam, fixed

Default: seam

leversrequiredLeverAssertionRequest[]

Lever assertions — at least one.

Constraints: at least 1 item

LeverAssertionRequest fields
FieldTypeDescription
qnamerequiredstring

QName of the rs-driver lever element (e.g. rs-driver:RevenueGrowthRate).

valueoptionalnumber

Uniform value asserted for every month of the horizon.

values_by_periodoptionalobject

Per-month overrides keyed by YYYY-MM. Wins over value for the months it names.

line_assertionsoptionalLineAssertionRequest[]

Direct statement-line assertions (manual overrides). Each names a calc-DAG leaf and wins over driver rules and carry-forward for the months it asserts.

LineAssertionRequest fields
FieldTypeDescription
qnamerequiredstring

QName of the statement leaf to assert (e.g. rs-gaap:NonoperatingIncomeExpense). Must be a calc-DAG leaf; rs-driver concepts belong in levers.

valueoptionalnumber

Uniform value asserted for every month of the horizon.

values_by_periodoptionalobject

Per-month overrides keyed by YYYY-MM. Wins over value for the months it names.

line_growthoptionalLineGrowthRequest[]

Per-line growth trajectories. Each names an income-statement leaf and grows it month-over-month at the asserted rate — the generic form of the revenue growth lever, for lines the catalog doesn't drive (opex trajectories, cost-cut ramps).

LineGrowthRequest fields
FieldTypeDescription
qnamerequiredstring

QName of the income-statement leaf to grow (e.g. rs-gaap:ResearchAndDevelopmentExpense). Must be a calc-DAG duration leaf.

valueoptionalnumber

Uniform month-over-month growth rate for every month of the horizon (decimal: 0.02 = +2%/mo, -0.05 = -5%/mo).

Constraints: greater than -1

values_by_periodoptionalobject

Per-month rate overrides keyed by YYYY-MM. Wins over value for the months it names; months named by neither carry the line's prior value (rate 0).

entity_idoptionalstring

Entity the scenario belongs to. Defaults to the graph's earliest-created entity (single-entity convention).

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.

FieldTypeDescription
block_typerequiredstring

Statement-family or metric block type. The endpoint returns 501 for these values — statements are constructed via create-report; metric construction is pending.

One of: balance_sheet, income_statement, cash_flow_statement, equity_statement, comprehensive_income, regulatory_disclosure, metric, reconciliation

payloadoptionalobject

Untyped payload — typed-arm validation is skipped because the dispatch handler raises 501 before the payload is consumed.

Example request

curl · block_type = schedule
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 · block_type = 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": "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 · block_type = forecast
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

FieldTypeDescription
operationrequiredstring

Kebab-case operation name

operationIdrequiredstring

op_-prefixed ULID for audit and SSE correlation

statusrequiredstring

Operation lifecycle state

One of: completed, pending, failed

resultoptionalInformationBlockEnvelope

Command-specific result payload

InformationBlockEnvelope fields
FieldTypeDescription
idrequiredstring
block_typerequiredstring

Discriminator — 'schedule', …

namerequiredstring
display_namerequiredstring

Registry-sourced display label (e.g., 'Schedule').

categoryrequiredstring

Registry-sourced sidebar grouping ('Close', 'Reporting', …).

taxonomy_idoptionalstring

Source taxonomy the Structure was seeded from. Always present for currently-registered block types (the Structure → Taxonomy FK is non-null); declared optional to keep the shape forward-compatible with future synthetic blocks that don't originate from a taxonomy.

taxonomy_nameoptionalstring

Display name of the source taxonomy.

disclosure_idoptionalstring

Qname of the named Disclosure this block corresponds to (e.g., 'disclosures:BalanceSheet'), when an inbound reportedDisclosure-requiresDisclosure arc identifies one. Null for tenant-authored blocks without a Disclosure mapping.

information_modelrequiredInformationModelResponse

The block's intrinsic shape — concept + member arrangement patterns.

InformationModelResponse fields
FieldTypeDescription
concept_arrangementoptionalstring

roll_up | roll_forward | variance | adjustment | set | arithmetic | textblock. Null for block types where the concept arrangement is implicit in their mechanics.

member_arrangementoptionalstring

is_a | whole_part | nested_whole_part | two_dimension_aggregation | complex_aggregating_whole_part, or null if non-hypercube.

artifactrequiredArtifactResponse

The block's producible-artifact envelope — topic, template, mechanics.

ArtifactResponse fields
FieldTypeDescription
topicoptionalstring

Structure.description — the block's human-readable topic.

renderer_noteoptionalstring

e.g. 'in thousands', 'except per share'.

templateoptionalobject

Reusable layout (ordering, subtotals, styling) when attached. First-class templates are not yet implemented; this field is always null on currently-shipped block types.

mechanicsrequiredScheduleMechanics | StatementMechanics | MetricMechanics | RollforwardMechanics | ForecastMechanics | ReconciliationMechanics
elementsoptionalElementLite[]

Element projection for bundling inside an Information Block envelope. Narrower than :class:LibraryElementResponse — excludes the heavy fields (labels, references, classifications) that library browsing needs but block consumers don't. Agents + frontends ask for those on demand via the full library GraphQL fields when they need them.

ElementLite fields
FieldTypeDescription
idrequiredstring
qnameoptionalstring
namerequiredstring
codeoptionalstring
element_typerequiredstring

concept | abstract | axis | member | hypercube

is_abstractoptionalboolean

Default: false

is_monetaryoptionalboolean

Default: true

balance_typeoptionalstring
period_typeoptionalstring
item_typeoptionalstring

Value-domain vocabulary (monetary | ratio | percent | multiple | days | string | …). None means untyped; fall back to is_monetary.

documentationoptionalstring

The element's documentation-role label — the catalog's authoritative value semantics (e.g. whether a percent driver is a growth rate or a rate-on-base fraction). None when the element carries no documentation label.

connectionsoptionalConnectionLite[]

Connection (= Association) projection. "Connection" is the ontology term used on the wire; the storage table is associations (models/extensions/association.py).

ConnectionLite fields
FieldTypeDescription
idrequiredstring
from_element_idrequiredstring
to_element_idrequiredstring
association_typerequiredstring

presentation | calculation | mapping | equivalence | general-special | essence-alias

arcroleoptionalstring
order_valueoptionalnumber
weightoptionalnumber
classificationsoptionalClassificationLite[]

Association-level classifications — concept_arrangement, member_arrangement, named_disclosure rows from the junction. Empty for library-seeded associations that haven't been classified yet.

factsoptionalFactLite[]

Fact projection — just the values the envelope caller cares about.

FactLite fields
FieldTypeDescription
idrequiredstring
element_idrequiredstring
element_nameoptionalstring
element_qnameoptionalstring
valueoptionalnumber

Numeric value; null for Nonnumeric (text-block) facts.

text_valueoptionalstring

Text payload for Nonnumeric facts; null for numeric.

fact_typeoptionalstring

Numeric | Nonnumeric

Default: Numeric

content_typeoptionalstring

MIME type of text_value (e.g. 'text/markdown').

period_startoptionalstring (date)
period_endrequiredstring (date)
period_typerequiredstring
unitoptionalstring

Default: USD

fact_scoperequiredstring

historical | in_scope

fact_set_idoptionalstring
rulesoptionalRuleLite[]

Rule projection for the Information Block envelope. One row per public.rules entry scoped to this block. The rule engine consumes rule_expression + rule_variables to evaluate against the in-scope fact set; the envelope surfaces the rules so the UI can render them as a checklist alongside any persisted verification results.

RuleLite fields
FieldTypeDescription
idrequiredstring
rule_categoryrequiredstring

One of 8 cm:VerificationRule subclasses — AutomatedAccountingAndReportingChecks, FundamentalAccountingConceptRelation, PeerConsistencyRule, PriorPeriodConsistencyRule, ReportLevelModelStructureRule, ReportingSystemSpecificRule, ToDoManualTask, XBRLTechnicalSyntaxRule.

rule_patternoptionalstring

Arithmetic / logical pattern evaluated over fact values. One of 11 cm:BusinessRulePattern mechanisms — Adjustment, CoExists, EqualTo, Exists, GreaterThan, GreaterThanOrEqualToZero, LessThan, RollForward, RollUp, SumEquals, Variance. Null when the rule is a structural check (see rule_check_kind).

rule_check_kindoptionalstring

Model-structure check kind evaluated over the association graph. One of 6 kinds — LeafHasClassification, LibraryOriginImmutability, NoCycles, NoOrphanArcs, ParentBeforeChild, UniqueQNameInTaxonomy. Null when the rule is an arithmetic pattern (see rule_pattern). Exactly one of rule_pattern / rule_check_kind is non-null per rule.

rule_expressionrequiredstring
rule_targetoptionalRuleTargetLite

Polymorphic rule target — points at the atom the rule is scoped to.

rule_variablesoptionalRuleVariableLite[]

$Variable → concept qname binding for a rule expression.

rule_messageoptionalstring
rule_severityoptionalstring

Failure severity — 'info' | 'warning' | 'error'. Enum closure enforced by the public.rules CHECK constraint.

Default: error

rule_originoptionalstring

Provenance — 'forked' (from an upstream artifact, e.g. an external XBRL taxonomy) or 'native' (authored in this seed or by a tenant). Enum closure enforced by the public.rules CHECK constraint.

Default: native

dimensionsoptionalobject[]
fact_setoptionalFactSetLite

The period-specific FactSet this envelope instantiates. Null when the underlying block has no FactSet row yet — typically library-seeded statement Structures with no tenant-generated facts, or Schedule rows written before the create-side FactSet stamping was added.

FactSetLite fields
FieldTypeDescription
idrequiredstring
structure_idoptionalstring
period_startoptionalstring (date)
period_endrequiredstring (date)
factset_typerequiredstring

'report' | 'schedule' | 'custom' | 'disclosure' | 'metric'. Enum closure enforced by the public.fact_sets CHECK constraint.

entity_idrequiredstring
report_idoptionalstring

Back-pointer to the parent row in reports. Null when the FactSet does not belong to a report package.

scenario_idoptionalstring

Scenario axis (the forecast engine). NULL = actuals; non-NULL names the owning forecast block whose parallel universe this set belongs to.

provenanceoptionalobject

Typed FactProvenance descriptor (discriminated on origin: pivot | schedule | derived | asserted | document | forecast | filed) recording how this FactSet was constructed. It describes the set, not each fact: a pivot set's mapped leaves aggregate posted line items, while its subtotals and derivations are computed from those leaves. Surfaced as JSON, mirroring how mechanics is exposed. Null when the FactSet carries no descriptor.

verification_resultsoptionalVerificationResultLite[]

Persisted outcome of one Rule evaluation. One row per public.verification_results entry the rule engine writes. The envelope surfaces them so the block viewer's "Verification Results" tab and MCP list-verification-failures tool can render + aggregate without a second round-trip.

VerificationResultLite fields
FieldTypeDescription
idrequiredstring
rule_idrequiredstring
structure_idoptionalstring
fact_set_idoptionalstring
statusrequiredstring

'pass' | 'fail' | 'error' | 'skipped'. Enum closure enforced by the public.verification_results CHECK constraint.

messageoptionalstring
period_startoptionalstring (date)
period_endoptionalstring (date)
evaluated_atoptionalstring (date-time)
verification_summaryoptionalVerificationSummary

Server-computed aggregate over verification_results — overall pass/fail/error/skip counts plus a per-rule_category breakdown for the grouped Verification Results panel. Null when the block has no verification results.

VerificationSummary fields
FieldTypeDescription
totaloptionalinteger

Default: 0

passedoptionalinteger

Default: 0

failedoptionalinteger

Default: 0

erroredoptionalinteger

Default: 0

skippedoptionalinteger

Default: 0

by_categoryoptionalVerificationCategorySummary[]

Pass/fail/skip counts for one rule_category within a block's verification results. Drives the per-category accordions in the Verification Results panel. category is the rule's rule_category (one of the cm:VerificationRule subclasses), resolved by joining each result to its Rule.

viewoptionalViewProjections

Server-computed view projections (the six type-of View projections). view.rendering carries pre-computed rows + periods + validation for blocks where rendering is deterministic (the statement family today). Projections without backend support yet are empty — see :class:ViewProjections.

ViewProjections fields
FieldTypeDescription
renderingoptionalRenderingLite

Pre-computed rendering projection of an Information Block. Computed server-side at envelope-build time for blocks where rendering is deterministic (the statement family today; future block types add their own rendering builders). The frontend's BlockView Rendering projection consumes this directly — no client-side rollup, depth computation, or calculation walk needed.

chartoptionalChartLite

Server-shaped chart projection — panel/series CONFIG, never values. The second real server-computed View arm (after rendering). Values come from rendering.rows joined by element_id; the x-axis is rendering.periods. Renderers (report-components) turn one panel into one chart.

atrequiredstring

ISO-8601 UTC timestamp

createdByoptionalstring

User ID that initiated the operation

idempotentReplayoptionalboolean

True when this envelope came from the idempotency cache — the underlying command did not execute again. False on fresh executions.

Default: false

StatusMeaning
400Invalid request
401Authentication required
403Access denied
404Resource not found
409Idempotency-Key conflict — key reused with different body
422Validation error
429Rate limit exceeded
500Internal server error