Skip to content
BuildWorkPro Docs

API Changelog

This changelog tracks public API changes. We follow the Keep a Changelog format and Semantic Versioning. Breaking changes only ship in a new major version. Additive changes (new endpoints, new optional fields, new event types) ship in minor versions.

[Unreleased]

Section titled “[Unreleased]”

The API surface below is live in the current OpenAPI spec (still declared v1.0.0) but has not yet been cut into a new version tag. It will be assigned a version number and date on the next release.

Added

Section titled “Added”
  • pay_apps:mark_paid scope with POST /api/v1/pay-apps/{id}/mark-paid -- mark an approved pay application as paid.
  • audit:read scope with GET /api/v1/usage (rate-limit and usage snapshot) and GET /api/v1/api-audit-logs (API request audit trail).
  • settings:read and settings:write scopes with read/write endpoints under /api/v1/settings/ (branding, data retention).
  • Expanded webhook catalog from 10 to 29 event types -- added bid.updated, bid.deleted, bid.expired, bid.acceptance_reverted, project.updated, project.deleted, pay_app.rejected, pay_app.updated, pay_app.deleted, pay_app.paid, change_order.submitted, change_order.updated, change_order.rejected, change_order.voided, change_order.deleted, contact.updated, contact.deleted, lead.updated, and lead.deleted.

[v1.0.0] — 2026-04-25

Section titled “[v1.0.0] — 2026-04-25”

Initial public release of the BuildWorkPro REST API.

Added

Section titled “Added”
  • Response envelope -- All 2xx responses return { "data": ..., "meta": { "request_id": "..." } }. List responses include meta.pagination.
  • RFC 9457 problem details -- All errors return application/problem+json with a machine-readable type URL (whose fragment is a stable error code), human-readable title/detail, and request_id.
  • 39-scope catalog -- 30 resource scopes (10 families x read/write/delete) + 4 workflow scopes (bids:send, bids:accept_reject, pay_apps:approve, change_orders:approve) + 5 meta scopes (users:read, webhooks:manage, jobs:read, jobs:write, offline_access). Enforced uniformly for both API keys and OAuth tokens.
  • Cursor pagination -- Opaque, HMAC-signed cursors with ?limit= (default 25, max 100) on every list endpoint. Stable ordering and tamper-resistant.
  • Idempotency middleware -- All mutations accept Idempotency-Key. Responses replayed for 24 hours per key.
  • Cost-weighted rate limiting -- Tenant-wide hourly budget plus per-key per-minute limit. RateLimit-* headers on every response and Retry-After on 429.
  • OpenAPI 3.1 spec -- Published at /api/v1/openapi.json and rendered as the API Reference. Linted with Spectral on every commit.
  • 14 v1 modules rewritten on the new foundation -- contacts, leads, projects, bids, pay applications, change orders, site logs, time entries, products, documents, calendar, users, project templates, settings.
  • Webhooks subsystem -- 10 launch event types (bid.created, bid.accepted, bid.rejected, project.created, project.status_changed, pay_app.submitted, pay_app.approved, change_order.approved, contact.created, lead.created), HMAC-SHA256 signatures (Bwp-Signature header with timestamp + replay window), exponential-backoff retries, SSRF guard at delivery time, and a manual replay endpoint.
  • Jobs subsystem -- Async CSV export, CSV import, bulk operations, and PDF generation. Artifacts are served via short-lived, single-use signed download URLs.
  • OAuth 2.1 with PKCE -- Authorization code grant with mandatory PKCE (S256), refresh token rotation with reuse detection, and Dynamic Client Registration (RFC 7591). Granted scopes are intersected with the consenting user's tenant role.
  • Identity endpoints -- GET /api/v1/me for the calling principal, GET /api/v1/oauth/userinfo (OIDC-compatible) for tokens carrying openid, and POST /api/v1/oauth/revoke (RFC 7009).
  • Discovery -- OAuth Authorization Server Metadata at /.well-known/oauth-authorization-server.