RoboLedger: Setup

Initialize Ledger

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.

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

Request

  • Base URL: https://api.robosystems.ai (the document declares no server; this is the origin it was published from)
  • URL: https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/initialize
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

graph_idstring required

Headers

Idempotency-Keystring nullable

Request body

entity_idstring nullable

The entity whose books this acts on, by id. Omit for the group parent — the single-entity default.

closed_throughstring nullable

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_monthinteger

Fiscal year start month (1-12). Defaults to calendar year.

auto_seed_schedulesboolean

If true, run the SchedulerAgent to create schedules from historical BS activity. NOT YET IMPLEMENTED — returns a warning in v1.

earliest_data_periodstring nullable

YYYY-MM period representing the earliest month that has transaction data. Used to create FiscalPeriod rows. Defaults to 24 months before the current month.

notestring nullable

Free-form note attached to the audit event

Example request

{
  "fiscal_year_start_month": 1
}

Response

Successful Response

operationstring required

Kebab-case operation name

operationIdstring required

op_-prefixed ULID for audit and SSE correlation

status'completed' | 'pending' | 'failed' required

Operation lifecycle state

atstring required

ISO-8601 UTC timestamp

createdBystring nullable

User ID that initiated the operation

idempotentReplayboolean

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

Changes

No recorded changes to this operation across all 1 revision of this API.