Developer Platform
Current API contracts and error handling
Kit 1.20.28: exact public API contracts, SDK packaging, webhook errors and shared AI routes.
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.
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 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. For exact current technical availability, use the generated API Map and first-class module inventory.