Developer Platform

Current API contracts and error handling

Kit 1.20.76: exact public API contracts, SDK packaging, webhook errors and shared AI routes.

Pin a contract version

Developer Kit 1.20.76 contains 478 public operations, including 340 native module operations. The JSON and YAML downloads are the same contracts packaged in the ZIP. Keep the ZIP checksum with your integration release, generate clients from that version, and review changed response handling before upgrading.

Developer Kit 1.20.76: dynamic-module creation returns 201

POST /v1/apps/{saasAppId}/modules/dynamic/{moduleKey} now declares 201 Created, matching the existing controller response. Update clients that relied on the former 200 declaration. The receipt retains contractVersion, moduleKey, recordId and isFavorite; request fields, permissions, selected scope and storage behavior are unchanged.

Release acceptance includes native dynamic-module create, detail and revision-fenced removal as well as the generic object PATCH lifecycle. All ten simple-module null-field checks compare full and sparse responses without hiding empty fields. Review the exact ZIP-bound gate report beside the download; historical archives remain immutable.

Developer Kit 1.20.65: Contacts sorting and applied-order echoes

The Contacts list accepts optional sortBy (name, companyName, updatedUtc) and sortDirection (asc, desc). Responses echo the applied values. Defaults remain updatedUtc descending; record permissions and the browsing limit are unchanged.

The matching Gateway is deployed. Fresh authenticated acceptance checks all six sort echoes through the public HTTPS binding on the owned test tenant. The exact ZIP-bound offline and live report is beside the download; this evidence does not claim unrelated provider or tenant workflows were exercised.

Developer Kit 1.20.64: review corrections, generated contracts and SDK bounds

This release corrects the earlier Company News and Inbox reply prose using the archived contracts. Child-creation statuses, request-body policies and DELETE concurrency tables now come from the packaged OpenAPI, and the release gate rejects stale tables and contradictory current prose. Published changelog sections stay intact; corrections are recorded in the new entry.

The SDK now checks declared page-size bounds before requests for support-lane lists and options, record-graph search and reservation assignees. The kit includes an evidence index, the previous release's accepted report and live summary, and labeled prepublication receipts for the current payload. The final ZIP-bound report and checksum remain beside the download.

Unknown-field rejection from 1.20.63 remains in force for its tightened requests. The request-fields guide separately documents Calendar and Dynamic records' remaining open custom-field entry handling; those exceptions do not grant permission to create arbitrary field definitions.

Developer Kit 1.20.63: strict request fields and custom-field guidance

Breaking request-contract change: the tightened Chat, Conversations, Discussion, News and Files requests reject unknown fields with HTTP 400 instead of silently ignoring them. File uploads reject extra form fields and file-part names. The error identifies the field, preserves a correlation ID and does not echo the submitted value.

Some record types support administrator-configured custom fields. Where the operation declares dynamicFields, submit configured values through that input on the supported record create/edit route. Files upload uses the declared DynamicFieldsJson form input. Extra fields on messages, reactions, favorites and attachment links do not create custom fields. Configuration, visibility, permissions and revision requirements still apply.

All 19 previous open-body contract warnings are resolved. Publication now requires fresh live HTTP and real Chrome checks tied to the exact kit ZIP, alongside the offline contract, SDK, test and mutation gates. See the included docs/REQUEST-FIELDS.md and the exact gate report before upgrading.

Developer Kit 1.20.62: restored Mail Reader and live API calibration

The Mail Reader list, message detail, favorite and mark-read routes are restored after SQL security checks and live API and Chrome verification. Mailbox configuration, credentials, compose/send and archive remain outside the public Mail Reader API. Chat, Conversation and Discussion history clients validate paired cursors and declared page-size bounds before sending a request.

Response contracts now match live child creation status 201, attention presentation wrappers, optional response objects and validation/not-found/conflict errors. Regenerate clients and review CHANGELOG.md before upgrading. Preserve every revision string exactly. The archive passed the release gate on both supported Node versions and all 15 SDK guard mutation checks. Download its exact release-gate report; the report documents remaining contract warnings and does not replace testing your integration.

Developer Kit 1.20.61: historical release and corrections

This release added bounded Chat, Conversation and Discussion history and board topic paging, alongside nullable dynamic-field and opaque revision declarations. It also removed four previously published Mail Reader operations: GET /v1/apps/{saasAppId}/modules/mail-reader, GET /v1/apps/{saasAppId}/modules/mail-reader/{recordId}, PUT /v1/apps/{saasAppId}/modules/mail-reader/{recordId}/favorite and PUT /v1/apps/{saasAppId}/modules/mail-reader/{recordId}/read. Those were breaking removals, omitted from the original notes; version 1.20.62 restores them. Company News deletion already declared HTTP 409 in the published 1.20.61 contract. The contrary 1.20.62/1.20.63 errata is corrected in the 1.20.64 changelog; the earlier ZIP sections remain preserved.

The original 1.20.61 archive passed the release-gate implementation used at publication. A later audit found checks that were too weak for removal disclosure, revision conflict declarations, immutable changelog history and cursor coverage. The original report is preserved as historical evidence; it does not mean 1.20.61 passes the hardened policy. The archive and its checksum remain unchanged.

Developer Kit 1.20.60: preserve exact revision strings

