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. 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/event-types`, `/public/v1/event-templates`, `/public/v1/calendar-events`	Calendar type, template, and event resources	Bearer access token
`/public/v1/clients/{clientId}/chats`	Messaging read 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, payments, 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

Current v1 scope

The first Public API resources are:

GET  /public/v1/clients
GET  /public/v1/me
GET  /public/v1/capabilities
GET  /public/v1/scopes
GET  /public/v1/audit-logs
GET  /public/v1/audit-logs/{auditLogId}
GET  /public/v1/company-profile
GET  /public/v1/facilities-services
GET  /public/v1/company-policies
GET  /public/v1/locations
POST /public/v1/locations
GET  /public/v1/locations/{locationId}
PATCH /public/v1/locations/{locationId}
POST /public/v1/locations/{locationId}/archive
GET  /public/v1/locations/{locationId}/availability
PUT  /public/v1/locations/{locationId}/availability
POST /public/v1/clients
GET  /public/v1/clients/{clientId}
PATCH /public/v1/clients/{clientId}
POST /public/v1/clients/{clientId}/archive
GET  /public/v1/clients/{clientId}/portal-access
POST /public/v1/clients/{clientId}/invite
POST /public/v1/clients/{clientId}/invite/resend
POST /public/v1/clients/{clientId}/relationship/approve
POST /public/v1/clients/{clientId}/relationship/reject
GET  /public/v1/client-custom-fields
GET  /public/v1/clients/{clientId}/custom-fields
PATCH /public/v1/clients/{clientId}/custom-fields
GET  /public/v1/clients/{clientId}/assigned-coaches
PATCH /public/v1/clients/{clientId}/assigned-coaches
GET  /public/v1/clients/{clientId}/timeline
GET  /public/v1/clients/{clientId}/notes
POST /public/v1/clients/{clientId}/notes
PATCH /public/v1/clients/{clientId}/notes/{noteId}
DELETE /public/v1/clients/{clientId}/notes/{noteId}
GET  /public/v1/client-tags
GET  /public/v1/coaches
GET  /public/v1/coaches/{coachId}
GET  /public/v1/coaches/{coachId}/availability
PUT  /public/v1/coaches/{coachId}/availability
GET  /public/v1/clients/{clientId}/chats
GET  /public/v1/clients/{clientId}/chats/{chatId}/messages
GET  /public/v1/event-types
POST /public/v1/event-types
GET  /public/v1/event-types/{eventTypeId}
PATCH /public/v1/event-types/{eventTypeId}
POST /public/v1/event-types/{eventTypeId}/archive
GET  /public/v1/event-templates
POST /public/v1/event-templates
GET  /public/v1/event-templates/{eventTemplateId}
PATCH /public/v1/event-templates/{eventTemplateId}
POST /public/v1/event-templates/{eventTemplateId}/archive
GET  /public/v1/calendar-events
GET  /public/v1/calendar-events/{eventId}
GET  /public/v1/recurring-bookings
GET  /public/v1/recurring-bookings/{recurringBookingId}
PATCH /public/v1/recurring-bookings/{recurringBookingId}
POST /public/v1/recurring-bookings/{recurringBookingId}/cancel
GET  /public/v1/calendar-tasks
GET  /public/v1/calendar-tasks/{taskId}
POST /public/v1/calendar-tasks
PATCH /public/v1/calendar-tasks/{taskId}
POST /public/v1/calendar-tasks/{taskId}/cancel
GET  /public/v1/booking-requests
POST /public/v1/booking-requests/{bookingRequestId}/approve
POST /public/v1/booking-requests/{bookingRequestId}/reject
GET  /public/v1/availability-closures
PUT  /public/v1/availability-closures
GET  /public/v1/availability
GET  /public/v1/bookings
POST /public/v1/bookings
GET  /public/v1/bookings/{bookingId}
PATCH /public/v1/bookings/{bookingId}
GET  /public/v1/bookings/{bookingId}/cancellation-context
POST /public/v1/bookings/{bookingId}/cancel
GET  /public/v1/finance/invoices
GET  /public/v1/finance/clients/{clientId}/invoices
GET  /public/v1/finance/invoices/{invoiceId}
GET  /public/v1/finance/invoices/{invoiceId}/pdf
POST /public/v1/finance/invoices/{invoiceId}/send-reminder
POST /public/v1/finance/invoices/{invoiceId}/resend
GET  /public/v1/finance/payments
GET  /public/v1/finance/payments/{paymentId}
GET  /public/v1/finance/payment-requests
GET  /public/v1/finance/payment-requests/{paymentRequestId}
POST /public/v1/finance/payment-requests
POST /public/v1/finance/payment-requests/{paymentRequestId}/cancel
GET  /public/v1/finance/chargebacks
GET  /public/v1/finance/chargebacks/{chargebackId}
GET  /public/v1/finance/products
GET  /public/v1/finance/clients/{clientId}/products
GET  /public/v1/finance/clients/{clientId}/products/{clientProductId}
GET  /public/v1/finance/clients/{clientId}/payment-methods/bank-accounts
GET  /public/v1/finance/membership-products
GET  /public/v1/finance/subscriptions
GET  /public/v1/finance/subscriptions/{subscriptionId}
POST /public/v1/finance/subscriptions/{subscriptionId}/pause-request
POST /public/v1/finance/subscriptions/{subscriptionId}/cancel-request
POST /public/v1/finance/clients/{clientId}/memberships
GET  /public/v1/finance/clients/{clientId}/credits
GET  /public/v1/finance/clients/{clientId}/credit-mutations
POST /public/v1/finance/clients/{clientId}/credits/{creditId}/adjust
POST /public/v1/finance/clients/{clientId}/products
POST /public/v1/finance/clients/{clientId}/products/{clientProductId}/revoke
GET  /public/v1/forms
GET  /public/v1/forms/{formId}
POST /public/v1/clients/{clientId}/intake-assignments
GET  /public/v1/clients/{clientId}/intake-assignment
GET  /public/v1/clients/{clientId}/intake/submission
GET  /public/v1/clients/{clientId}/checkups
GET  /public/v1/clients/{clientId}/checkups/{settingId}/status
GET  /public/v1/clients/{clientId}/checkups/submissions
POST /public/v1/clients/{clientId}/checkups/{settingId}/cancel
POST /public/v1/clients/{clientId}/checkups
GET  /public/v1/clients/{clientId}/measurements/types
GET  /public/v1/clients/{clientId}/measurements/entries
POST /public/v1/clients/{clientId}/measurements/entries
PATCH /public/v1/clients/{clientId}/measurements/entries/{entryId}
PATCH /public/v1/clients/{clientId}/measurements/entries/{entryId}/archive
GET  /public/v1/clients/{clientId}/measurements/summary
GET  /public/v1/clients/{clientId}/progress-photos
GET  /public/v1/clients/{clientId}/progress-photos/{progressPhotoId}
GET  /public/v1/clients/{clientId}/habits
GET  /public/v1/clients/{clientId}/habits/entries
POST /public/v1/clients/{clientId}/habits/{habitId}/entries
PATCH /public/v1/clients/{clientId}/habits/entries/{entryId}
PATCH /public/v1/clients/{clientId}/habits/entries/{entryId}/archive
GET  /public/v1/clients/{clientId}/goals
PATCH /public/v1/clients/{clientId}/goals
GET  /public/v1/clients/{clientId}/document-folders
GET  /public/v1/clients/{clientId}/documents
POST /public/v1/clients/{clientId}/documents/links
PATCH /public/v1/clients/{clientId}/documents/{documentId}
PATCH /public/v1/clients/{clientId}/documents/{documentId}/archive
GET  /public/v1/reports/attendance-summary
GET  /public/v1/reports/revenue-summary
GET  /public/v1/reports/retention-summary
GET  /public/v1/webhooks
POST /public/v1/webhooks
GET  /public/v1/webhooks/{id}
PATCH /public/v1/webhooks/{id}
DELETE /public/v1/webhooks/{id}
POST /public/v1/webhooks/{id}/test
GET  /public/v1/webhooks/deliveries
GET  /public/v1/webhooks/deliveries/{id}
GET  /public/v1/health

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

Route families

Current v1 scope

Response shape

Rate limits

​Route families

​Current v1 scope

​Response shape

​Rate limits

Route families

Current v1 scope

Response shape

Rate limits