Skip to content
BookendBookend Docs

Generate a signed usage report

POST
/v1/metering/usage-report
curl --request POST \
  --url http://localhost:8080/v1/metering/usage-report

Air-gapped path: builds the usage payload for a quarter (quarter like 2026Q3; default the current quarter), signs its canonical JSON with the install’s RS256 key and stores it for manual delivery. Administrators only. 400 for a malformed quarter.

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
quarter
string

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
id
required
string format: uuid
deliveryMode
required
string
period
required

month for heartbeats (month-to-date), quarter for the air-gapped usage report.

object
kind
required
string
start
required
string format: date
end
required
string format: date
closedLoanCount
required
integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
documentPageCount
required
integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
payload
required

What leaves the bank: install id, version, the period, two integers (closed loans, document pages), coarse health, and the license key for Bookend’s receiver to validate. Never loan data. The wire names are the documented snake_case ones on every surface (heartbeat, signed report, REST) so the payload viewer shows exactly what is sent.

object
install_id
required
string
version
required
string
period
required

month for heartbeats (month-to-date), quarter for the air-gapped usage report.

object
kind
required
string
start
required
string format: date
end
required
string format: date
closed_loan_count
required
integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
document_page_count
required
integer | string format: int32
/^-?(?:0|[1-9]\d*)$/
health
required

Coarse component status words (ok / degraded / unknown); no hostnames, no counts beyond the metered one.

object
database
required
string
inference
required
string
core
required
string
evidence
required
string
license_key
required
null | string
generated_at
required
string format: date-time
signature
required
null | string
signatureKeyId
required
null | string
deliveredAt
required
null | string format: date-time
generatedAt
required
string format: date-time
Examplegenerated
{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "deliveryMode": "example",
  "period": {
    "kind": "example",
    "start": "2026-04-15",
    "end": "2026-04-15"
  },
  "closedLoanCount": 1,
  "documentPageCount": 1,
  "payload": {
    "install_id": "example",
    "version": "example",
    "period": {
      "kind": "example",
      "start": "2026-04-15",
      "end": "2026-04-15"
    },
    "closed_loan_count": 1,
    "document_page_count": 1,
    "health": {
      "database": "example",
      "inference": "example",
      "core": "example",
      "evidence": "example"
    },
    "license_key": "example",
    "generated_at": "2026-04-15T12:00:00Z"
  },
  "signature": "example",
  "signatureKeyId": "example",
  "deliveredAt": "2026-04-15T12:00:00Z",
  "generatedAt": "2026-04-15T12:00:00Z"
}