Create Information Block

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

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

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.

Example request

curl

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 '"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

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	any

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. Seattle Method) 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's facts were constructed. 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 (Charlie's six type-of View arms). ``view.rendering`` carries pre-computed rows + periods + validation for blocks where rendering is deterministic (the statement family today). Other projections come online as their backend support lands — 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 (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