Pre-launch request-contract and response-contract changes: timestamp revision fences and their source response fields are opaque strings in the OpenAPI and SDK. This includes Knowledge articles, Reservations, reservation products and tenant-user updates and deactivation. Preserve every fractional digit and the returned timezone marker, including its absence. Send the exact returned updatedUtc, modifiedUtc or revisionUtc value in the matching expectedUpdatedUtc or expectedRevisionUtc field. Never round-trip a revision through JavaScript Date. Refresh and reconcile a conflict before retrying.

The archive includes reviewed operation-scope metadata, declared error codes and aligned MCP revision and ID schemas. Its extracted contents passed the offline release gate, both Node 22.22.2 and 24.19.0 test/build runs, and all seven SDK guard mutation checks. See CHANGELOG.md, docs/API-OPERATING-CONTRACTS.md and docs/DELETE-CONCURRENCY.md inside the kit for affected operations and compatibility guidance.

These are kit validation results. Matching server changes need deployment and live verification. The kit does not establish deployed revision enforcement, unknown-field rejection, webhook retry ID typing or SQL error mappings. Communications child bodies remain open where rejection has not been proved; five child POST contracts retain HTTP 200 pending live evidence. Remote DSH journey evidence and publication of the private @buildwithhq/page-runtime package remain open.

Version 1.20.60 is a new immutable archive. The first 1.20.59 archive was superseded by its authoritative rebuild; both SHA-256 values are recorded in the kit changelog. Keep each archive with its own adjacent .sha256 file.

Every public operation now has a concise OpenAPI summary for API explorers and generated clients. The summaries describe route intent; the operation description, request schema, response schema and verified authority remain the contract for implementation.

The API route map now reflects corrected route discovery, including combined attributes, multiple aliases and absolute paths. Discovery corrections preserve existing operation scopes. An operation appearing in a catalog does not mean that its provider is configured for every app.

Webhook responses

Webhook delivery history now supports keyset paging. Request 1–100 rows with pageSize; if hasMore is true, send both returned nextBeforeCreatedUtc and nextBeforeDeliveryId as the next request's beforeCreatedUtc and beforeDeliveryId. The cursor ID and each item's deliveryId and eventId are decimal strings so JavaScript does not round a SQL BIGINT. Pass the string delivery ID directly to retryWebhookDelivery. Omit both cursor fields on the first page. The authorized account and app-scope filters apply to each page, and the SDK exposes listWebhookDeliveriesPage.

The six tenant-organization Snowflake operations cover configuration, connection testing, enable/pause, manual export and hosted scheduling. Organization owners and authorized Builder support credentials can configure Snowpipe Streaming through the same scoped public API. Setup, permissions and current availability.

Tenant payment lifecycle contracts

The kit includes typed public methods for tokenized payment-method registration and detail, revision-fenced default/revoke, and lease-version-fenced pending-charge cancellation. Payment-method writes use the sensitive-write budget. Send the exact expectedUpdatedUtc or expectedLeaseVersion returned by the latest read, refresh after HTTP 409, and never collect raw card data through these routes. The verified credential and secured procedures recheck app, organization, user, DataRole, location, customer and payable-record scope.

Use the declared response statuses below. Validation errors explain the field or position to correct; conflicts require resolving the reported state. Dependency failures may return 503, and unexpected failures return 500. An explicitly retryable dependency error includes Retry-After. Do not blindly retry mutations: preserve documented idempotency and revision checks.

Error JSON uses error for the safe explanation, code for the stable identifier and correlationId for troubleshooting. Include the correlation ID when requesting help. Do not put credentials, secrets or customer payloads into diagnostic messages.

CompanyIQ and OpsAtlas

These solutions share the existing app-scoped AI operations: GET /v1/apps/{saasAppId}/ai/status, POST /v1/apps/{saasAppId}/ai/sources/records/{recordId}/ingest, and POST /v1/apps/{saasAppId}/ai/search. Their availability depends on the caller's permissions, record visibility and configured AI providers. Separate solution-specific aliases are not required.

Installed services and ownership

Use GET /v1/apps/{saasAppId}/services and GET /v1/apps/{saasAppId}/openapi.json with appliances.read to discover available installed services. Pin the returned contract fingerprint. Discovery never grants permission to invoke an operation.

This kit also includes a separate BuildWithHQPlatformClient and 129 Builder-session operations for app lifecycle and provisioning, backups and upgrades, domains and runtime control, account/team/API-client lifecycle, diagnostics and support, BuildSpec workflows, billing/storage, marketplace and templates. Their standalone Platform Account OpenAPI is packaged as openapi/platform-owner.json. The client calls getBuilderSession for each request; provide the current verified Builder login token through that callback. Tenant-organization billing retains tenant, user, DataRole and location checks; a tenant API credential does not grant Builder account authority. Read the Builder Platform API guide.

Read billing availability at GET /v1/platform/billing/catalog, account resources at GET /v1/platform/billing/resources, and purchased entitlements at GET /v1/platform/marketplace/entitlements. SQL rechecks account ownership and action permissions. Catalog administration requires its existing operator permission. Public routes do not enable unconfigured payment providers, installation workers or deferred features. Check readiness and never blindly retry a purchase after a transport failure.

Verified server identity is passed to the secured stored procedures that authorize and perform the work. Frontends display their generated JSON. IDs supplied by a client select targets; they do not prove ownership.

SDK package correction

The public SDK entry point includes only the clients distributed in this archive. Its relative imports are checked after packaging. Replace the complete SDK folder together when upgrading.

Capability review: 2026-09-14. See current features and setup requirements, the generated API Map and first-class module inventory.