4 sections · 19 pages
HelloBooks Public API Reference
Authentication, scopes, rate limits, endpoints, and quickstarts for the marketplace-facing /public/v1/* surface — plus the manufacturing API roadmap.
Browse by section
Pick a topic to explore
Foundations
Auth, scopes, rate limits, errors, tenant isolation. Read these first.
5 pagesExplore
Quickstarts
Hands-on walkthroughs against endpoints that are live today.
2 pagesExplore
Endpoint Reference
Every endpoint currently exposed at /public/v1/*.
5 pagesExplore
Manufacturing API (Roadmap)
Manufacturing endpoints are not yet exposed on /public/v1. This section describes the planned contract so integrators can preview shape and request prioritization.
7 pagesExplore
Every page
Index of all 19 pages
- FoundationsAuthenticationAll /public/v1/* requests require a Bearer access token minted for a marketplace app install. The token carries the tenant scope (org + entity) and the granted scopes.
- FoundationsScopesScopes are granted at install time. Each route checks a required scope before executing — missing scopes return 403 insufficient_scope.
- FoundationsRate limitsDefault 120 requests per 60 seconds per (clientId, install). Per-app overrides are configurable. Exceeding the limit returns 429 rate_limited.
- FoundationsErrorsEvery error response is JSON with an `error` machine code and a human-readable `message`. Some include extra fields like `required` (scopes) or `ticket` (not_implemented).
- FoundationsTenant isolationYour token is scoped to exactly one (org, entity). Any URL with a different :orgId or :entityId returns 403 tenant_scope_violation — even if you have a token for the other tenant.
- QuickstartsQuickstart: set up a marketplace app and verify authWalk through registering a marketplace app, completing the OAuth install, and verifying the resulting access token end-to-end. Runs against live endpoints (no roadmap parts).
- QuickstartsQuickstart: subscribe to webhook eventsCreate a webhook subscription, capture the signing secret, verify a delivery, and clean up. Runs end-to-end against live endpoints.
- Endpoint ReferenceGET /public/v1/healthReturns 200 ok with a server timestamp. Use as a reachability and auth-acceptance probe.
- Endpoint ReferenceGET /public/v1/meReturns the current install context — who you are, which tenant you are scoped to, and which scopes you hold.
- Endpoint ReferencePOST /public/v1/orgs/:orgId/entities/:entityId/webhooksSubscribe to one or more event topics. Returns the subscription row and a one-time signing_secret.
- Endpoint ReferenceGET /public/v1/orgs/:orgId/entities/:entityId/webhooksList active webhook subscriptions for the install, including delivery health metrics.
- Endpoint ReferenceDELETE /public/v1/orgs/:orgId/entities/:entityId/webhooks/:idSoft-delete a webhook subscription. Subsequent listings exclude it; the row is preserved for audit.
- Manufacturing API (Roadmap)Manufacturing API — Roadmap OverviewroadmapManufacturing endpoints are NOT yet exposed at /public/v1/*. The internal HelloBooks app uses six manufacturing controllers today; the public-API curated subset is roadmap.
- Manufacturing API (Roadmap)Roadmap: BOM (Bill of Materials)roadmapPlanned: full CRUD plus where-used analytics and material requirements explosion. Currently lives on the internal route /bom — not on /public/v1.
- Manufacturing API (Roadmap)Roadmap: Work OrdersroadmapPlanned: full lifecycle (Draft → InProgress → Completed/Cancelled) with InventoryAllocation reservations on release and atomic stock movements on completion.
- Manufacturing API (Roadmap)Roadmap: RecipesroadmapPlanned: CRUD on production recipes (the process-industry counterpart of BOM), with per-output-item lookup for production planning.
- Manufacturing API (Roadmap)Roadmap: Quality InspectionsroadmapPlanned: create + complete quality inspections against work orders or receipts, with stats endpoint for pass/fail trends.
- Manufacturing API (Roadmap)Roadmap: Subcontract OrdersroadmapPlanned: full subcontract lifecycle — create, issue materials to subcontractor, receive finished goods, and complete.
- Manufacturing API (Roadmap)Roadmap: Manufacturing ReportsroadmapPlanned: read-only reports (job costing, by-products, production cost analysis, efficiency) with 5-minute server-side cache.