API docs by Redocly

Ledger API (1.0.0)

Download OpenAPI specification:

URL: https://peteshepley.com License: Source

A small double-entry bookkeeping service: accounts, transactions, and the entries that belong to them. Entries are immutable and append-only — balances are always derived by summing entries, never stored and mutated directly. Every transaction's entries must sum to exactly zero (enforced both in application code and by a database constraint).

This API is meant to be called by other services/applications in this account, not by end users directly — see the awsSigv4 security scheme below.

Accounts

Asset, liability, income, and expense accounts.

Create an account

Authorizations:
awsSigv4
Request Body schema: application/json
required
name
required
string
type
required
string (AccountType)
Enum: "asset" "liability" "income" "expense"
currency
required
string

ISO 4217, e.g. USD. Single currency per account.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "asset",
  • "currency": "USD"
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "type": "asset",
  • "currency": "USD",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z"
}

List all accounts

Authorizations:
awsSigv4

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get an account

Authorizations:
awsSigv4
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "type": "asset",
  • "currency": "USD",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z"
}

List an account's entries

Paginated, most-recent-first by effective_date.

Authorizations:
awsSigv4
path Parameters
id
required
string <uuid>
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
offset
integer >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "limit": 0,
  • "offset": 0
}

Transactions

Immutable, zero-sum double-entry postings.

Post a transaction

Requires an idempotency_key. Posting the same key twice returns the original transaction unchanged with 200, rather than double-posting — safe to retry.

Authorizations:
awsSigv4
Request Body schema: application/json
required
idempotency_key
required
string
description
string
effective_date
string <date>

Defaults to today (UTC) if omitted.

required
Array of objects (EntryInput) >= 2 items

Amounts must sum to exactly zero.

Responses

Request samples

Content type
application/json
{
  • "idempotency_key": "string",
  • "description": "string",
  • "effective_date": "2019-08-24",
  • "entries": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "idempotency_key": "string",
  • "effective_date": "2019-08-24",
  • "created_at": "2019-08-24T14:15:22Z",
  • "entries": [
    ]
}

Get a transaction and its entries

Authorizations:
awsSigv4
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "description": "string",
  • "idempotency_key": "string",
  • "effective_date": "2019-08-24",
  • "created_at": "2019-08-24T14:15:22Z",
  • "entries": [
    ]
}

Balances

Derived balances, current or as of a given date.

Get an account's balance

Authorizations:
awsSigv4
path Parameters
id
required
string <uuid>
query Parameters
as_of
string <date>

Interpreted end-of-day inclusive (effective_date <= as_of). Omit for "now."

Responses

Response samples

Content type
application/json
{
  • "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
  • "as_of": "2019-08-24",
  • "balance": 0
}

List every account's balance

Authorizations:
awsSigv4
query Parameters
as_of
string <date>

Interpreted end-of-day inclusive (effective_date <= as_of). Omit for "now."

Responses

Response samples

Content type
application/json
{
  • "as_of": "2019-08-24",
  • "accounts": [
    ]
}