Public API Overview

The FITsociety Public API lives under:

https://api.fitsociety.io/public/v1

Use this API for server-to-server integrations that need direct REST resources, such as creating clients from an external CRM or automation platform.

New here? The Quickstart walks you from creating OAuth credentials to your first successful API call in about 10 minutes.

The Public API is separate from the MCP server. MCP clients continue to use /mcp/v1 and the MCP OAuth metadata. Access-device validation also lives under /public/v1, but it is a separate device contract. QR gates, badge scanners, and door controllers use /public/v1/access/* with device-key authentication.

Route families

Route family	Purpose	Auth model
`/public/v1/oauth/*`	Issue Public API access tokens	OAuth client credentials
`/public/v1/me`, `/public/v1/capabilities`, `/public/v1/scopes`	API client profile and capability resources	Bearer access token
`/public/v1/audit-logs`	Redacted Public API audit log resources	Bearer access token
`/public/v1/company-profile`, `/public/v1/locations`	Company catalog resources	Bearer access token
`/public/v1/clients`	Core CRM client and note resources	Bearer access token
`/public/v1/client-tags`	Client tag lookup resources	Bearer access token
`/public/v1/coaches`	Coach lookup resources	Bearer access token
`/public/v1/conversations`	Direct and group chat conversations	Bearer access token
`/public/v1/event-types`, `/public/v1/event-templates`, `/public/v1/calendar-events`	Calendar type, template, and event resources	Bearer access token
`/public/v1/recurring-bookings`, `/public/v1/calendar-tasks`, `/public/v1/booking-requests`, `/public/v1/availability-closures`	Calendar extension resources, including closure days and absence	Bearer access token
`/public/v1/coaches/{coachId}/availability`, `/public/v1/locations/{locationId}/availability`	Coach and location availability template management	Bearer access token
`/public/v1/availability`	Bookable calendar availability slots for client booking flows	Bearer access token
`/public/v1/bookings`	Booking read/write resources	Bearer access token
`/public/v1/finance`	Finance invoices, transactions, products, subscriptions, credits	Bearer access token
`/public/v1/forms`	Form metadata resources	Bearer access token
`/public/v1/clients/{clientId}/measurements/*`	Measurement entries	Bearer access token
`/public/v1/clients/{clientId}/progress-photos`	Progress photo metadata and signed URLs	Bearer access token
`/public/v1/clients/{clientId}/habits`, `/public/v1/clients/{clientId}/goals`	Habit and goal read/write resources	Bearer access token
`/public/v1/clients/{clientId}/documents`	Document metadata resources	Bearer access token
`/public/v1/reports/*`	Aggregate reporting summaries	Bearer access token
`/public/v1/webhooks`, `/public/v1/webhooks/{id}`, `/public/v1/webhooks/deliveries`	Outbound webhook subscription and delivery resources	Bearer access token
`/public/v1/access/*`	QR and access-device validation, documented under Access Devices	Device key
`/public/v1/webhooks/payment-requests/`, `/public/v1/webhooks/inbody/`, and other provider callback paths	Provider webhook receivers	Provider-specific signature or token

What you can call

Rather than maintaining a duplicate endpoint list here, use the API Reference tab — it is generated from the OpenAPI contract and always matches the live surface. The API covers these domains:

Domain	Highlights	Guide
Platform	API client profile, capabilities, scope catalog, redacted audit logs	Platform
Company catalog	Company profile, facilities, policies, locations, coaches	Company catalog, Coaches
Clients	CRM clients, custom fields, portal invites, timeline, notes	Clients, Client notes
Communication	Direct and group chat conversations, messages, and participants	Conversations
Calendar and bookings	Bookings, recurring bookings, events, event types/templates, tasks, availability	Calendar and bookings
Finance	Products, invoices, transactions, payment requests, subscriptions, credits, chargebacks	Finance
Progress	Measurements, progress photos, habits, goals	Measurements, Habits and goals
Forms	Create, update and archive form templates	Forms
Intakes	Assign intake forms and read submissions	Intakes
Check-ups	Schedule, inspect and cancel check-ups	Check-ups
Documents	Read and manage document metadata	Documents
Reporting	Attendance, revenue, and retention summaries	Reports
Webhooks	Outbound webhook subscriptions and delivery inspection	Webhooks

Invoice and payment list/detail resources remain read-focused. Public API write actions for reminders, invoice copies, payment requests, subscription action requests, memberships, products, and credits use guarded DTOs and reject raw pricing/provider internals. Invoice PDF access returns metadata for an existing generated PDF and a short-lived download URL; it does not create or regenerate invoice PDFs.

Response shape

OAuth token responses use the standard OAuth shape:

{
  "access_token": "fspt_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "clients:write"
}

Bearer resource auth errors use the same developer-facing error envelope as resource errors:

{
  "error": {
    "code": 401,
    "key": "auth.invalid_token",
    "message": "The access token is invalid."
  },
  "meta": {
    "requestId": "req_0123456789abcdef"
  }
}

Bearer resource controllers return explicit Public API envelopes:

{
  "data": {
    "id": "66a201f6962b241f55ebc216"
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": {
      "limit": 10,
      "remaining": 9,
      "resetSeconds": 1
    }
  }
}

Access-device endpoints and provider webhook receiver callbacks do not use this envelope. See the Access Devices section for the /public/v1/access/* response and auth contract. See the Webhooks page for outbound webhook management resources, which do use the Bearer Public API envelope.

Rate limits

Bearer Public API resource requests are currently limited per Public API client to 10 requests per second. Successful and failed authenticated resource responses include rate-limit data in meta.rateLimit and both standard and legacy rate-limit headers:

Header	Description
`RateLimit-Limit`	Maximum requests in the current one-second window.
`RateLimit-Remaining`	Remaining requests in the current window.
`RateLimit-Reset`	Seconds until the current window resets.
`X-RateLimit-Limit`	Legacy mirror of `RateLimit-Limit`.
`X-RateLimit-Remaining`	Legacy mirror of `RateLimit-Remaining`.
`X-RateLimit-Reset`	Legacy mirror of `RateLimit-Reset`.
`Retry-After`	Present on `429 rate_limit.exceeded`; seconds to wait before retrying.

Start here

Public API guides

Access Devices

Resources

Route families

What you can call

Response shape

Rate limits

​Route families

​What you can call

​Response shape

​Rate limits

Route families

What you can call

Response shape

Rate limits