FOformancehq
Ledgers

Create a new ledger

Changed on

Creates a new ledger with the specified name. Storage is configured at the server level. Each ledger has its own Raft group for data consistency. Requires ledger:write scope.

The ledger name _ is reserved: all system / non-ledger routes live under the /v3/_/… segment (e.g. /v3/_/audit-entries), so a ledger named _ would be unreachable over REST. Creating it is rejected with a validation error. The exact name _system is also reserved for system events and rejected. Other underscore-prefixed names remain valid.

post/v3/{ledgerName}

Request

  • Base URL
    http://localhost:9000
  • URL
    http://localhost:9000/v3/{ledgerName}
  • Auth
    • HTTP bearer
    • or none

Path parameters

ledgerNamestring required

Name of the ledger

Headers

Idempotency-Keystring

Idempotency key for the request

Request body

metadataobject

Initial typed metadata, persisted atomically with creation in NORMAL and MIRROR modes. Creation requires ledger:WriteLedger, including initial metadata; later metadata saves require ledger:WriteMetadata. JSON null entries are omitted. Schema declarations govern indexing and queries, not write-time value coercion. Cluster policy defaults allow 128 entries per entity, 256 bytes per key, 16384 bytes per value, 65536 bytes per entity, and 1048576 bytes per request. Effective ceilings are configurable through the replicated cluster policy.

mode'NORMAL' | 'MIRROR'

Ledger mode. MIRROR creates a read-only ledger that syncs from an external v2 source. Values are case-sensitive; any other value is rejected with 400 INVALID_REQUEST.

defaultEnforcementMode'STRICT' | 'AUDIT'

Default chart-of-accounts enforcement for accounts that match no account type.

accountTypesobject

Initial account types (name -> account type definition).

Response

Ledger created successfully

Changes

  • f5e817eca038Revision changes
    • info

      api operation id createLedger removed and replaced with v3CreateLedger

  • 45c54ddbb457Revision changes
    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • warning

      removed the optional property / from the response with the status

    • info

      the request property /// became nullable

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      the response property / became required for the status

    • info

      added the required property / to the response with the status