Liveness probe
GET /public/v1/health
Returns `{ ok: true, ts: <epoch ms> }`. Still behind the bearer token — there is no anonymous endpoint on this gateway. Excluded from AI-credit metering. DECLARED FIELD-CONTRACT GAP: this route is listed in `UNCONTRACTED_ROUTE_PREFIXES` in `middlewares/publicApiSerialize.middleware.js`. The response field allowlist does not apply to it; only the deny-key floor does. It is named here rather than omitted.
OAuth 2.0; company authorization and operation scopes required
Request example
curl --request GET 'https://sandboxapi.hellobooks.ai/public/v1/health' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' Replace tenant/path placeholders and prepare request.json from the published request schema when needed.
Complete published contract
{
"operationId": "healthCheck",
"summary": "Liveness probe",
"description": "Returns `{ ok: true, ts: <epoch ms> }`. Still behind the bearer token — there is no anonymous endpoint on this gateway. Excluded from AI-credit metering.\n\nDECLARED FIELD-CONTRACT GAP: this route is listed in `UNCONTRACTED_ROUTE_PREFIXES` in `middlewares/publicApiSerialize.middleware.js`. The response field allowlist does not apply to it; only the deny-key floor does. It is named here rather than omitted.",
"tags": [
"service"
],
"security": [
{
"marketplaceOAuth2": []
}
],
"responses": {
"200": {
"description": "Success.",
"headers": {
"RateLimit": {
"description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"ts": {
"type": "integer"
}
},
"required": [
"ok",
"ts"
],
"additionalProperties": false
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"402": {
"$ref": "#/components/responses/PaymentRequired"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"429": {
"$ref": "#/components/responses/RateLimited"
},
"500": {
"$ref": "#/components/responses/ServerError"
},
"503": {
"$ref": "#/components/responses/ServiceUnavailable"
}
},
"x-hellobooks-source": "hand-written",
"x-hellobooks-field-contract": "declared-gap",
"x-hellobooks-tenant-guard": false,
"x-hellobooks-required-scopes": [],
"x-hellobooks-scope-grain": "unguarded",
"parameters": [],
"referenceUrl": "https://agents.hellobooks.ai/api/developer-reference.json",
"scopeRule": "OpenAPI security array entries are alternatives (OR); scopes inside one security requirement are cumulative (AND).",
"environment": "Use the developer portal for sandbox setup and production access. API metadata does not prove a deployed operation is available.",
"components": {
"responses": {
"Unauthorized": {
"description": "Missing, malformed, expired or revoked bearer token, or a disabled client.",
"headers": {
"RateLimit": {
"description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GatewayError"
},
"examples": {
"invalid_token": {
"value": {
"error": "invalid_token",
"message": "Token invalid or expired."
}
},
"invalid_client": {
"value": {
"error": "invalid_client",
"message": "Client disabled."
}
}
}
}
}
},
"PaymentRequired": {
"description": "The tenant's AI-credit wallet cannot cover this request. Charged before any tenant work; the deduction settles only on a <400 response.",
"headers": {
"RateLimit": {
"description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AiCreditsError"
}
}
}
},
"Forbidden": {
"description": "Denied. THREE different bodies land on this status: the token is not bound to the org/entity in the path (`tenant_scope_violation`), the token lacks the scope the route requires (`insufficient_scope`), or the organisation's plan does not include API access — which returns the entitlement shape, not the gateway shape.",
"headers": {
"RateLimit": {
"description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/GatewayError"
},
{
"$ref": "#/components/schemas/EntitlementError"
}
]
},
"examples": {
"tenant_scope_violation": {
"value": {
"error": "tenant_scope_violation",
"message": "Token not authorized for this entity."
}
},
"insufficient_scope": {
"value": {
"error": "insufficient_scope",
"message": "Missing scope: book:write",
"required": [
"book:write"
]
}
},
"plan_denied": {
"value": {
"success": false,
"error": {
"code": "FEATURE_NOT_IN_PLAN",
"plan": "free",
"upgradeTo": "pro",
"upgradeUrl": "/settings/subscription?intent=upgrade",
"feature": "ApiAccess"
}
}
}
}
}
}
},
"RateLimited": {
"description": "Rate limit exceeded for this (clientId, installId) pair. Default 120 requests per 60s; see the description at the top of this document for the per-app override and the plan-derived ceiling.",
"headers": {
"RateLimit": {
"description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds until the window resets.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GatewayError"
},
"examples": {
"rate_limited": {
"value": {
"error": "rate_limited",
"message": "Public API rate limit exceeded."
}
}
}
}
}
},
"ServerError": {
"description": "Unhandled failure. The generic resource gateway also returns 500 with `controller_load_failed` or `handler_missing` when a registry row names a controller or export that does not resolve — binding is lazy and per-request, so a bad row fails on its own route rather than at boot.",
"headers": {
"RateLimit": {
"description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GatewayError"
}
}
}
},
"ServiceUnavailable": {
"description": "The AI-credit balance check itself was unavailable.",
"headers": {
"RateLimit": {
"description": "RFC 9651 draft-8 structured field, e.g. `\"default\"; r=118; t=41` — remaining requests and seconds until the window resets.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "Draft-8 policy, e.g. `\"default\"; q=120; w=60; pk=:mkt:<clientId>:<installId>:` — quota, window in seconds, and the partition key the quota is counted against.",
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AiCreditsError"
}
}
}
}
},
"schemas": {
"GatewayError": {
"type": "object",
"description": "The error shape emitted by the /public/v1 gateway middlewares (authentication, tenant match, scope, rate limit, controller binding).",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"description": "Stable machine-readable code."
},
"message": {
"type": "string"
},
"required": {
"type": "array",
"items": {
"type": "string"
},
"description": "Present on `insufficient_scope`: the scopes that were missing."
},
"resource": {
"type": "string",
"description": "Present on `controller_load_failed` / `handler_missing`: the registry `seg`."
},
"handler": {
"type": "string",
"description": "Present on `handler_missing`: the controller export that was absent."
},
"detail": {
"type": "string"
}
},
"additionalProperties": true
},
"AiCreditsError": {
"type": "object",
"description": "AI-credit metering refusal. Every /public/v1 request except /health, /me and the books draft→commit flow is charged against the install's tenant AI-credit wallet before any tenant work happens.",
"required": [
"error"
],
"properties": {
"error": {
"type": "string",
"enum": [
"INSUFFICIENT_AI_CREDITS",
"AI_CREDITS_CHECK_UNAVAILABLE",
"MISSING_ORG_OR_ENTITY"
]
},
"feature": {
"type": "string"
},
"requiredUSD": {
"type": "number"
},
"balanceUSD": {
"type": "number"
},
"creditBalance": {
"type": "number"
},
"requiredCredits": {
"type": "number"
},
"topUpUrl": {
"type": "string"
},
"message": {
"type": "string"
}
},
"additionalProperties": true
},
"EntitlementError": {
"type": "object",
"description": "A SECOND, DIFFERENT error shape. Plan-entitlement denials (`requireApiAccessFeature`) do not use the gateway shape above — they return the first-party subscription-guard payload, in which `error` is an OBJECT rather than a string. A client that reads `body.error` as a string will get `[object Object]` here. This divergence is real and is described rather than smoothed over.",
"required": [
"success",
"error"
],
"properties": {
"success": {
"type": "boolean",
"const": false
},
"error": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"enum": [
"FEATURE_NOT_IN_PLAN",
"LIMIT_EXCEEDED"
]
},
"plan": {
"type": "string"
},
"upgradeTo": {
"type": [
"string",
"null"
]
},
"upgradeUrl": {
"type": "string"
},
"feature": {
"type": "string"
},
"limitKey": {
"type": "string"
},
"limit": {
"type": [
"number",
"null"
]
},
"current": {
"type": [
"number",
"null"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}
},
"securitySchemes": {
"marketplaceOAuth2": {
"type": "oauth2",
"description": "Authorization-code OAuth 2.0 against the HelloBooks marketplace provider. The access token's audience is `marketplace_app`; it is bound to one AppInstall, and therefore to exactly one (org, entity) pair. Public clients use PKCE (`code_challenge` / `code_challenge_method` are accepted on /oauth/authorize).\n\nScopes are GRANULAR: 14 domains x {read, write} = 28 scopes, derived from the internal RBAC permission entity each of the 100 registry resources already gates on, folded onto the module axis of the RBAC v2 manifest. `book:read` and `book:write` are NOT deprecated and NOT removed — they remain first-class grantable BUNDLE scopes that expand to every granular read / write scope respectively, which is why every token issued before this vocabulary existed keeps working unchanged. Request the narrowest domains you need; ask for a bundle only if you genuinely need the whole surface.",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://api.hellobooks.ai/oauth/authorize",
"tokenUrl": "https://api.hellobooks.ai/oauth/token",
"refreshUrl": "https://api.hellobooks.ai/oauth/token",
"scopes": {
"book:read": "Read all of your books data (legacy bundle — grants every read scope)",
"book:write": "Create and update all of your books data (legacy bundle — grants every write scope)",
"accounting:read": "Read: Chart of accounts, journals, ledger, classes, locations, budgets and tax rates",
"accounting:write": "Create, update and delete: Chart of accounts, journals, ledger, classes, locations, budgets and tax rates",
"banking:read": "Read: Bank transactions, transaction lines, categorisation, cashbook, transfers and reconciliation links",
"banking:write": "Create, update and delete: Bank transactions, transaction lines, categorisation, cashbook, transfers and reconciliation links",
"sales:read": "Read: Invoices, quotes, sales orders, credit notes, delivery challans, recurring invoices, customer advances and leads",
"sales:write": "Create, update and delete: Invoices, quotes, sales orders, credit notes, delivery challans, recurring invoices, customer advances and leads",
"purchases:read": "Read: Bills, purchase orders, purchase requests, RFQs, goods receipts, vendor prepayments and expenses",
"purchases:write": "Create, update and delete: Bills, purchase orders, purchase requests, RFQs, goods receipts, vendor prepayments and expenses",
"contacts:read": "Read: Customers, vendors, business owners, their addresses, contact people, groups and balances",
"contacts:write": "Create, update and delete: Customers, vendors, business owners, their addresses, contact people, groups and balances",
"payments:read": "Read: Payments received and made",
"payments:write": "Create, update and delete: Payments received and made",
"paymentmethods:read": "Read: Stored credit and debit card details for customers, vendors, employees and owners",
"paymentmethods:write": "Create, update and delete: Stored credit and debit card details for customers, vendors, employees and owners",
"inventory:read": "Read: Items and stock records",
"inventory:write": "Create, update and delete: Items and stock records",
"reports:read": "Read: Balance sheet, profit and loss, cash flow, gross profit and revenue-by-customer reports",
"reports:write": "Create, update and delete: Balance sheet, profit and loss, cash flow, gross profit and revenue-by-customer reports",
"fixedassets:read": "Read: Fixed assets, asset groups, disposals, surveys, transfers and depreciation timing",
"fixedassets:write": "Create, update and delete: Fixed assets, asset groups, disposals, surveys, transfers and depreciation timing",
"projects:read": "Read: Projects and job tracking",
"projects:write": "Create, update and delete: Projects and job tracking",
"payroll:read": "Read: Employee records and employee addresses",
"payroll:write": "Create, update and delete: Employee records and employee addresses",
"comments:read": "Read: Comments attached to documents",
"comments:write": "Create, update and delete: Comments attached to documents",
"webhooks:read": "Read: Your app's webhook subscriptions",
"webhooks:write": "Create, update and delete: Your app's webhook subscriptions"
}
}
},
"x-hellobooks-scope-model": {
"grain": "granular",
"source": "utils/publicApiScopes.util.js",
"domainCount": 14,
"granularScopeCount": 28,
"domains": [
{
"name": "accounting",
"label": "Chart of accounts, journals, ledger, classes, locations, budgets and tax rates",
"read": "accounting:read",
"write": "accounting:write",
"manifestModule": "accounting"
},
{
"name": "banking",
"label": "Bank transactions, transaction lines, categorisation, cashbook, transfers and reconciliation links",
"read": "banking:read",
"write": "banking:write",
"manifestModule": "banking"
},
{
"name": "sales",
"label": "Invoices, quotes, sales orders, credit notes, delivery challans, recurring invoices, customer advances and leads",
"read": "sales:read",
"write": "sales:write",
"manifestModule": "sales"
},
{
"name": "purchases",
"label": "Bills, purchase orders, purchase requests, RFQs, goods receipts, vendor prepayments and expenses",
"read": "purchases:read",
"write": "purchases:write",
"manifestModule": "purchases"
},
{
"name": "contacts",
"label": "Customers, vendors, business owners, their addresses, contact people, groups and balances",
"read": "contacts:read",
"write": "contacts:write",
"manifestModule": "contacts"
},
{
"name": "payments",
"label": "Payments received and made",
"read": "payments:read",
"write": "payments:write",
"manifestModule": null,
"manifestNote": "split out of banking — money movement, separate on the Intuit precedent"
},
{
"name": "paymentmethods",
"label": "Stored credit and debit card details for customers, vendors, employees and owners",
"read": "paymentmethods:read",
"write": "paymentmethods:write",
"manifestModule": null,
"manifestNote": "no manifest module; stored payment-instrument detail, isolated deliberately"
},
{
"name": "inventory",
"label": "Items and stock records",
"read": "inventory:read",
"write": "inventory:write",
"manifestModule": "inventory"
},
{
"name": "reports",
"label": "Balance sheet, profit and loss, cash flow, gross profit and revenue-by-customer reports",
"read": "reports:read",
"write": "reports:write",
"manifestModule": "reports"
},
{
"name": "fixedassets",
"label": "Fixed assets, asset groups, disposals, surveys, transfers and depreciation timing",
"read": "fixedassets:read",
"write": "fixedassets:write",
"manifestModule": null,
"manifestNote": "internal permission entities exist; no manifest v2 module yet"
},
{
"name": "projects",
"label": "Projects and job tracking",
"read": "projects:read",
"write": "projects:write",
"manifestModule": null,
"manifestNote": "internal `project:*` permission entity; no manifest v2 module yet"
},
{
"name": "payroll",
"label": "Employee records and employee addresses",
"read": "payroll:read",
"write": "payroll:write",
"manifestModule": "payroll"
},
{
"name": "comments",
"label": "Comments attached to documents",
"read": "comments:read",
"write": "comments:write",
"manifestModule": null,
"manifestNote": "internal `comment:*` permission entity; cross-cutting annotations, no manifest module"
},
{
"name": "webhooks",
"label": "Your app's webhook subscriptions",
"read": "webhooks:read",
"write": "webhooks:write",
"manifestModule": null,
"manifestNote": "not a registry resource; the app's own webhook subscriptions"
}
],
"bundles": {
"book:read": {
"description": "Read all of your books data (legacy bundle — grants every read scope)",
"expandsTo": [
"accounting:read",
"banking:read",
"sales:read",
"purchases:read",
"contacts:read",
"payments:read",
"paymentmethods:read",
"inventory:read",
"reports:read",
"fixedassets:read",
"projects:read",
"payroll:read",
"comments:read",
"webhooks:read"
]
},
"book:write": {
"description": "Create and update all of your books data (legacy bundle — grants every write scope)",
"expandsTo": [
"accounting:write",
"banking:write",
"sales:write",
"purchases:write",
"contacts:write",
"payments:write",
"paymentmethods:write",
"inventory:write",
"reports:write",
"fixedassets:write",
"projects:write",
"payroll:write",
"comments:write",
"webhooks:write"
]
}
},
"compatibilityRules": [
"`book:read` expands to every `<domain>:read`.",
"`book:write` expands to every `<domain>:write`. It deliberately does NOT expand to reads — a write-only token cannot reach a read route today, and that stays true.",
"Webhook subscription management was gated by nothing beyond a valid bearer token, so `webhooks:read` + `webhooks:write` are granted to any token carrying either bundle AND to any token carrying no granular public-API scope at all. That covers live installs on unrelated vocabularies. Only a NEW grant that opted into granular scopes is held to them."
],
"expansionIsCheckedAtTheGuard": "middlewares/appAccessToken.middleware.js expands the granted list before requireScope() tests it, and never rewrites it: GET /me still reports exactly what was granted, not the expansion.",
"coarseByDesign": [
"POST /oauth/register (dynamic client registration) grants only the two bundles.",
"The /books/drafts draft -> confirm -> commit routes require only the bundles.",
"Both because AI-MCP-Hellobooks understands exactly four scope strings and ignores the rest, so a granular scope would grant its connector nothing."
],
"notGrantableOnThisApi": {
"scopes": [
"owner:close",
"audit:export"
],
"reason": "Part of the marketplace catalog and enforced by AI-MCP-Hellobooks, but checked by no /public/v1 route. Listing them among this API's scopes would imply they grant something here. They do not."
}
}
}
}
}
}