Developer Platform

Builder Platform API

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

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

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

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. For exact current technical availability, use the generated API Map and first-class module inventory.