---
title: "Marketplace service API discovery"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/marketplace-service-apis.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Marketplace service API discovery

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

## In brief

- **REST discovery:** GET /services
- **Projection:** GET /openapi.json
- **Read scope:** appliances.read

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 444-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.71 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.

Note

appliances.read grants contract visibility only. A schema, path, record ID, canInvoke flag, or per-app OpenAPI operation is never accepted as authorization proof.

[Download Developer Kit 1.20.71](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.71.zip) [MCP security model](mcp-tools.html) [OpenAPI versioning](versioning-and-openapi.html)

---

Capability review: 2026-09-14. [View the canonical guide](https://support.buildwithhq.com/api/marketplace-service-apis.html).