{
  "entries": [
    {
      "id": "accounting-listPurchaseOrder",
      "kind": "accounting",
      "name": "List purchaseOrder records",
      "description": "Mounted by the generic resource factory in `routes/publicApi.routes.js` from the registry row `purchaseOrder` in `routes/publicApi.resources.js`. The request is delegated to the SAME internal controller a signed-in user hits (`controllers/GRPC/Accounting/purchaseOrder.grpc` → `getPurchaseOrders`), so it inherits that controller's validation, server-side tax computation and audit trail. Guards applied, in order: bearer token (`marketplace_app` audience) → plan API-access entitlement → rate limit → AI-credit metering → permission context of the installing user → tenant path match → `requireScope(\"purchases:read\")`.",
      "method": "GET",
      "path": "/public/v1/orgs/{orgId}/entities/{entityId}/purchaseOrder",
      "documentation": "https://developer.hellobooks.ai/docs/reference-purchases?resource=purchaseOrder&op=0",
      "authentication": "OAuth 2.0; company authorization and operation scopes required",
      "details": {
        "operationId": "listPurchaseOrder",
        "summary": "List purchaseOrder records",
        "description": "Mounted by the generic resource factory in `routes/publicApi.routes.js` from the registry row `purchaseOrder` in `routes/publicApi.resources.js`. The request is delegated to the SAME internal controller a signed-in user hits (`controllers/GRPC/Accounting/purchaseOrder.grpc` → `getPurchaseOrders`), so it inherits that controller's validation, server-side tax computation and audit trail. Guards applied, in order: bearer token (`marketplace_app` audience) → plan API-access entitlement → rate limit → AI-credit metering → permission context of the installing user → tenant path match → `requireScope(\"purchases:read\")`.",
        "tags": [
          "purchaseOrder"
        ],
        "security": [
          {
            "marketplaceOAuth2": [
              "purchases:read"
            ]
          },
          {
            "marketplaceOAuth2": [
              "book:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/orgId"
          },
          {
            "$ref": "#/components/parameters/entityId"
          },
          {
            "$ref": "#/components/parameters/isArchived"
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Note that these controllers return 200 with a failure message in some paths rather than a 4xx; check the body.",
            "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": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessEnvelope"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "description": "Present only on the controllers that use the `data` key. When present it holds the collection.",
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/PurchaseOrder"
                          }
                        }
                      }
                    }
                  ],
                  "description": "The payload is a collection of `PurchaseOrder` records. It is returned under a resource-named top-level key chosen by the internal controller (`accounts`, `bills`, `transactions`, …), NOT reliably under a fixed envelope field — see SuccessEnvelope. Which key this particular controller uses is not yet described; that arrives with the field contract.",
                  "x-hellobooks-payload": {
                    "cardinality": "collection",
                    "record": "#/components/schemas/PurchaseOrder"
                  }
                }
              }
            }
          },
          "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": "factory",
        "x-hellobooks-controller": "controllers/GRPC/Accounting/purchaseOrder.grpc",
        "x-hellobooks-handler": "getPurchaseOrders",
        "x-hellobooks-registry-verb": "list",
        "x-hellobooks-scope-grain": "granular",
        "x-hellobooks-required-scopes": [
          "purchases:read"
        ],
        "x-hellobooks-scope-domain": "purchases",
        "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": {
          "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"
              }
            },
            "isArchived": {
              "name": "isArchived",
              "in": "query",
              "required": false,
              "description": "Return archived records instead of active ones. The gateway compares the raw query value against the literal string `true`; every other value, `1` and `TRUE` included, is treated as false.",
              "schema": {
                "type": "string",
                "enum": [
                  "true",
                  "false"
                ]
              }
            }
          },
          "schemas": {
            "SuccessEnvelope": {
              "type": "object",
              "description": "A /public/v1 success body. THERE IS NO SINGLE ENVELOPE — this was measured, not assumed: across the Accounting controllers these routes delegate to, top-level success keys are `success` (219 sites), `message` (322), `data` (18), plus 146 distinct resource-named keys such as `accounts`, `bills`, `transactions`, `items`, `groups`. Any rule of the form 'the payload lives under .data' would be wrong most of the time. The properties below are therefore the keys that MAY appear, none of them required, and the payload itself sits under a resource-named key this description cannot yet name per resource.",
              "properties": {
                "success": {
                  "type": "boolean"
                },
                "message": {
                  "type": "string"
                },
                "data": {}
              },
              "additionalProperties": true,
              "x-hellobooks-envelope": "heterogeneous"
            },
            "PurchaseOrder": {
              "type": "object",
              "additionalProperties": true,
              "description": "A `purchaseOrder` record, from the published field contract (model `PurchaseOrder`). Additional properties are permitted because the runtime allowlist is not yet in enforce mode — see PUBLIC_API_FILTER_MODE.",
              "properties": {
                "AcceptedByVendorAt": {
                  "type": "string"
                },
                "Addresses": {
                  "type": "array"
                },
                "ApprovalComment": {
                  "type": "string"
                },
                "ApprovalStatus": {
                  "type": "string"
                },
                "ApprovedAt": {
                  "type": "string"
                },
                "ApprovedBy": {
                  "type": "string"
                },
                "Attachments": {
                  "type": "object"
                },
                "BrandingThemeId": {
                  "type": "string"
                },
                "ClassRef": {
                  "type": "string"
                },
                "Comment": {
                  "type": "string"
                },
                "CreatedAt": {
                  "type": "string",
                  "readOnly": true
                },
                "CreatedBy": {
                  "type": "string"
                },
                "CreatedByName": {
                  "type": "string"
                },
                "Currency": {
                  "type": "string"
                },
                "DeclinedByVendorAt": {
                  "type": "string"
                },
                "DeclinedReason": {
                  "type": "string"
                },
                "ExchangeRate": {
                  "type": "number"
                },
                "ExpectedDeliveryDate": {
                  "type": "string"
                },
                "FinancialYear": {
                  "type": "string"
                },
                "FunctionalTotalPayableAmount": {
                  "type": "number"
                },
                "FxRateDate": {
                  "type": "string"
                },
                "FxSource": {
                  "type": "string"
                },
                "IsArchived": {
                  "type": "boolean"
                },
                "LocationRef": {
                  "type": "string"
                },
                "PayeeRef": {
                  "type": "string"
                },
                "PayeeType": {
                  "type": "string"
                },
                "PlaceOfSupply": {
                  "type": "string"
                },
                "ProjectRef": {
                  "type": "string"
                },
                "PurchaseOrderDate": {
                  "type": "string",
                  "readOnly": true
                },
                "PurchaseOrderNumber": {
                  "type": "string"
                },
                "QboId": {
                  "type": "string"
                },
                "QboLinkedAt": {
                  "type": "string"
                },
                "QboRealmId": {
                  "type": "string"
                },
                "QboSyncToken": {
                  "type": "string"
                },
                "ReceiptStatus": {
                  "type": "string"
                },
                "ReferenceNumber": {
                  "type": "string"
                },
                "Status": {
                  "type": "string"
                },
                "TallyGuid": {
                  "type": "string"
                },
                "TallyVoucherType": {
                  "type": "string"
                },
                "TaxType": {
                  "type": "string"
                },
                "TermsAndConditions": {
                  "type": "object"
                },
                "TotalLabourAmount": {
                  "type": "number"
                },
                "TotalPayableAmount": {
                  "type": "number"
                },
                "TotalSupplyAmount": {
                  "type": "number"
                },
                "TotalTaxAmount": {
                  "type": "number"
                },
                "TotalTaxableAmount": {
                  "type": "number"
                },
                "UpdatedAt": {
                  "type": "string",
                  "readOnly": true
                },
                "XeroId": {
                  "type": "string"
                },
                "XeroLinkedAt": {
                  "type": "string"
                },
                "XeroTenantId": {
                  "type": "string"
                },
                "XeroUpdatedDateUTC": {
                  "type": "string"
                },
                "chartOfAccountId": {
                  "type": "string"
                },
                "id": {
                  "type": "string",
                  "readOnly": true
                }
              },
              "x-hellobooks-field-contract": "published"
            },
            "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
            }
          },
          "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"
                  }
                }
              }
            }
          },
          "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."
}