Update Information Block

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

Generic Information Block update entry. Dispatches by block_type to the registered mutation handler. Block types whose Structures are library-seeded and immutable (statement family) surface 501.

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.

One of 4 shapes, chosen by block_type.

`block_type =` `schedule`

Update-information-block body for block_type="schedule".

Carries a typed schedule update payload — full editable shape is exposed inline.

Field Type Description

block_typerequired

string

Discriminator value selecting this arm.

payloadrequired

UpdateScheduleRequest

Schedule update payload.

UpdateScheduleRequest fields

Field Type Description

structure_idrequired string

nameoptional string

entry_templateoptional

EntryTemplateRequest

EntryTemplateRequest fields

Field	Type	Description
`debit_element_id`required	string	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_id`required	string	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_type`optional	string	Entry type for generated entries One of: `standard`, `adjusting`, `closing`, `reversing` Default: `closing`
`memo_template`optional	string	Memo template ({structure_name} is replaced) Default:
`auto_reverse`optional	boolean	Auto-generate a reversing entry on the first day of the next period Default: `false`

schedule_metadataoptional

ScheduleMetadataRequest

ScheduleMetadataRequest fields

Field	Type	Description
`method`optional	string	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_amount`optional	integer	Cost basis in cents Default: `0`
`residual_value`optional	integer	Salvage value in cents. The schedule expenses `original_amount` less this; net book value ends at it. Default: `0`
`useful_life_months`optional	integer	Useful life in months Default: `0`
`asset_element_id`optional	string	BS asset element for net book value
`booked_on`optional	string (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_amounts`optional	integer[]	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.

`block_type =` `rollforward`

Update-information-block body for block_type="rollforward".

Carries a typed rollforward update payload. Mutable fields: name, default_change_tag_qname, attribution_filters, validation_mode.

Field Type Description

block_typerequired

string

Discriminator value selecting this arm.

payloadrequired

UpdateRollforwardRequest

Rollforward update payload.

UpdateRollforwardRequest fields

Field Type Description

structure_idrequired

string

Structure ID of the rollforward block.

nameoptional string

default_change_tag_qnameoptional

string

New default change tag qname. Pass a value to *change* the default; omit (None) to leave unchanged. There is no wire-level way to clear the default — see the class docstring.

attribution_filtersoptional

AttributionFilter[]

One flow-concept attribution rule on a rollforward IB. Pairs a target concept (the flow leaf the matched amount counts toward) with a predicate (which LineItems match). The rollforward's attribution_filters: list[AttributionFilter] declares every flow the BS source decomposes into; the renderer evaluates them all per period. target_element_id is resolved at create time from target_qname via the rs-gaap library + tenant taxonomy lookup. Authors only need to provide the qname; the element_id is filled in by the create handler and the resolved value is what the envelope round-trips.

AttributionFilter fields

