> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fitsociety.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Public API Overview

> Use the FITsociety Public API for server-to-server integrations.

The FITsociety Public API lives under:

```txt theme={null}
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.

<Note>
  New here? The [Quickstart](/public-api/quickstart) walks you from creating
  OAuth credentials to your first successful API call in about 10 minutes.
</Note>

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](/access-devices/overview) | 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](/public-api/platform) |
| Company catalog | Company profile, facilities, policies, locations, coaches | [Company catalog](/public-api/company-catalog), [Coaches](/public-api/coaches) |
| Clients | CRM clients, custom fields, portal invites, timeline, notes | [Clients](/public-api/clients), [Client notes](/public-api/client-notes) |
| Communication | Direct and group chat conversations, messages, and participants | [Conversations](/public-api/conversations) |
| Calendar and bookings | Bookings, recurring bookings, events, event types/templates, tasks, availability | [Calendar and bookings](/public-api/calendar-bookings) |
| Finance | Products, invoices, transactions, payment requests, subscriptions, credits, chargebacks | [Finance](/public-api/finance) |
| Progress | Measurements, progress photos, habits, goals | [Measurements](/public-api/measurements), [Habits and goals](/public-api/habits-goals) |
| Forms | Create, update and archive form templates | [Forms](/public-api/forms) |
| Intakes | Assign intake forms and read submissions | [Intakes](/public-api/intakes) |
| Check-ups | Schedule, inspect and cancel check-ups | [Check-ups](/public-api/checkups) |
| Documents | Read and manage document metadata | [Documents](/public-api/documents) |
| Reporting | Attendance, revenue, and retention summaries | [Reports](/public-api/reports) |
| Webhooks | Outbound webhook subscriptions and delivery inspection | [Webhooks](/public-api/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/access-devices/overview) section for the
`/public/v1/access/*` response and auth contract. See the
[Webhooks](/public-api/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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.