{
  "entries": [
    {
      "id": "accounting-listWebhookTopics",
      "kind": "accounting",
      "name": "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.",
      "method": "GET",
      "path": "/public/v1/orgs/{orgId}/entities/{entityId}/webhooks/topics",
      "documentation": "https://developer.hellobooks.ai/docs/webhooks",
      "authentication": "OAuth 2.0; company authorization and operation scopes required",
      "details": {
        "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."
                }
              }
            }
          }
        }
      }
    }
  ],
  "total": 1,
  "catalogTotal": 565,
  "page": 1,
  "pageSize": 1,
  "totalPages": 1,
  "nextPage": null,
  "counts": {
    "public": 31,
    "mcp": 43,
    "accounting": 491
  },
  "source": "https://agents.hellobooks.ai/api/catalog.json",
  "reference": "https://agents.hellobooks.ai/api/developer-reference.json",
  "referenceProvenance": {
    "source": "HelloBooks-Backend-Auth-V3/openapi/public-api.openapi.json",
    "sourceCommit": "7abae8f78f7bc401c0184bede82dbaa28cde6e67",
    "importedAt": "2026-09-25T15:40:09.021Z"
  },
  "note": "Public APIs and MCP tools are hosted here. Accounting entries document the authenticated API; use company-scoped credentials at the documented API host."
}