Field	Type	Description
`target_qname`required	string	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_id`optional	string	Resolved element id for `target_qname`. Null at create time; populated by the handler before persistence. Round-tripped in the envelope.
`predicate`required	LineItemMetadataPredicate	Predicate that determines which LineItems match this filter.

validation_modeoptional

string

One of: strict, residual_as_default, warn_only

`block_type =` `forecast`

Update-information-block body for block_type="forecast".

Mutable: name, scenario_kind, horizon_months, base_period, levers (full replace). Updating does not recompute — run compute-forecast to refresh the scenario's derived months.

Field Type Description

block_typerequired

string

Discriminator value selecting this arm.

payloadrequired

UpdateForecastRequest

Forecast update payload. Updating does NOT recompute — lever, horizon, or base-period changes leave the scenario's computed months stale until the next compute-forecast run.

UpdateForecastRequest fields

Field Type Description

structure_idrequired

string

Structure ID of the forecast block.

nameoptional string

scenario_kindoptional

string

One of: budget, forecast, projection

horizon_monthsoptional

integer

Constraints: 1–36

base_periodoptional

string

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

base_anchoroptional

string

Switch the walk between seam-anchored (default) and pinned to base_period. Changes nothing about the authored window, so unlike base_period it needs no levers re-supplied.

One of: seam, fixed

leversoptional

LeverAssertionRequest[]

Full replacement of the lever set when provided.

Constraints: at least 1 item

LeverAssertionRequest fields

Field	Type	Description
`qname`required	string	QName of the rs-driver lever element (e.g. `rs-driver:RevenueGrowthRate`).
`value`optional	number	Uniform value asserted for every month of the horizon.
`values_by_period`optional	object	Per-month overrides keyed by `YYYY-MM`. Wins over `value` for the months it names.

line_assertionsoptional

LineAssertionRequest[]

Full replacement of the line-assertion set when provided. Pass an empty list to clear every assertion.

LineAssertionRequest fields

Field	Type	Description
`qname`required	string	QName of the statement leaf to assert (e.g. `rs-gaap:NonoperatingIncomeExpense`). Must be a calc-DAG leaf; rs-driver concepts belong in `levers`.
`value`optional	number	Uniform value asserted for every month of the horizon.
`values_by_period`optional	object	Per-month overrides keyed by `YYYY-MM`. Wins over `value` for the months it names.

line_growthoptional

LineGrowthRequest[]

Full replacement of the line-growth set when provided. Pass an empty list to clear every growth entry.

LineGrowthRequest fields

Field Type Description

qnamerequired

string

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

valueoptional

number

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_periodoptional

object

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

`block_type =` `balance_sheet`, `cash_flow_statement`, `comprehensive_income`, `equity_statement`, `income_statement`, `metric`, `reconciliation`, `regulatory_disclosure`

Update-information-block body for block types that don't yet have a typed update path at the API boundary.

Statement-family blocks are library-seeded and immutable. Metric block updates are not yet implemented. Calling this endpoint with one of these block types returns HTTP 501.

Field Type Description

Field	Type	Description
`block_type`required	string	Statement-family or metric block type. Updates return 501 — statement Structures are library-seeded; metric updates are pending. One of: `balance_sheet`, `income_statement`, `cash_flow_statement`, `equity_statement`, `comprehensive_income`, `regulatory_disclosure`, `metric`, `reconciliation`
`payload`optional	object	Untyped payload — typed-arm validation is skipped because the dispatch handler raises 501 before the payload is consumed.

block_typerequired

string

Statement-family or metric block type. Updates return 501 — statement Structures are library-seeded; metric updates are pending.

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

payloadoptional

object

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/update-information-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "block_type": "schedule",
  "payload": {
    "name": "Office Building Depreciation (Renamed)",
    "structure_id": "struct_depr_office_2026"
  }
}'

curl · block_type = rollforward

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-information-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "block_type": "rollforward",
  "payload": {
    "name": "Cash Rollforward (Renamed)",
    "structure_id": "struct_rf_cash_2026"
  }
}'

curl · block_type = forecast

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/update-information-block" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "block_type": "forecast",
  "payload": {
    "levers": [
      {
        "qname": "rs-driver:RevenueGrowthRate",
        "value": 0.04
      },
      {
        "qname": "rs-driver:CostOfRevenueRate",
        "value": 0.62
      },
      {
        "qname": "rs-driver:DaysSalesOutstanding",
        "value": 45
      },
      {
        "qname": "rs-driver:DaysPayableOutstanding",
        "value": 30
      }
    ],
    "structure_id": "struct_fy26_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: completed, pending, failed

resultoptional

InformationBlockEnvelope

Command-specific result payload

InformationBlockEnvelope fields

Field Type Description

idrequired string

block_typerequired

string

Discriminator — 'schedule', …

namerequired string

display_namerequired

string

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

categoryrequired

string

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

taxonomy_idoptional

string

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_nameoptional

string

Display name of the source taxonomy.

disclosure_idoptional

string

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_modelrequired

InformationModelResponse

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

InformationModelResponse fields

Field	Type	Description
`concept_arrangement`optional	string	roll_up \| roll_forward \| variance \| adjustment \| set \| arithmetic \| textblock. Null for block types where the concept arrangement is implicit in their mechanics.
`member_arrangement`optional	string	is_a \| whole_part \| nested_whole_part \| two_dimension_aggregation \| complex_aggregating_whole_part, or null if non-hypercube.

artifactrequired

ArtifactResponse

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

ArtifactResponse fields

Field	Type	Description
`topic`optional	string	Structure.description — the block's human-readable topic.
`renderer_note`optional	string	e.g. 'in thousands', 'except per share'.
`template`optional	object	Reusable layout (ordering, subtotals, styling) when attached. First-class templates are not yet implemented; this field is always null on currently-shipped block types.
`mechanics`required	ScheduleMechanics \| StatementMechanics \| MetricMechanics \| RollforwardMechanics \| ForecastMechanics \| ReconciliationMechanics

elementsoptional

ElementLite[]

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

Field	Type	Description
`id`required	string
`qname`optional	string
`name`required	string
`code`optional	string
`element_type`required	string	concept \| abstract \| axis \| member \| hypercube
`is_abstract`optional	boolean	Default: `false`
`is_monetary`optional	boolean	Default: `true`
`balance_type`optional	string
`period_type`optional	string
`item_type`optional	string	Value-domain vocabulary (monetary \| ratio \| percent \| multiple \| days \| string \| …). None means untyped; fall back to is_monetary.
`documentation`optional	string	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.

connectionsoptional

ConnectionLite[]

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

ConnectionLite fields

Field	Type	Description
`id`required	string
`from_element_id`required	string
`to_element_id`required	string
`association_type`required	string	presentation \| calculation \| mapping \| equivalence \| general-special \| essence-alias
`arcrole`optional	string
`order_value`optional	number
`weight`optional	number
`classifications`optional	ClassificationLite[]	Association-level classifications — concept_arrangement, member_arrangement, named_disclosure rows from the junction. Empty for library-seeded associations that haven't been classified yet.

factsoptional

FactLite[]

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

FactLite fields

Field	Type	Description
`id`required	string
`element_id`required	string
`element_name`optional	string
`element_qname`optional	string
`value`optional	number	Numeric value; null for Nonnumeric (text-block) facts.
`text_value`optional	string	Text payload for Nonnumeric facts; null for numeric.
`fact_type`optional	string	Numeric \| Nonnumeric Default: `Numeric`
`content_type`optional	string	MIME type of text_value (e.g. 'text/markdown').
`period_start`optional	string (date)
`period_end`required	string (date)
`period_type`required	string
`unit`optional	string	Default: `USD`
`fact_scope`required	string	historical \| in_scope
`fact_set_id`optional	string

rulesoptional

RuleLite[]

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

Field	Type	Description
`id`required	string
`rule_category`required	string	One of 8 cm:VerificationRule subclasses — AutomatedAccountingAndReportingChecks, FundamentalAccountingConceptRelation, PeerConsistencyRule, PriorPeriodConsistencyRule, ReportLevelModelStructureRule, ReportingSystemSpecificRule, ToDoManualTask, XBRLTechnicalSyntaxRule.
`rule_pattern`optional	string	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_kind`optional	string	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_expression`required	string
`rule_target`optional	RuleTargetLite	Polymorphic rule target — points at the atom the rule is scoped to.
`rule_variables`optional	RuleVariableLite[]	`$Variable` → concept qname binding for a rule expression.
`rule_message`optional	string
`rule_severity`optional	string	Failure severity — 'info' \| 'warning' \| 'error'. Enum closure enforced by the `public.rules` CHECK constraint. Default: `error`
`rule_origin`optional	string	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`

