Support/Developer Platform/REST APIs
/

Developer Platform

REST APIs

The current resource-oriented v1 API for app identity, records, connectors, webhooks, AI, logs, contracts, and installed services.

Format
JSON over HTTPS
Reference host
api.buildwithhq.com
Data path
API to reviewed services

The REST surface is the general-purpose integration layer for software outside BuildWithHQ. It is intentionally resource-oriented: callers work with applications, objects, records, relationships, workflows, and actions — not SQL tables, database names, or stored-procedure names.

Current v1 resource families

  • Application metadata and schemas — discover the objects/modules and fields an integration is allowed to use.
  • Permission-aware records — list, search, retrieve, create, update, and archive records through reviewed server operations.
  • Relationships — inspect record relationships using the application's declared model.
  • Connectors and inbound endpoints — manage declared external integration metadata without returning provider secrets.
  • Webhooks — manage event subscriptions, rotate signing secrets, inspect delivery evidence, and retry eligible failures.
  • AI and logs — manage permitted AI ingestion/search/rebuild work and query bounded diagnostics.
  • Installed services — invoke approved container-backed endpoints through the gateway rather than private addresses.

Representative current routes

GET    /v1/apps/{saasAppId}/auth/context
GET    /v1/apps/{saasAppId}/objects
GET    /v1/apps/{saasAppId}/objects/{objectKey}/schema
POST   /v1/apps/{saasAppId}/objects/{objectKey}/records/search
POST   /v1/apps/{saasAppId}/objects/{objectKey}/records
PATCH  /v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}
DELETE /v1/apps/{saasAppId}/objects/{objectKey}/records/{recordId}
GET    /v1/apps/{saasAppId}/connector-types
GET    /v1/apps/{saasAppId}/logs/correlations/{correlationId}
Note

Use the generated OpenAPI document for the complete path set and schemas. These examples are current but intentionally do not duplicate the entire machine-readable reference.

Server-derived scope

Do not design an integration around caller-supplied tenant, user, role, or location IDs. The gateway derives the credential's application and actor context, then applies the application's permission model server-side. IDs supplied as ordinary input never grant additional access.

Reads and writes follow the same rule

Reads are filtered to the caller's allowed record envelope. Writes are stricter: a request must pass object-level, field/action-level, record-level, and application-level checks before the operation can execute. A valid JSON body is not proof that the caller is authorized to perform the change.

Async operations

Long-running work — imports, large exports, AI jobs, appliance work, or other queued operations — should return 202 Accepted with an operation identifier and a status resource instead of holding an HTTP request open indefinitely.

Tip

Build integrations against stable resource keys and returned schema metadata, not assumptions about BuildWithHQ's internal storage. That keeps your integration portable as the platform evolves.