Initialize Ledger

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

One-time setup: creates the fiscal calendar and seeds periods. Returns 409 if already initialized.

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.

Field	Type	Description
`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.
`fiscal_year_start_month`optional	integer	Fiscal year start month (1-12). Defaults to calendar year. Default: `1`
`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.
`note`optional	string	Free-form note attached to the audit event

Example request

curl

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

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 a graph.

FiscalCalendarResponse fields

Field	Type	Description
`graph_id`required	string
`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'
`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.
`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 (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