---
title: "Current API contracts and error handling"
section: "Developer Platform"
canonical_url: "https://support.buildwithhq.com/api/current-api-contracts.html"
reviewed_at: "2026-09-14"
authority: Official
---

# Current API contracts and error handling

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

## In brief

- **Kit:** 1.20.28
- **Public operations:** 358
- **Native module operations:** 255
- **Authority:** Verified server identity

[Developer Kit 1.20.28](../downloads/BuildWithHQ-API43-Developer-Kit-1.20.28.zip) [OpenAPI JSON](../downloads/BuildWithHQ-OpenAPI-1.20.28.json) [OpenAPI YAML](../downloads/BuildWithHQ-OpenAPI-1.20.28.yaml)

## Pin a contract version

Developer Kit 1.20.28 contains 358 public operations, including 255 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.

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

This version also adds five tenant-organization Snowflake operations. Organization owners and authorized Builder support credentials can configure Snowpipe Streaming through the same scoped public API. [Setup, permissions and current availability](tenant-snowflake.html).

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.

| Operation | Declared responses |
| --- | --- |
| `GET /v1/apps/{saasAppId}/webhook-deliveries` | 200, 400, 401, 403, 500, 429, 409, 422, 503 |
| `POST /v1/apps/{saasAppId}/webhook-deliveries/{deliveryId}/retry` | 200, 400, 404, 401, 403, 500, 429, 409, 422, 503 |
| `GET /v1/apps/{saasAppId}/webhook-event-types` | 200, 401, 403, 500, 429, 409, 422, 503 |
| `GET /v1/apps/{saasAppId}/webhooks` | 200, 401, 403, 500, 429, 409, 422, 503 |
| `POST /v1/apps/{saasAppId}/webhooks` | 201, 401, 403, 500, 429, 409, 422, 503, 400 |
| `PUT /v1/apps/{saasAppId}/webhooks/{subscriptionId}` | 200, 404, 401, 403, 500, 429, 409, 422, 503, 400 |
| `POST /v1/apps/{saasAppId}/webhooks/{subscriptionId}/rotate-secret` | 200, 400, 404, 401, 403, 500, 429, 409, 422, 503 |

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 73 Builder-session billing, storage, marketplace and template operations. Their standalone [Platform Account OpenAPI](https://api.buildwithhq.com/v1/platform/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 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. [View the canonical guide](https://support.buildwithhq.com/api/current-api-contracts.html).