BuildWithHQ
Canonical knowledge unit · extensibility

API-first custom service boundary

Developer custom code runs behind declared, schema-validated API endpoints so BuildWithHQ can bind custom logic into pages, workflows, AI, and external APIs without exposing platform core IP or direct unrestricted SQL.

ID: BWHQ-EXT-001Status: currentAuthority: highapicustom-servicescontainersextensibility

API-first custom service boundary

Pattern

When structured JSON configuration is not enough, a developer can implement normal code in an isolated service/container and expose stable API endpoints.

Contract

A service version can declare endpoint keys/routes, input/output JSON schemas, required permission, execution mode, timeout, network egress policy, image digest, SBOM, and release fingerprint.

Invocation

Pages, workflows, API routes, and AI/MCP actions bind to a stable endpoint key. The platform authorization layer remains in front of the custom code.

Isolation

Custom service code does not receive BuildWithHQ core source merely because it runs near the app, and external clients do not receive unrestricted SQL access. The contract around custom code is governed even though the code itself can use normal languages, libraries, and SDKs.

Related knowledge

Server-driven JSON presentationBuildWithHQ represents pages and much application behavior as versioned JSON/schema interpreted by a shared runtime, enabling many application variations from a common codebase.Headless SaaS and scoped API clientsBuildWithHQ can act as a secured headless backend for external frontends, legacy systems, mobile apps, dashboards, and scripts through scoped API clients.Security invariantsSecurity is designed as a shared structural layer: server-derived identity, one authorization path, explicit tenant/application/location scope, and separate permissions for read, AI, export, and sensitive disclosure.
Machine-readable source: canonical Markdown. This HTML companion exists for human reading, search indexing, and AI retrieval.