Retainers API

The retainer balance API is read-only. Owners/Administrators and Managers with invoice-view authority may use normal full-access API credentials. Personal read-only sync, scoped automation and MCP connector credentials do not gain retainer access.

Method	Endpoint	Purpose
GET	/api/v2/retainers	Paginated current retainers and computed ledger balances
GET	/api/v2/retainers/{retainerId}	One visible retainer and its balance

Query a period cutoff

curl --fail-with-body 'https://app.keito-test.com/api/v2/retainers?as_of=2026-10-31&per_page=100' \
  -H "Authorization: Bearer $KEITO_API_KEY" \
  -H "Keito-Account-Id: $KEITO_ACCOUNT_ID"

Collection filters are client_id, current status (ACTIVE or ARCHIVED), as_of, page and per_page (1–2000, default 100). The item endpoint accepts only as_of. Unknown, repeated or invalid date parameters return 400.

as_of is an inclusive UTC activity calendar date, not a snapshot of what was known at that moment. Late-entered activities dated on or before it count; currently voided activities do not. Without a cutoff, all current nonvoided activity dates count, including future dates. Retainer status and metadata are current regardless of the cutoff. Imported history may be incomplete.

Amounts are exact decimal strings in each retainer’s currency. Keep their precision and never add different currencies into a single amount. Each response is consistent, but separate pages do not form an immutable snapshot; follow every page and avoid concurrent ledger changes when collecting a month-end report.

These endpoints do not create, fund, draw from, archive or change retainers. The Workspace Backup API remains available to Owners/Administrators for raw records and activity. Consult OpenAPI for the precise balance response.