Backfill Plan History

post/extensions/roboledger/{graph_id}/operations/backfill-plan-history

Compile monthly statement history behind the close boundary — the plan's historical columns. Seeds any missing FiscalPeriod rows (baseline-closed) back to the clamped start_period, then restamps each month lacking canonical statement FactSets by running the real reopen → reclose cycle (balance validation, statement rules, and audit events per month). Chunked: at most max_periods months per call, oldest first — loop until remaining_periods comes back empty. Idempotent: already-stamped months are never touched. Months holding draft entries are skipped, never posted. start_period is clamped to the earliest month with ledger data, so deep-history tenants only backfill what actually exists. Runs on the background worker, since a chunk recloses up to 24 months: returns a pending envelope at once, and the result — the outcome per month and remaining_periods, or a refusal under error — arrives on /v1/operations/{operation_id}/stream.

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.
`start_period`optional	string	YYYY-MM period to backfill from. Clamped to the earliest month with ledger data; defaults to that month when omitted. Must be on or before `closed_through`. Constraints: matches `^\d{4}-(0[1-9]\|1[0-2])$`
`max_periods`optional	integer	Maximum months to restamp in this call. Each month runs a full reopen → reclose cycle; keep chunks modest and loop on `remaining_periods`. Default: `12` Constraints: 1–24
`allow_stale_sync`optional	boolean	Override the sync-currency gate on each reclose. Historical months predate the last sync in the normal case, so this is rarely needed. Default: `false`
`allow_stranded_obligations`optional	boolean	Override the stranded-obligation gate on each reclose. Only needed when a matured classified obligation without a drafted entry exists inside the backfill window and you have decided not to draft or void it first. Default: `false`
`allow_reconciling_items`optional	boolean	Override the reconciling-item gate on each reclose. Only needed when an event inside the backfill window is still flagged as changed upstream and you have decided not to resolve it first. Default: `false`
`allow_unposted_source_events`optional	boolean	Override the unposted-source-event gate on each reclose. Only needed when a source event inside the backfill window was never committed and you have decided not to commit or void it first. Default: `false`
`allow_unreconciled_accounts`optional	boolean	Override the reconciliation gate on each reclose. Needed when a month inside the backfill window has a reconciliation the close waits on that was never compared for it, which is every month closed before the reconciliation existed. Default: `false`
`allow_unexplained_residuals`optional	boolean	Override the group close's residual gate on each reclose of the consolidation entity's months. Default: `false`
`restamp`optional	boolean	Also re-derive months that ALREADY have canonical statement sets (default: skip them). Use after an engine improvement changes what a stamp produces — each month reruns the full reopen → reclose cycle and replaces its sets. A restamp run is not self-resuming (every month in range stays a candidate); advance `start_period` between chunks. Default: `false`
`note`optional	string	Free-form note attached to each close audit event

Example request

curl · example 1 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/backfill-plan-history" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>"

curl · example 2 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/backfill-plan-history" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "max_periods": 12,
  "start_period": "2019-07"
}'

curl · example 3 of 3

curl -X POST "https://api.robosystems.ai/extensions/roboledger/{graph_id}/operations/backfill-plan-history" \
  -H "X-API-Key: $ROBOSYSTEMS_API_KEY" \
  -H "Idempotency-Key: <Idempotency-Key>" \
  -H "Content-Type: application/json" \
  -d '{
  "max_periods": 12,
  "restamp": true,
  "start_period": "2024-08"
}'

Responses

202 Successful Response

Field	Type	Description
`operation`required	string	Kebab-case operation name
`operationId`required	string	op_-prefixed ULID for audit and SSE correlation
`status`required	string	Operation lifecycle state One of: `completed`, `pending`, `failed`
`result`optional	any	Command-specific result payload
`at`required	string	ISO-8601 UTC timestamp
`createdBy`optional	string	User ID that initiated the operation
`idempotentReplay`optional	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