Initialize Ledger

post/extensions/roboledger/{graph_id}/operations/initialize

One-time setup: creates the fiscal calendar and seeds periods. Returns 409 if already initialized, or if draft entries or unposted events are dated before the first open month, where no close would post them.

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.

Field	Type	Description
`entity_id`optional	string	The entity whose books this acts on, by id. Omit for the group parent — the single-entity default.
`closed_through`optional	string	YYYY-MM period. Periods ≤ this date are treated as historical (already closed before the user joined). Set to null for a fresh business with no prior close state. Constraints: matches `^\d{4}-(0[1-9]\|1[0-2])$`
`fiscal_year_start_month`optional	integer	Fiscal year start month (1-12). Defaults to calendar year. Default: `1` Constraints: 1–12
`auto_seed_schedules`optional	boolean	If true, run the SchedulerAgent to create schedules from historical BS activity. NOT YET IMPLEMENTED — returns a warning in v1. Default: `false`
`earliest_data_period`optional	string	YYYY-MM period representing the earliest month that has transaction data. Used to create FiscalPeriod rows. Defaults to 24 months before the current month. Constraints: matches `^\d{4}-(0[1-9]\|1[0-2])$`
`note`optional	string	Free-form note attached to the audit event

Example request

curl · example 1 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/initialize" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "fiscal_year_start_month": 1
}'

curl · example 2 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/initialize" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "closed_through": "2025-12",
  "earliest_data_period": "2024-01",
  "fiscal_year_start_month": 1,
  "note": "Migrating from QuickBooks; 2025 already closed there."
}'

curl · example 3 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/initialize" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "closed_through": "2026-03",
  "fiscal_year_start_month": 7,
  "note": "FY runs July–June."
}'

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

InitializeLedgerResponse

Command-specific result payload

InitializeLedgerResponse fields

Field Type Description

fiscal_calendarrequired

FiscalCalendarResponse

Current fiscal calendar state for one entity of a graph.

FiscalCalendarResponse fields

Field	Type	Description
`graph_id`required	string
`entity_id`optional	string	The entity whose calendar this is.
`fiscal_year_start_month`required	integer
`closed_through`optional	string	Latest closed period (YYYY-MM), or null if nothing closed
`close_target`optional	string	Target period the user wants closed through (YYYY-MM)
`gap_periods`optional	integer	Number of periods between closed_through and close_target (inclusive of close_target). 0 means caught up. Default: `0`
`catch_up_sequence`optional	string[]	Ordered list of periods that a close run would process
`closeable_now`optional	boolean	Whether the next period in the catch-up sequence passes all closeable gates Default: `false`
`blockers`optional	string[]	Structured blocker codes when closeable_now is False: 'sequence_violation', 'period_incomplete', 'sync_stale', 'calendar_not_initialized', 'period_already_closed', 'pending_obligations', 'stranded_obligations', 'reconciling_items', 'unposted_source_events', 'unreconciled_accounts', 'unmapped_accounts', 'held_bank_lines'; on the consolidation entity, whose close is the group's, also 'entity_open', 'adjustments_unposted', 'residual_unexplained', 'consolidated_does_not_foot'
`pending_obligation_count`optional	integer	Number of pending schedule_entry_due events blocking close. Non-zero only when `pending_obligations` is in `blockers`. Default: `0`
`pending_obligation_sample`optional	PendingObligationDetailResponse[]	Sample of up to 5 pending obligations (schedule_id, schedule_name, period, event_id) ordered by occurred_at. Use `list-event-blocks` with event_type=schedule_entry_due&status=pending for the full set.
`earliest_pending_period`optional	string	Earliest period (YYYY-MM) with a pending obligation blocking close. Null when no pending_obligations blocker is active.
`sync_stale_days`optional	integer	Days the most recent sync is stale relative to the period to close. Populated only when `sync_stale` is in `blockers` and last_sync_at exists (null when there's a connection but no sync has ever run).
`stranded_obligation_count`optional	integer	Matured schedule_entry_due events already at 'classified' with no drafted closing entry for their (schedule, period) — adjusting entries a close would silently omit. Resolve by running promote-obligations with dispatch_handlers=true (which reaches them) or voiding the obligation. Default: `0`
`stranded_obligation_sample`optional	PendingObligationDetailResponse[]	Sample of up to 5 stranded obligations (schedule_id, schedule_name, period, event_id) ordered by occurred_at.
`reconciling_item_count`optional	integer	Posted events in or before this period whose source payload changed afterwards and that nobody has dispositioned — differences between the books and the source system. Resolve each with resolve-reconciling-item, or close over them knowingly with allow_reconciling_items. Default: `0`
`reconciling_item_sample`optional	string[]	Source identifiers (or event ids) of up to 5 unresolved reconciling items, so the blocker names what is holding the close.
`unposted_source_event_count`optional	integer	Source events dated in this period that were never committed: bank-feed lines still captured or classified, and QuickBooks transactions whose automatic posting failed. Commit or void each, or close over them knowingly with allow_unposted_source_events. Default: `0`
`unposted_source_event_sample`optional	string[]	Source identifiers (or event ids) of up to 5 unposted source events, so the blocker names what is holding the close.
`held_bank_line_count`optional	integer	Bank lines a sync held out of an earlier, closed month — dated there, arriving after it closed — that no close has decided on. They block the next close: reopen the month they are dated in, which gives them back to post, or close over them knowingly with allow_held_bank_lines. Listed by list-event-blocks with status='voided' and void_reason 'feed_in_closed_month'. Default: `0`
`held_bank_line_sample`optional	string[]	Up to 5 held lines, oldest first, as 'date: description amount [event id]', so the blocker names what is holding the close.
`unreconciled_account_count`optional	integer	Reconciliations the close waits on that are not reconciled for this period, including any never compared for it. Run refresh-reconciliations and clear what it reports, release one with set-reconciliation-policy, or close over them knowingly with allow_unreconciled_accounts. Default: `0`
`unreconciled_account_sample`optional	string[]	Name and status of up to 5 of those reconciliations, so the blocker names what is holding the close.
`unmapped_account_count`optional	integer	Accounts in this entity's chart with postings through the period that its mapping does not map to a reporting concept. Their balances are in no statement, so the month cannot be stated until each is mapped: suggest-mapping, then create-mapping-association. No override lifts it. Default: `0`
`unmapped_account_sample`optional	string[]	Code and name of up to 5 of those accounts, so the blocker names what is holding the close.
`group_open_entities`optional	string[]	The group close: the entities the month consolidates, the parent and its equity-method members included, that have not closed it. Close each first.
`group_pending_adjustments`optional	string[]	The group close: the consolidating entries the consolidation entity neither holds nor has drafted, by kind and member, or what the engine left out and why. Run propose-consolidation-entries.
`group_unexplained`optional	string[]	The group close: residuals and intercompany disagreements left unexplained. Correct the books or post the explaining entry, or close over them knowingly with allow_unexplained_residuals.
`group_not_footing`optional	string[]	The group close: the consolidated balance sheet's and equity statement's validation failures for the month.
`last_close_at`optional	string (date-time)
`initialized_at`optional	string (date-time)
`last_sync_at`optional	string (date-time)	Most recent QB sync timestamp (if connected)
`periods`optional	FiscalPeriodSummary[]	Fiscal period rows for this graph

periods_createdoptional

integer

Number of FiscalPeriod rows created by initialization

Default: 0

warningsoptional

string[]

Non-fatal warnings (e.g., auto_seed_schedules not implemented)

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