HelloBooks / Agents

Build and connect

All HelloBooks APIs, in one place.

Find an endpoint, inspect its parameters, and open its documentation. Browse public data here or connect a company through the authenticated accounting API.

31 public endpoints43 MCP tools491 accounting operations

Find an accountantCatalog JSONAccounting OpenAPIDeveloper quickstart
Clear filters

1 matching APIs

Authenticated accounting

List every subscribable topic

GET /public/v1/orgs/{orgId}/entities/{entityId}/webhooks/topics

The catalogue registration validates against. Subscribing to a topic outside this list is rejected with a 400, so this is where the legal spelling comes from — the rejection can tell you a topic is wrong but not what is right. Derived from the same resource registry that mounts the write routes, so it cannot drift from what actually emits. `first_party_writes_emit` reports whether edits made INSIDE HelloBooks also emit on this deployment. It is a deployment switch, not a property of your app, and it is off by default — read it rather than assuming either answer. 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/orgs/{orgId}/entities/{entityId}/webhooks/topics' \
  --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": "listWebhookTopics",
  "summary": "List every subscribable topic",
  "description": "The catalogue registration validates against. Subscribing to a topic outside this list is rejected with a 400, so this is where the legal spelling comes from — the rejection can tell you a topic is wrong but not what is right.\n\nDerived from the same resource registry that mounts the write routes, so it cannot drift from what actually emits.\n\n`first_party_writes_emit` reports whether edits made INSIDE HelloBooks also emit on this deployment. It is a deployment switch, not a property of your app, and it is off by default — read it rather than assuming either answer.\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": [
    "webhooks"
  ],
  "security": [
    {
      "marketplaceOAuth2": [
        "webhooks:read"
      ]
    },
    {
      "marketplaceOAuth2": [
        "book:read"
      ]
    }
  ],
  "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": {
              "topics": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "count": {
                "type": "integer"
              },
              "by_resource": {
                "type": "object",
                "additionalProperties": true
              },
              "first_party_writes_emit": {
                "type": "boolean"
              },
              "note": {
                "type": "string"
              }
            },
            "required": [
              "topics",
              "count",
              "by_resource",
              "first_party_writes_emit"
            ],
            "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": true,
  "x-hellobooks-required-scopes": [
    "webhooks:read"
  ],
  "x-hellobooks-scope-grain": "granular",
  "parameters": [
    {
      "$ref": "#/components/parameters/orgId"
    },
    {
      "$ref": "#/components/parameters/entityId"
    }
  ],
  "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
      }
    },
    "parameters": {
      "orgId": {
        "name": "orgId",
        "in": "path",
        "required": true,
        "description": "The organisation the call targets. MUST equal the OrgRefId the access token's AppInstall is bound to — `requireTenantParamMatch` returns 403 `tenant_scope_violation` otherwise. There is no cross-tenant form of this API.",
        "schema": {
          "type": "string"
        }
      },
      "entityId": {
        "name": "entityId",
        "in": "path",
        "required": true,
        "description": "The entity (book) within the organisation. MUST equal the install's EntityRefId; see `orgId`.",
        "schema": {
          "type": "string"
        }
      }
    },
    "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."
          }
        }
      }
    }
  }
}

This API as JSON · Full reference and referenced schemas