---
title: "Builder Platform API"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/builder-platform-api.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Builder Platform API

Use the 136-operation owner API for app, account, operations, diagnostics and BuildSpec workflows.

## In brief

- **Kit:** 1.20.35
- **Operations:** 136
- **Base path:** /v1/platform
- **Authentication:** Verified Builder session

[Download Developer Kit 1.20.35](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.35.zip) [Platform OpenAPI](https://api.buildwithhq.com/v1/platform/openapi) [Current contract changes](current-api-contracts.html)

## Choose the Builder contract

Use `BuildWithHQPlatformClient` when your trusted Builder integration manages apps and organizations owned by the signed-in Builder account. It is separate from the app-scoped `BuildWithHQConnector`. App credentials and tenant-user sessions cannot become Builder authority. The client asks `getBuilderSession` for the current session on every request so normal refresh, MFA, revocation and logout rules remain in force.

```
import { BuildWithHQPlatformClient } from "./sdk/index.js";

const platform = new BuildWithHQPlatformClient({
  baseUrl: "https://api.buildwithhq.com",
  getBuilderSession: async () => currentBuilderSession
});
```

Keep the session on a trusted server or in the supported Builder client boundary. Never place it in public source, page JSON, logs, prompts or a downloadable configuration file.

The Platform OpenAPI document is intentionally readable without a Builder session so tooling can discover its route and schema shape. This read grants no account access: all 136 operations still require verified Builder identity, ownership and action permission. The current kit gives each operation a typed success response and summary. Pin the SHA-256 in `sdk/platform-operation-coverage.json` to the packaged `openapi/platform-owner.json` before generating or updating a client.

## Choose the namespace by authority and resource

| Namespace | Use it for | Identity |
| --- | --- | --- |
| `/v1/platform/...` | The Builder account and its owned apps: provisioning, operations, team, diagnostics, BuildSpec, billing, marketplace and templates. | Current verified Builder session through `BuildWithHQPlatformClient`. |
| `/v1/apps/{saasAppId}/accounts/...` | Customer-organization and tenant-user provisioning by the SaaS application's trusted backend. | App-bound server credential with the exact tenant-management scope. |
| `/v1/apps/{saasAppId}/modules/...` | Typed first-class business modules such as Contacts, Work Orders, Reservations, Payments and Universal Inbox. | App credential or delegated tenant user; server applies tenant, DataRole, location and record scope. |
| `/v1/apps/{saasAppId}/objects/...` | Generic schema and record workflows for dynamic business objects that do not have a dedicated module method. | App or delegated-user credential with object/record permissions. |
| `/v1/apps/{saasAppId}/services/...` | Discover and invoke exact-version marketplace services running in their own VM or microVM and private data store. | Tenant context plus installed endpoint permission; discovery does not grant invocation. |
| `/v1/apps/{saasAppId}/ai/...` | Shared AI status, authorized record ingestion, rebuilds and multimodal search. | AI scopes plus the same tenant, DataRole, location and `CanAiReadRecords` envelope. |
| `/v1/apps/{saasAppId}/organization/...` | Singleton administration for the caller's current organization, including Snowflake export. | Active organization owner or an explicitly bound supported Builder context. |
| `/v1/apps/{saasAppId}/mcp` | The MCP transport over the same permission-filtered Developer API and installed-service catalog. | App credential or delegated tenant user with `mcp.use` and each tool's ordinary scope. |

Public assets, browser challenges, outside-form submissions and provider callbacks use their route-specific ingress protocol. Their lack of a normal bearer on the first request does not turn them into general anonymous API namespaces.

## Create an app safely after a timeout

`POST /v1/platform/apps` requires an `idempotencyKey` UUID in the JSON body with `appName` and `deploymentType`. Generate one key for one intended app and retain it until the result is known. If the response is lost, resend the same key and details: the server returns the original app and does not enqueue a second provisioning job. A different payload with that key returns HTTP 409. Use a new key for a separate app. The response `correlationId` helps support trace a request; it is not the retry key.

## Supported workflow groups

| Workflow | What is included | Kit guide and tests |
| --- | --- | --- |
| Apps and provisioning | Create an app, read provisioning progress and administrative detail, and use the supported suspend/resume lifecycle. | `PLATFORM-APP-LIFECYCLE.md`
`examples/platform-app-lifecycle.test.mjs` |
| Backups, upgrades, domains and runtime | Manage protected backup destinations, queue and inspect backups, request reviewed database upgrades, manage domains, and read/restart owned runtime state. | `PLATFORM-BACKUP-DOMAIN-RUNTIME.md`
`examples/platform-operations.test.mjs` |
| Identity, team and API clients | Integrate the existing Builder login/session protocol, manage account settings, team membership and invitations, and issue or revoke one-time API-client credentials. | `PLATFORM-IDENTITY-TEAM-API-CLIENTS.md`
`examples/platform-identity-team-clients.test.mjs` |
| Diagnostics and support | Read bounded app observability, use 24-hour diagnostic sessions and history, search account audit, triage SaaS-developer problems, and inspect owned seller versions. | `PLATFORM-DIAGNOSTICS-SUPPORT.md`
`examples/platform-diagnostics-support.test.mjs` |
| BuildSpec | Start and read a session, record requirements, validate, read progress, decide an exact pending review, and create an unpublished reuse candidate from completed work. | `PLATFORM-BUILDSPEC-WORKFLOW.md`
`examples/platform-buildspec-workflow.test.mjs` |

## Authority and state rules

The server derives the Builder user and account from the verified session. App and organization IDs select a target; they do not prove ownership. Each operation rechecks the owned app, active organization and required action permission through typed services and reviewed database contracts. Organization-owned payments remain on the app-scoped API because they require tenant, user, DataRole, location and payable-record authority.

Preserve returned row versions, revisions, review fingerprints, job IDs and idempotency fields. Refresh after a conflict. Do not blindly retry purchases, credential issuance, runtime restarts, backup starts or other consequential mutations after an ambiguous transport failure. Safe errors include a stable code and correlation ID; send support the correlation ID without credentials or customer payloads.

## BuildSpec approval remains mandatory

Validation and progress reads do not approve work. When progress reports a pending review, keep the job parked, display the reviewed summary and submit the exact review ID and fingerprint through the decision operation. A repeated identical decision is idempotent; a conflicting decision returns a conflict. Reuse candidates are created unpublished. The deterministic workflow contract does not promise that an external AI provider is configured or ready.

## What remains outside this client

Builder login, MFA, recovery, invitation acceptance, refresh and logout remain their existing identity protocol. Provider callbacks retain provider-signature validation. Health and discovery endpoints remain operational metadata. Global AI control, master-operator projections and explicit `/api/operator/...` history remain operator-only. Native tenant-session routes keep tenant role, DataRole, location and record visibility checks instead of accepting a Builder-session proxy.

The kit includes `docs/api-route-inventory-first-class-and-build-this.md` and the complete `skills/` source tree for route discovery and Skill authoring. Those files describe available contracts; they do not grant scopes, tools, records, GoClaw assignment or mutation authority.

---

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