Skip to main content

​
API Overview

PlanSync API surface is organized into three layers:
  • /api/auth/* for Better Auth session flows
  • /api/v1/* for product APIs
  • /api/stripe/* for billing-related operations

​
Base URL and proxy behavior

In production, use the API domain base URL (for example https://api.plansync.dev).
In local development, the web app usually proxies /api/* through the frontend host. The OpenAPI source of truth for this documentation is:
  • openapi/openapi.yaml

​
Response patterns

Most endpoints return JSON. Common behaviors:
  • 200/201 success payloads
  • 400 validation/body shape issues
  • 401 unauthenticated
  • 403 authenticated but not allowed (including email verification requirements)
  • 402 plan entitlement required
  • 404 resource not found

​
Important integration note

Prefer project API keys (x-api-key) for integrations and the docs playground. Session cookies still power the signed-in web app. Use cookies when calling from a browser session; use API keys for server-to-server or playground testing.

​
Common endpoint families

  • Workspace/project management
  • Files, uploads, viewer state/collaboration
  • Issues, RFIs, punch lists, field reports
  • Takeoff, materials, schedule
  • Proposals and O&M modules
  • Public token routes (proposal and occupant portals)
Continue to Authentication before implementing any integration.

​
Example: health check