Outcome
Describe every dataset Books can export: its key, the route family and permission that serves it, the date parameters it takes, and every column with its type and meaning. The chart and journal datasets use the column names the importers read, so an export re-imports.
Before you start
- Verify the intended environment, authenticated identity and specifically approved organization context.
- The published application permission is ledger:read. Discover the exact granted canonical Books workspace and bind it separately from action input.
Discover the target
topolo whoami --json
topolo actions get app_topolo_books.exports.datasets.list --detail --json
topolo resources topolo-books --json
topolo workspaces list topolo-books --json
- Set BOOKS_WORKSPACE_ID to the exact granted workspace returned by discovery.
Request
GET /api/exports/datasets
Inspect and test this action. Save the reviewed input as payload.json; supply credential/resource context separately.
Input fields
Use an empty input object. Credential and resource context are separate.
Inspect nested fields and the complete input schema.
Effects
- Reads the dataset catalogue without touching data.
Interpret the response
Read $.datasets[].key for the returned export_dataset identifier. Empty collections and nullable fields do not discover a target.
No verification needed for a read.
Inspect the success schema. CLI/MCP add their own transport envelope; CLI --detail requests the full result.
Worked examples
Actual Books route handlers and the exported Worker were exercised against five local SQLite D1 concern databases with all committed migrations, the real posting Durable Object and local R2. Route captures use synthetic verified Auth; Worker captures use synthetic Auth transports. Nexus, Brand, Notify, Pay, Mercury and Xero responses are explicitly simulated at the provider transport boundary. Captures prove local request/response behavior and canonical SDK projection, not live bank access, payment movement, email delivery, provider eligibility, tax compliance, encrypted custody, scheduled execution, deployment or production completion. Fixture identities, credentials, addresses and records authorize no live operation.
Run a reviewed request
Save the input from the selected worked example as payload.json. Validate and inspect the plan before calling the action; refused examples demonstrate errors and are not instructions to execute.
CLI:
topolo actions validate app_topolo_books.exports.datasets.list --data @payload.json --json
topolo actions plan app_topolo_books.exports.datasets.list --resource-type workspace --resource-id "$BOOKS_WORKSPACE_ID" --data @payload.json --json
topolo actions call app_topolo_books.exports.datasets.list --resource-type workspace --resource-id "$BOOKS_WORKSPACE_ID" --data @payload.json --detail --json
MCP tool and arguments for the first successful example:
{
"tool": "topolo_read_action",
"arguments": {
"actionId": "app_topolo_books.exports.datasets.list",
"input": {},
"resourceType": "workspace",
"resourceId": "<exact granted workspace id>",
"detail": true
}
}
Refused response · auth_error
Input · payload.json:
{}
Captured response · HTTP 401
{
"error": "API key validation failed"
}
HTTP 401. SDK error code auth_error. Authenticate in the intended organization again. Verify whoami and the exact Books application/workspace binding before retrying; do not switch identity to work around a refusal.
Successful response · HTTP 200
Input · payload.json:
{}
Captured response · HTTP 200
{
"datasets": [
{
"key": "chart_of_accounts",
"title": "Chart of accounts",
"family": "ledger",
"parameters": [],
"description": "Every account, active and archived. Re-imports through accounts.import with the generic preset.",
"columns": [
{
"key": "code",
"title": "Code",
"type": "string",
"description": "Account code"
},
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Account name"
},
{
"key": "type",
"title": "Type",
"type": "string",
"description": "asset, liability, equity, income or expense"
},
{
"key": "subtype",
"title": "Subtype",
"type": "string",
"description": "Finer classification used by the statements"
},
{
"key": "description",
"title": "Description",
"type": "string",
"description": "Free text"
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "active or archived"
},
{
"key": "system_key",
"title": "System role",
"type": "string",
"description": "The ledger role the account plays, if any"
},
{
"key": "parent_code",
"title": "Parent code",
"type": "string",
"description": "Code of the parent account, if any"
}
],
"permission": "ledger:read"
},
{
"key": "tax_rates",
"title": "Tax rates",
"family": "ledger",
"parameters": [],
"description": "Tax rates with their codes, kinds and effective dates.",
"columns": [
{
"key": "code",
"title": "Code",
"type": "string",
"description": "Tax code"
},
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Display name"
},
{
"key": "jurisdiction",
"title": "Jurisdiction",
"type": "string",
"description": "Country or region code"
},
{
"key": "kind",
"title": "Kind",
"type": "string",
"description": "standard, reduced, zero, exempt, out_of_scope or reverse_charge"
},
{
"key": "rate",
"title": "Rate %",
"type": "number",
"description": "Percentage"
},
{
"key": "effective_from",
"title": "Effective from",
"type": "date",
"description": "First day the rate applies"
},
{
"key": "effective_to",
"title": "Effective to",
"type": "date",
"description": "Last day, blank while current"
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "active or archived"
}
],
"permission": "ledger:read"
},
{
"key": "periods",
"title": "Periods",
"family": "ledger",
"parameters": [],
"description": "Monthly accounting periods and their lock status.",
"columns": [
{
"key": "period_key",
"title": "Period",
"type": "string",
"description": "YYYY-MM"
},
{
"key": "start_date",
"title": "Start",
"type": "date",
"description": "First day"
},
{
"key": "end_date",
"title": "End",
"type": "date",
"description": "Last day"
},
{
"key": "fiscal_year",
"title": "Fiscal year",
"type": "number",
"description": "Named by the calendar year it ends in"
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "open, soft_locked or hard_locked"
},
{
"key": "lock_reason",
"title": "Lock reason",
"type": "string",
"description": "Why it was locked, if it was"
}
],
"permission": "ledger:read"
},
{
"key": "journals",
"title": "Journal lines",
"family": "ledger",
"parameters": [
"from",
"to"
],
"description": "Every ledger line in posting order, one row per line. Re-imports through journals.import: the journal, date, description, account_code, debit, credit, reference and memo columns are the ones it reads.",
"columns": [
{
"key": "journal",
"title": "Journal",
"type": "string",
"description": "Journal id, shared by the lines of one posting"
},
{
"key": "sequence",
"title": "Sequence",
"type": "number",
"description": "Gap-free posting number"
},
{
"key": "date",
"title": "Date",
"type": "date",
"description": "Posted on"
},
{
"key": "description",
"title": "Description",
"type": "string",
"description": "Journal description"
},
{
"key": "reference",
"title": "Reference",
"type": "string",
"description": "Journal reference"
},
{
"key": "journal_type",
"title": "Journal type",
"type": "string",
"description": "manual, opening_balance, year_end_close and so on"
},
{
"key": "event_type",
"title": "Event",
"type": "string",
"description": "journal_posted or journal_reversed"
},
{
"key": "line_no",
"title": "Line",
"type": "number",
"description": "Line number within the journal"
},
{
"key": "account_code",
"title": "Account code",
"type": "string",
"description": "Ledger account code"
},
{
"key": "account_name",
"title": "Account",
"type": "string",
"description": "Ledger account name"
},
{
"key": "debit",
"title": "Debit",
"type": "number",
"description": "Debit amount, in the currency column's major units"
},
{
"key": "credit",
"title": "Credit",
"type": "number",
"description": "Credit amount, in the currency column's major units"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Base currency"
},
{
"key": "memo",
"title": "Memo",
"type": "string",
"description": "Line memo"
},
{
"key": "dimensions",
"title": "Dimensions",
"type": "string",
"description": "JSON map of dimension key to value code"
},
{
"key": "contact_id",
"title": "Contact id",
"type": "string",
"description": "Contact the line belongs to, if any"
}
],
"permission": "ledger:read"
},
{
"key": "trial_balance",
"title": "Trial balance",
"family": "ledger",
"parameters": [
"asOf"
],
"description": "Every account with activity up to the date, debits against credits.",
"columns": [
{
"key": "code",
"title": "Code",
"type": "string",
"description": "Account code"
},
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Account name"
},
{
"key": "type",
"title": "Type",
"type": "string",
"description": "Account type"
},
{
"key": "debit",
"title": "Debit",
"type": "number",
"description": "Cumulative debits, in the currency column's major units"
},
{
"key": "credit",
"title": "Credit",
"type": "number",
"description": "Cumulative credits, in the currency column's major units"
},
{
"key": "balance",
"title": "Balance",
"type": "number",
"description": "Debit less credit, in the currency column's major units"
}
],
"permission": "ledger:read"
},
{
"key": "profit_and_loss",
"title": "Profit and loss",
"family": "ledger",
"parameters": [
"from",
"to"
],
"description": "The income statement for the range, one row per account plus the summary lines.",
"columns": [
{
"key": "section",
"title": "Section",
"type": "string",
"description": "revenue, cost_of_sales, operating_expenses, other_income, other_expenses, tax or summary"
},
{
"key": "code",
"title": "Code",
"type": "string",
"description": "Account code, blank on summary lines"
},
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Account or summary line"
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Natural-sign amount for the range, in the currency column's major units"
}
],
"permission": "ledger:read"
},
{
"key": "balance_sheet",
"title": "Balance sheet",
"family": "ledger",
"parameters": [
"asOf"
],
"description": "The position at the date, one row per account plus computed and summary lines.",
"columns": [
{
"key": "section",
"title": "Section",
"type": "string",
"description": "current_assets, non_current_assets, current_liabilities, non_current_liabilities, equity or summary"
},
{
"key": "code",
"title": "Code",
"type": "string",
"description": "Account code, blank on computed and summary lines"
},
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Account, computed or summary line"
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Natural-sign amount at the date, in the currency column's major units"
}
],
"permission": "ledger:read"
},
{
"key": "cash_flow",
"title": "Cash flow",
"family": "ledger",
"parameters": [
"from",
"to"
],
"description": "Cash generated and used in the range, split across operating, investing and financing activity, with the cash reconciliation.",
"columns": [
{
"key": "section",
"title": "Section",
"type": "string",
"description": "operating, investing, financing or summary"
},
{
"key": "code",
"title": "Code",
"type": "string",
"description": "Account code, blank on summary lines"
},
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Account or summary line"
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Cash movement for the range, in the currency column's major units"
}
],
"permission": "ledger:read"
},
{
"key": "contacts",
"title": "Contacts",
"family": "contacts",
"parameters": [],
"description": "Customers and suppliers with their details and defaults.",
"columns": [
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Contact name, unique among live contacts"
},
{
"key": "legal_name",
"title": "Legal name",
"type": "string",
"description": "Registered name"
},
{
"key": "is_customer",
"title": "Customer",
"type": "boolean",
"description": "Sells to them"
},
{
"key": "is_supplier",
"title": "Supplier",
"type": "boolean",
"description": "Buys from them"
},
{
"key": "email",
"title": "Email",
"type": "string",
"description": ""
},
{
"key": "phone",
"title": "Phone",
"type": "string",
"description": ""
},
{
"key": "website",
"title": "Website",
"type": "string",
"description": ""
},
{
"key": "tax_number",
"title": "Tax number",
"type": "string",
"description": "VAT or tax registration"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Default document currency"
},
{
"key": "payment_terms_days",
"title": "Payment terms (days)",
"type": "number",
"description": ""
},
{
"key": "address_line1",
"title": "Address 1",
"type": "string",
"description": ""
},
{
"key": "address_line2",
"title": "Address 2",
"type": "string",
"description": ""
},
{
"key": "city",
"title": "City",
"type": "string",
"description": ""
},
{
"key": "region",
"title": "Region",
"type": "string",
"description": ""
},
{
"key": "postal_code",
"title": "Postal code",
"type": "string",
"description": ""
},
{
"key": "country",
"title": "Country",
"type": "string",
"description": ""
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "active or archived"
}
],
"permission": "contacts:read"
},
{
"key": "invoices",
"title": "Invoices",
"family": "invoices",
"parameters": [
"from",
"to"
],
"description": "Every invoice issued in the range, one row per document with its totals and status.",
"columns": [
{
"key": "number",
"title": "Number",
"type": "string",
"description": "invoice number"
},
{
"key": "reference",
"title": "Reference",
"type": "string",
"description": ""
},
{
"key": "contact",
"title": "Contact",
"type": "string",
"description": "Contact name"
},
{
"key": "issue_date",
"title": "Issue date",
"type": "date",
"description": ""
},
{
"key": "due_date",
"title": "Due date",
"type": "date",
"description": ""
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "draft, awaiting_payment, paid or void"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
},
{
"key": "exchange_rate",
"title": "Exchange rate",
"type": "number",
"description": "To base currency, blank when the same"
},
{
"key": "subtotal",
"title": "Subtotal",
"type": "number",
"description": "Before tax, in the currency column's major units"
},
{
"key": "tax",
"title": "Tax",
"type": "number",
"description": "Tax total, in the currency column's major units"
},
{
"key": "total",
"title": "Total",
"type": "number",
"description": "Document total, in the currency column's major units"
},
{
"key": "paid",
"title": "Paid",
"type": "number",
"description": "Payments received, in the currency column's major units"
},
{
"key": "written_off",
"title": "Written off",
"type": "number",
"description": "Settled through bad debt or small-balance write-off, in the currency column's major units"
},
{
"key": "outstanding",
"title": "Outstanding",
"type": "number",
"description": "Total less paid and written off, in the currency column's major units"
},
{
"key": "notes",
"title": "Notes",
"type": "string",
"description": ""
},
{
"key": "source",
"title": "Source",
"type": "string",
"description": "manual, xero and so on"
}
],
"permission": "invoices:read"
},
{
"key": "invoice_lines",
"title": "Invoice lines",
"family": "invoices",
"parameters": [
"from",
"to"
],
"description": "Every line of every invoice issued in the range.",
"columns": [
{
"key": "number",
"title": "Number",
"type": "string",
"description": "invoice number"
},
{
"key": "issue_date",
"title": "Issue date",
"type": "date",
"description": ""
},
{
"key": "line_no",
"title": "Line",
"type": "number",
"description": ""
},
{
"key": "description",
"title": "Description",
"type": "string",
"description": ""
},
{
"key": "quantity",
"title": "Quantity",
"type": "number",
"description": ""
},
{
"key": "unit_amount",
"title": "Unit amount",
"type": "number",
"description": "Price per unit, in the currency column's major units"
},
{
"key": "account_code",
"title": "Account code",
"type": "string",
"description": "Ledger account the line posts to"
},
{
"key": "tax_code",
"title": "Tax code",
"type": "string",
"description": ""
},
{
"key": "tax",
"title": "Tax",
"type": "number",
"description": "Line tax, in the currency column's major units"
},
{
"key": "line_total",
"title": "Line total",
"type": "number",
"description": "Line total before tax, in the currency column's major units"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
}
],
"permission": "invoices:read"
},
{
"key": "invoice_payments",
"title": "Invoice payments",
"family": "invoices",
"parameters": [
"from",
"to"
],
"description": "Every payment recorded against a invoice in the range.",
"columns": [
{
"key": "number",
"title": "Number",
"type": "string",
"description": "invoice number"
},
{
"key": "paid_on",
"title": "Paid on",
"type": "date",
"description": ""
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Payment amount, in the currency column's major units"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": ""
},
{
"key": "reference",
"title": "Reference",
"type": "string",
"description": ""
},
{
"key": "bank_line_id",
"title": "Bank line",
"type": "string",
"description": "Statement line the payment was matched to, if any"
}
],
"permission": "invoices:read"
},
{
"key": "bills",
"title": "Bills",
"family": "bills",
"parameters": [
"from",
"to"
],
"description": "Every bill issued in the range, one row per document with its totals and status.",
"columns": [
{
"key": "number",
"title": "Number",
"type": "string",
"description": "bill number"
},
{
"key": "reference",
"title": "Reference",
"type": "string",
"description": ""
},
{
"key": "contact",
"title": "Contact",
"type": "string",
"description": "Contact name"
},
{
"key": "issue_date",
"title": "Issue date",
"type": "date",
"description": ""
},
{
"key": "due_date",
"title": "Due date",
"type": "date",
"description": ""
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "draft, awaiting_payment, paid or void"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
},
{
"key": "exchange_rate",
"title": "Exchange rate",
"type": "number",
"description": "To base currency, blank when the same"
},
{
"key": "subtotal",
"title": "Subtotal",
"type": "number",
"description": "Before tax, in the currency column's major units"
},
{
"key": "tax",
"title": "Tax",
"type": "number",
"description": "Tax total, in the currency column's major units"
},
{
"key": "total",
"title": "Total",
"type": "number",
"description": "Document total, in the currency column's major units"
},
{
"key": "paid",
"title": "Paid",
"type": "number",
"description": "Payments received, in the currency column's major units"
},
{
"key": "written_off",
"title": "Written off",
"type": "number",
"description": "Settled through bad debt or small-balance write-off, in the currency column's major units"
},
{
"key": "outstanding",
"title": "Outstanding",
"type": "number",
"description": "Total less paid and written off, in the currency column's major units"
},
{
"key": "notes",
"title": "Notes",
"type": "string",
"description": ""
},
{
"key": "source",
"title": "Source",
"type": "string",
"description": "manual, xero and so on"
}
],
"permission": "bills:read"
},
{
"key": "bill_lines",
"title": "Bill lines",
"family": "bills",
"parameters": [
"from",
"to"
],
"description": "Every line of every bill issued in the range.",
"columns": [
{
"key": "number",
"title": "Number",
"type": "string",
"description": "bill number"
},
{
"key": "issue_date",
"title": "Issue date",
"type": "date",
"description": ""
},
{
"key": "line_no",
"title": "Line",
"type": "number",
"description": ""
},
{
"key": "description",
"title": "Description",
"type": "string",
"description": ""
},
{
"key": "quantity",
"title": "Quantity",
"type": "number",
"description": ""
},
{
"key": "unit_amount",
"title": "Unit amount",
"type": "number",
"description": "Price per unit, in the currency column's major units"
},
{
"key": "account_code",
"title": "Account code",
"type": "string",
"description": "Ledger account the line posts to"
},
{
"key": "tax_code",
"title": "Tax code",
"type": "string",
"description": ""
},
{
"key": "tax",
"title": "Tax",
"type": "number",
"description": "Line tax, in the currency column's major units"
},
{
"key": "line_total",
"title": "Line total",
"type": "number",
"description": "Line total before tax, in the currency column's major units"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
}
],
"permission": "bills:read"
},
{
"key": "bill_payments",
"title": "Bill payments",
"family": "bills",
"parameters": [
"from",
"to"
],
"description": "Every payment recorded against a bill in the range.",
"columns": [
{
"key": "number",
"title": "Number",
"type": "string",
"description": "bill number"
},
{
"key": "paid_on",
"title": "Paid on",
"type": "date",
"description": ""
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Payment amount, in the currency column's major units"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": ""
},
{
"key": "reference",
"title": "Reference",
"type": "string",
"description": ""
},
{
"key": "bank_line_id",
"title": "Bank line",
"type": "string",
"description": "Statement line the payment was matched to, if any"
}
],
"permission": "bills:read"
},
{
"key": "aged_receivables",
"title": "Aged receivables",
"family": "invoices",
"parameters": [
"asOf"
],
"description": "Open customer balances at the date, one row per customer and aging bucket.",
"columns": [
{
"key": "contact",
"title": "Customer",
"type": "string",
"description": "Customer name"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
},
{
"key": "documents",
"title": "Documents",
"type": "number",
"description": "Open invoice count for the customer"
},
{
"key": "oldest_date",
"title": "Oldest due date",
"type": "date",
"description": "Oldest due or issue date in the balance"
},
{
"key": "bucket",
"title": "Aging bucket",
"type": "string",
"description": "Not yet due or overdue day range"
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Outstanding in this bucket, in the currency column's major units"
},
{
"key": "total",
"title": "Customer total",
"type": "number",
"description": "Total outstanding for the customer, in the currency column's major units"
}
],
"permission": "invoices:read"
},
{
"key": "sales_by_customer",
"title": "Sales by customer",
"family": "invoices",
"parameters": [
"from",
"to"
],
"description": "Issued invoice totals in the range, grouped by customer and currency.",
"columns": [
{
"key": "customer",
"title": "Customer",
"type": "string",
"description": "Customer name"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
},
{
"key": "documents",
"title": "Invoices",
"type": "number",
"description": "Issued invoice count"
},
{
"key": "subtotal",
"title": "Subtotal",
"type": "number",
"description": "Before tax, in the currency column's major units"
},
{
"key": "tax",
"title": "Tax",
"type": "number",
"description": "Tax total, in the currency column's major units"
},
{
"key": "total",
"title": "Total",
"type": "number",
"description": "Invoice total, in the currency column's major units"
},
{
"key": "paid",
"title": "Paid",
"type": "number",
"description": "Payments received, in the currency column's major units"
},
{
"key": "outstanding",
"title": "Outstanding",
"type": "number",
"description": "Amount still due, in the currency column's major units"
}
],
"permission": "invoices:read"
},
{
"key": "aged_payables",
"title": "Aged payables",
"family": "bills",
"parameters": [
"asOf"
],
"description": "Open supplier balances at the date, one row per supplier and aging bucket.",
"columns": [
{
"key": "contact",
"title": "Supplier",
"type": "string",
"description": "Supplier name"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
},
{
"key": "documents",
"title": "Documents",
"type": "number",
"description": "Open bill count for the supplier"
},
{
"key": "oldest_date",
"title": "Oldest due date",
"type": "date",
"description": "Oldest due or issue date in the balance"
},
{
"key": "bucket",
"title": "Aging bucket",
"type": "string",
"description": "Not yet due or overdue day range"
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Outstanding in this bucket, in the currency column's major units"
},
{
"key": "total",
"title": "Supplier total",
"type": "number",
"description": "Total outstanding for the supplier, in the currency column's major units"
}
],
"permission": "bills:read"
},
{
"key": "purchases_by_supplier",
"title": "Purchases by supplier",
"family": "bills",
"parameters": [
"from",
"to"
],
"description": "Issued bill totals in the range, grouped by supplier and currency.",
"columns": [
{
"key": "supplier",
"title": "Supplier",
"type": "string",
"description": "Supplier name"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Document currency"
},
{
"key": "documents",
"title": "Bills",
"type": "number",
"description": "Issued bill count"
},
{
"key": "subtotal",
"title": "Subtotal",
"type": "number",
"description": "Before tax, in the currency column's major units"
},
{
"key": "tax",
"title": "Tax",
"type": "number",
"description": "Tax total, in the currency column's major units"
},
{
"key": "total",
"title": "Total",
"type": "number",
"description": "Bill total, in the currency column's major units"
},
{
"key": "paid",
"title": "Paid",
"type": "number",
"description": "Payments made, in the currency column's major units"
},
{
"key": "outstanding",
"title": "Outstanding",
"type": "number",
"description": "Amount still owed, in the currency column's major units"
}
],
"permission": "bills:read"
},
{
"key": "bank_accounts",
"title": "Bank accounts",
"family": "bank",
"parameters": [],
"description": "Every bank, card and cash account Books knows, with the ledger account it maps to.",
"columns": [
{
"key": "name",
"title": "Name",
"type": "string",
"description": "Name from the bank"
},
{
"key": "nickname",
"title": "Nickname",
"type": "string",
"description": ""
},
{
"key": "provider",
"title": "Provider",
"type": "string",
"description": "mercury, manual, xero and so on"
},
{
"key": "kind",
"title": "Kind",
"type": "string",
"description": "checking, savings, card and so on"
},
{
"key": "account_number_last4",
"title": "Last 4",
"type": "string",
"description": ""
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": ""
},
{
"key": "current_balance",
"title": "Current balance",
"type": "number",
"description": "Latest balance the bank reported, in the currency column's major units"
},
{
"key": "balance_as_of",
"title": "Balance as of",
"type": "date",
"description": ""
},
{
"key": "ledger_account_code",
"title": "Ledger account",
"type": "string",
"description": "Code of the linked ledger account"
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "active, disconnected or archived"
}
],
"permission": "banking:read"
},
{
"key": "bank_lines",
"title": "Bank statement lines",
"family": "bank",
"parameters": [
"from",
"to"
],
"description": "Every statement line in the range. Money in is positive.",
"columns": [
{
"key": "bank_account",
"title": "Bank account",
"type": "string",
"description": "Account name"
},
{
"key": "posted_on",
"title": "Posted on",
"type": "date",
"description": ""
},
{
"key": "amount",
"title": "Amount",
"type": "number",
"description": "Signed: money in positive, in the currency column's major units"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": ""
},
{
"key": "description",
"title": "Description",
"type": "string",
"description": ""
},
{
"key": "counterparty",
"title": "Counterparty",
"type": "string",
"description": ""
},
{
"key": "memo",
"title": "Memo",
"type": "string",
"description": ""
},
{
"key": "match_status",
"title": "Match status",
"type": "string",
"description": "unmatched, matched or excluded"
},
{
"key": "provider_transaction_id",
"title": "Bank transaction id",
"type": "string",
"description": ""
}
],
"permission": "banking:read"
},
{
"key": "bank_summary",
"title": "Bank summary",
"family": "bank",
"parameters": [
"from",
"to"
],
"description": "Movement, unmatched amounts and latest balance for every bank, card and cash account.",
"columns": [
{
"key": "bank_account",
"title": "Bank account",
"type": "string",
"description": "Account nickname or provider name"
},
{
"key": "provider",
"title": "Provider",
"type": "string",
"description": "Connection provider"
},
{
"key": "status",
"title": "Status",
"type": "string",
"description": "Connection status"
},
{
"key": "currency",
"title": "Currency",
"type": "string",
"description": "Account currency"
},
{
"key": "ledger_account",
"title": "Ledger account",
"type": "string",
"description": "Linked account code and name"
},
{
"key": "lines",
"title": "Lines",
"type": "number",
"description": "Statement line count in the range"
},
{
"key": "money_in",
"title": "Money in",
"type": "number",
"description": "Incoming movement, in the currency column's major units"
},
{
"key": "money_out",
"title": "Money out",
"type": "number",
"description": "Outgoing movement, in the currency column's major units"
},
{
"key": "net",
"title": "Net movement",
"type": "number",
"description": "Money in less money out, in the currency column's major units"
},
{
"key": "unmatched_lines",
"title": "Unmatched lines",
"type": "number",
"description": "Lines still to reconcile"
},
{
"key": "unmatched_amount",
"title": "Unmatched amount",
"type": "number",
"description": "Absolute unmatched value, in the currency column's major units"
},
{
"key": "current_balance",
"title": "Current balance",
"type": "number",
"description": "Latest provider balance, in the currency column's major units"
},
{
"key": "balance_as_of",
"title": "Balance as of",
"type": "date",
"description": "Date of the latest provider balance"
}
],
"permission": "banking:read"
}
]
}
HTTP 200. No verification needed for a read.
Verify the result
- No verification needed for a read.
Errors and recovery
auth_error(HTTP 401): Authenticate in the intended organization again. Verify whoami and the exact Books application/workspace binding before retrying; do not switch identity to work around a refusal.
These are observed local refusals. Shared authentication, schema validation and resource authorization can also refuse before the route. Preserve the actual error, details and request id.
Recovery boundary
Repeat a read in the same authorized context; no state is changed.
Related actions
- Export a ledger dataset: Rows of one ledger dataset: chart_of_accounts, tax_rates, periods, journals (from/to), trial_balance (asOf), profit_and_loss, cash_flow (from/to) or balance_sheet (asOf). Flat rows with account codes and names, decimal amounts in the base currency, the columns exports.datasets.list documents. The whole set, never paged.
- Export an invoice dataset: Rows of invoices, invoice_lines, invoice_payments, aged_receivables (asOf) or sales_by_customer (from/to), with stable documented columns.
Evidence
Actual Books route handlers and the exported Worker were exercised against five local SQLite D1 concern databases with all committed migrations, the real posting Durable Object and local R2. Route captures use synthetic verified Auth; Worker captures use synthetic Auth transports. Nexus, Brand, Notify, Pay, Mercury and Xero responses are explicitly simulated at the provider transport boundary. Captures prove local request/response behavior and canonical SDK projection, not live bank access, payment movement, email delivery, provider eligibility, tax compliance, encrypted custody, scheduled execution, deployment or production completion. Fixture identities, credentials, addresses and records authorize no live operation.