dimensionsoptional object[]

fact_setoptional

FactSetLite

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

Field	Type	Description
`id`required	string
`structure_id`optional	string
`period_start`optional	string (date)
`period_end`required	string (date)
`factset_type`required	string	'report' \| 'schedule' \| 'custom' \| 'disclosure' \| 'metric'. Enum closure enforced by the `public.fact_sets` CHECK constraint.
`entity_id`required	string
`report_id`optional	string	Back-pointer to the parent row in `reports`. Null when the FactSet does not belong to a report package.
`scenario_id`optional	string	Scenario axis (the forecast engine). NULL = actuals; non-NULL names the owning forecast block whose parallel universe this set belongs to.
`provenance`optional	object	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_resultsoptional

VerificationResultLite[]

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

Field	Type	Description
`id`required	string
`rule_id`required	string
`structure_id`optional	string
`fact_set_id`optional	string
`status`required	string	'pass' \| 'fail' \| 'error' \| 'skipped'. Enum closure enforced by the `public.verification_results` CHECK constraint.
`message`optional	string
`period_start`optional	string (date)
`period_end`optional	string (date)
`evaluated_at`optional	string (date-time)

verification_summaryoptional

VerificationSummary

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

Field	Type	Description
`total`optional	integer	Default: `0`
`passed`optional	integer	Default: `0`
`failed`optional	integer	Default: `0`
`errored`optional	integer	Default: `0`
`skipped`optional	integer	Default: `0`
`by_category`optional	VerificationCategorySummary[]	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.

viewoptional

ViewProjections

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

Field	Type	Description
`rendering`optional	RenderingLite	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.
`chart`optional	ChartLite	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.

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

Authentication

Path parameters

Header parameters

Request body

block_type = schedule

block_type = rollforward

block_type = forecast

block_type = balance_sheet, cash_flow_statement, comprehensive_income, equity_statement, income_statement, metric, reconciliation, regulatory_disclosure

Example request

Responses

`block_type =` `schedule`

`block_type =` `rollforward`

`block_type =` `forecast`

`block_type =` `balance_sheet`, `cash_flow_statement`, `comprehensive_income`, `equity_statement`, `income_statement`, `metric`, `reconciliation`, `regulatory_disclosure`