Developer Platform

Marketplace service API discovery

Discover installed custom endpoint schemas, download per-app OpenAPI, and let MCP agents plan governed calls.

Marketplace features can publish custom endpoints without forcing every possible service into the static platform SDK. The Developer API now exposes the installed contract for the selected SaaS app while preserving one governed invocation door.

API callers never receive SQL credentials or database permissions. The server injects the verified SaaS app, tenant account, and user identity and executes only allow-listed stored procedures through bwhq_developer_api. That database role has procedure-level EXECUTE grants, no table access, no DDL authority, and no ability to drop, create, alter, or directly delete database objects or rows.

Discover installed endpoint contracts

Call GET /v1/apps/{saasAppId}/services with a server-held live credential carrying appliances.read. The response includes each installed service key, exact package version and release fingerprint, fixed health state (Green, Yellow, or Red), fixed license state (Active, Suspended, or Revoked), input and output schemas, required permission, execution mode, timeout, availability, and the current tenant user's canInvoke result. It never returns container addresses, secret references, database routes, or provider credentials.

Download the app-specific OpenAPI contract

Call GET /v1/apps/{saasAppId}/openapi.json with the same read scope. The result combines the 283-operation base contract with one concrete logical invocation operation for each available installed endpoint. Its OpenAPI response formally declares ETag, X-BuildWithHQ-Contract-SHA256, and Cache-Control: private, no-store; the document also carries x-buildwithhq-contract-set-sha256. Generated clients can therefore surface, pin, and detect fingerprint changes.

Verify discovery authorization

Developer Kit 1.20.3 includes evidence/installed-service-discovery-policy.sql, the exact reviewed DROP/CREATE procedure deployed to the golden CustomerCopy database, plus a sanitized JSON evidence record tied to its migration and deployed-definition hashes. Reviewers can verify that discovery first authorizes the calling app/account/user principal, returns only active installations and endpoints whose SaaSAppId equals the requested app, and computes canInvoke only when the current principal is allowed the endpoint's exact normalized permission key. The receipt also records a rollback-only proof that installs v1, deactivates it, installs v2, and discovers available/invocable v2 without leaking v1. Server and backup topology remain outside the kit.

Dynamic MCP schemas

buildwithhq.services.list requires mcp.use + appliances.read and returns the same current endpoint schemas. Agents inspect that result, then use the retained generic buildwithhq.services.invoke tool. Invocation separately requires mcp.use + appliances.invoke, per-app approval of installed_services.invoke, the endpoint permission, an executable exact-fingerprint installation, and secured source records.

Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.