--- title: "Promote a mirror ledger" method: POST path: "/v3/{ledgerName}/promote" tags: ["Ledgers"] --- # Promote a mirror ledger `POST /v3/{ledgerName}/promote` ## Request - Base URL: `http://localhost:9000` - URL: `http://localhost:9000/v3/{ledgerName}/promote` - Auth: one of: - HTTP bearer - none Promotes a mirror-mode ledger to normal mode. After promotion, the mirror sync worker is stopped and the ledger accepts direct write operations. Requires `ledger:write` scope. ## Path parameters - `ledgerName` string, required ## Response `201` Ledger promoted successfully - PromoteLedgerResponse - `data` LedgerInfo, required - `name` string, required: Name of the ledger - `createdAt` string, date-time - `deletedAt` string, date-time: Soft deletion timestamp; omitted for active ledgers - `metadata` object: Enriched typed ledger metadata - `metadataSchema` LedgerMetadataSchema - `accountFields` object - `transactionFields` object - `ledgerFields` object - `mode` 'NORMAL' | 'MIRROR', required: Ledger mode, including the default NORMAL value - `mirrorSource` union: Detached credential-safe mirror configuration returned by ledger reads - object - `ledgerName` string, required - `batchSize` integer - `rewriteRules` MirrorRewriteRuleRead[] - `createdTransaction` CreatedTransactionRuleRead: Rule scoped to MirrorCreatedTransaction. Inside `match`, `log` is the created-transaction proto directly (e.g. `log.metadata["k"]`). - `match` string - `actions` CreatedTransactionActionRead[] - … - `revertedTransaction` RevertedTransactionRuleRead - `match` string - `actions` RevertedTransactionActionRead[] - … - `savedMetadata` SavedMetadataRuleRead - `match` string - `actions` SavedMetadataActionRead[] - … - `deletedMetadata` DeletedMetadataRuleRead - `match` string - `actions` DeletedMetadataActionRead[] - … - `anyVariant` AnyVariantRuleRead: Rule scoped to every variant. `log` is the full MirrorLogEntry — use `has(log.)` guards to read variant-specific fields. - `match` string - `actions` AnyVariantActionRead[] - … - `stop` boolean - `http` HttpMirrorSourceRead, required - `baseUrl` string: Source URL with userinfo (including passwordless tokens) and query credentials masked - `oauth2ClientCredentials` MirrorOAuthRead - `clientId` string - `clientSecret` '[redacted]': Presence marker only; reusable secret material is never returned - `tokenEndpoint` string: OAuth endpoint URL with userinfo (including passwordless tokens) and query credentials masked - `scopes` string[] - `postgres` PostgresMirrorSourceRead - `dsn` string: Connection string with password material masked; malformed values are fully redacted - `awsIamAuth` MirrorAwsIamAuthRead - `region` string - `assumeRoleArn` string - object - `ledgerName` string, required - `batchSize` integer - `rewriteRules` MirrorRewriteRuleRead[] - `createdTransaction` CreatedTransactionRuleRead: Rule scoped to MirrorCreatedTransaction. Inside `match`, `log` is the created-transaction proto directly (e.g. `log.metadata["k"]`). - `match` string - `actions` CreatedTransactionActionRead[] - … - `revertedTransaction` RevertedTransactionRuleRead - `match` string - `actions` RevertedTransactionActionRead[] - … - `savedMetadata` SavedMetadataRuleRead - `match` string - `actions` SavedMetadataActionRead[] - … - `deletedMetadata` DeletedMetadataRuleRead - `match` string - `actions` DeletedMetadataActionRead[] - … - `anyVariant` AnyVariantRuleRead: Rule scoped to every variant. `log` is the full MirrorLogEntry — use `has(log.)` guards to read variant-specific fields. - `match` string - `actions` AnyVariantActionRead[] - … - `stop` boolean - `http` HttpMirrorSourceRead - `baseUrl` string: Source URL with userinfo (including passwordless tokens) and query credentials masked - `oauth2ClientCredentials` MirrorOAuthRead - `clientId` string - `clientSecret` '[redacted]': Presence marker only; reusable secret material is never returned - `tokenEndpoint` string: OAuth endpoint URL with userinfo (including passwordless tokens) and query credentials masked - `scopes` string[] - `postgres` PostgresMirrorSourceRead, required - `dsn` string: Connection string with password material masked; malformed values are fully redacted - `awsIamAuth` MirrorAwsIamAuthRead - `region` string - `assumeRoleArn` string - `mirrorSyncProgress` MirrorSyncProgress: Sync progress for MIRROR ledgers (populated at read time) - `state` 'SYNCING' | 'FOLLOWING', required: Current sync state (SYNCING = catching up, FOLLOWING = up to date) - `cursor` string, bigint, required: Last ingested v2 log ID - `sourceLogCount` string, bigint, required: Latest known log ID in the v2 source - `remainingLogs` string, bigint, required: Number of remaining logs to sync (sourceLogCount - cursor) - `error` MirrorSyncError: Most recent mirror sync error (null if healthy) - `message` string: Error message - `occurredAt` string, date-time: When the error occurred - `accountTypes` object - `defaultEnforcementMode` 'STRICT' | 'AUDIT', required: Default enforcement for unmatched accounts; defaults to STRICT ## Other responses - `400`: The request is invalid, or the ledger is not in mirror mode (`LEDGER_NOT_IN_MIRROR_MODE`). - `401`: Authentication required (missing or invalid JWT token) - `403`: Insufficient permissions (missing required scope) - `404`: Not found - `405`: Method not allowed - `409`: The ledger has been deleted (`LEDGER_DELETED`). - `429`: Resource exhausted. Write admission can reject with `WRITES_BLOCKED_DISK_FULL` while disk pressure blocks writes; `SEQUENCE_EXHAUSTED` means an authoritative identifier allocator cannot allocate another identifier and is permanent for that allocator. Inspect `errorCode` before deciding whether to retry. No retry interval is supplied, and retrying cannot resolve sequence exhaustion. - `500`: Internal server error - `503`: Service unavailable — the server cannot serve the request right now but an immediate retry can succeed. The `errorCode` field discriminates the cause: `NO_LEADER` (no elected Raft leader), `CACHE_HORIZON_EXCEEDED` (admission snapshot too old, retry against a fresh one), `UNAVAILABLE` (an internal forwarded stream was torn down mid-transfer), or the reason of any domain error of the unavailable kind (e.g. `INDEX_BUILDING`). ## Changes - **2026-11-03** `f5e817eca038`: 1 info - api operation id `promoteLedger` removed and replaced with `v3PromoteLedger` - **2026-10-09** `45c54ddbb457`: 7 warning, 9 info - removed the optional property `data/account_types` from the response with the `201` status - removed the optional property `data/created_at` from the response with the `201` status - removed the optional property `data/default_enforcement_mode` from the response with the `201` status - removed the optional property `data/deleted_at` from the response with the `201` status - …12 more - **2026-10-08** `3da23d327316`: 3 info - added the media type `text/plain` for the response with the status `401` - added the media type `text/plain` for the response with the status `403` - added the non-success response with the status `429` - **2026-09-30** `b747efd5cd77`: 1 info - endpoint added - **2026-09-29** `6ff73ac9a6bd`: 1 breaking - api path removed without deprecation [Operation history](https://skmtc.dev/formancehq/apis/ledger-api/changes/v3/:ledgerName/promote/post.md) --- [API](https://skmtc.dev/formancehq/apis/ledger-api.md) - [All operations](https://skmtc.dev/formancehq/apis/ledger-api/llms.txt) - [OpenAPI document](https://skmtc.dev/formancehq/apis/ledger-api/revisions/f5e817eca038?raw)