Contracts, validation, and rate limits

The Public API is contract-first. Resource endpoints expose explicit DTO fields, not raw database documents. FITsociety may add fields to a response, but existing v1 fields are not renamed, removed, or changed to another type without a new API version.

DTO allowlist policy

Public API responses are built from explicit DTO allowlists. Adding a field to a MongoDB model, internal controller response, MCP tool result, provider payload, or coach app endpoint does not automatically add that field to the Public API. Every new Public API endpoint must document each returned field on its endpoint page. New response fields require a deliberate DTO change, Swagger update, Mintlify update, frontend plugin metadata update when relevant, and contract tests for sensitive-field omissions. The Public API does not expose these internal fields unless an endpoint page explicitly documents a safe masked or derived version:

Field category	Examples
Authentication secrets	Passwords, password hashes, access tokens, refresh tokens, API keys, client secrets, OAuth token hashes
Provider internals	Raw payment-provider payloads, webhook payloads, provider authorization headers, provider customer snapshots
Payment mandates	Full IBAN, full BIC, mandate objects, bank verification payloads
Storage internals	Raw S3 keys, private media paths, unsigned private file URLs
Health/provider provenance	Raw health provider source refs, derivation refs, suppression metadata, quality flags
Private communication	Chat message bodies, push tokens, unread-state internals, raw participant auth fields
Form internals	Objective medical/nutrition blocks, draft answers, media answer URLs, reminder email/chat bodies
Internal operations	Sentry context, stack traces, background job debug state, internal audit implementation details
Internal notes	Staff-only notes, deletion metadata, moderation state, hidden support context

When a public workflow needs a sensitive-derived value, return a purpose-built field instead. Examples: pdfAvailable instead of pdfLink, a short-lived downloadUrl instead of a storage key, and masked bank-account identifiers instead of full account details.

Compatibility policy

Change type	v1 behavior
Add a response field	Allowed without a version bump
Add an enum value	Allowed when the field is documented as extensible
Rename a response field	Not allowed in v1
Remove a response field	Not allowed in v1
Change a field type	Not allowed in v1
Make an optional field required in request bodies	Not allowed in v1
Make a required field optional in request bodies	Allowed
Add a new endpoint	Allowed

Clients should ignore unknown response fields. Clients should not depend on object key order.

Base URL

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

Authentication

Resource endpoints require:

Authorization: Bearer <access_token>

Tokens are issued by POST /public/v1/oauth/token using OAuth client credentials. Each token has explicit scopes. A request must include every scope required by the endpoint.

Resource response envelope

Bearer resource endpoints use the Public API envelope:

Field	Type	Nullable	Description
`data`	object, array, or `null`	no	Endpoint-specific response payload.
`meta.requestId`	string	no	Stable request identifier. Also returned as `X-Request-Id`.
`meta.rateLimit`	object	yes	Rate-limit state when the request passed through the Public API rate limiter.
`meta.rateLimit.limit`	integer	yes	Request limit for the current rate-limit window.
`meta.rateLimit.remaining`	integer	yes	Requests remaining in the current window.
`meta.rateLimit.resetSeconds`	integer	yes	Seconds until the current window resets.
`meta.rateLimit.retryAfterSeconds`	integer	yes	Seconds to wait before retrying; present on `429` responses.
`meta.idempotency.replayed`	boolean	yes	Present and `true` when a successful write response was replayed from an `Idempotency-Key`.

Example:

{
  "data": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPrevPage": false,
    "bookings": []
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": {
      "limit": 10,
      "remaining": 9,
      "resetSeconds": 1
    }
  }
}

OAuth token responses use the OAuth shape documented on the authentication page.

Error envelopes

Bearer resource authentication, scope, validation, rate-limit, and server errors use the Public API error envelope:

Field	Type	Nullable	Description
`error.code`	integer	no	HTTP status code.
`error.key`	string	no	Machine-readable error key.
`error.message`	string	no	Human-readable message.
`error.details`	object	yes	Additional validation details when available.
`meta.requestId`	string	no	Stable request identifier. Also returned as `X-Request-Id`.
`meta.rateLimit`	object	yes	Rate-limit state when available.
`meta.rateLimit.limit`	integer	yes	Request limit for the current rate-limit window.
`meta.rateLimit.remaining`	integer	yes	Requests remaining in the current window.
`meta.rateLimit.resetSeconds`	integer	yes	Seconds until the current window resets.
`meta.rateLimit.retryAfterSeconds`	integer	yes	Seconds to wait before retrying; present on `429` responses.

Example:

{
  "error": {
    "code": 422,
    "key": "validation.failed",
    "message": "The request body is invalid.",
    "details": {
      "field": "email",
      "reason": "invalid_email"
    }
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": {
      "limit": 10,
      "remaining": 8,
      "resetSeconds": 1
    }
  }
}

Do not build client logic from translated text. Use HTTP status, error.key, endpoint context, and documented validation rules. Error payloads do not include stack traces, raw provider payloads, token hashes, secrets, authorization headers, Sentry context, or database documents.

Idempotency

Bearer write requests require an Idempotency-Key header:

Idempotency-Key: <stable_request_key>

Idempotency applies to POST, PUT, PATCH, and DELETE resource requests. The key is scoped to the authenticated company and Public API client.

Rule	Behavior
Missing key on a write	`400 idempotency.required`
Key longer than 200 characters	`400 idempotency.invalid`
Same key, same method, same URL path/query, same body, already completed	Replays the stored successful response with `meta.idempotency.replayed=true`.
Same key, different method, URL path/query, or body	`409 idempotency.conflict`
Same key while the first request is still processing	`409 idempotency.in_progress`
Request returns `4xx` or `5xx`	The key is not completed and may be retried after the underlying issue is fixed.

Only successful 2xx and 3xx write responses are stored for replay. Use a new key for a new user action, and reuse a key only for retries of the exact same request.

Access-device contracts

/public/v1/access/* is intentionally separate from the OAuth resource contract. It uses device-key authentication and the FITsociety application envelope:

Field	Type	Nullable	Description
`status`	integer	no	HTTP status code.
`error`	boolean	no	`false` for access decisions, `true` for malformed requests.
`message`	string	no	Stable access message key.
`data`	object	yes	Access decision payload.

Access decisions return HTTP 200 for both allow and deny outcomes. Read data.allowed and data.reasonCode. Access validation has its own per-device rate limit and does not require Idempotency-Key.

Rate limits

Bearer resource calls are rate limited per Public API OAuth client:

Limit	Value
Window	1 second
Requests per window	10
Bucket key	OAuth client ID

Every authenticated resource response includes rate-limit data in meta.rateLimit and rate-limit headers:

Header	Type	Description
`RateLimit-Limit`	integer	Maximum requests in the current window.
`RateLimit-Remaining`	integer	Requests left in the current window.
`RateLimit-Reset`	integer	Seconds until the current window resets.
`X-RateLimit-Limit`	integer	Backward-compatible mirror of `RateLimit-Limit`.
`X-RateLimit-Remaining`	integer	Backward-compatible mirror of `RateLimit-Remaining`.
`X-RateLimit-Reset`	integer	Backward-compatible mirror of `RateLimit-Reset`.
`Retry-After`	integer	Only present on `429` responses. Seconds to wait before retrying.

Rate-limit response:

{
  "error": {
    "code": 429,
    "key": "rate_limit.exceeded",
    "message": "Too many Public API requests for this client."
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": {
      "limit": 10,
      "remaining": 0,
      "resetSeconds": 1,
      "retryAfterSeconds": 1
    }
  }
}

Pagination fields

List endpoints use 1-based pagination unless explicitly documented otherwise.

Field	Type	Nullable	Description
`page`	integer	no	Current 1-based page.
`limit`	integer	no	Page size after server caps are applied.
`total`	integer	no	Total matching records.
`totalPages`	integer	no	Number of pages, minimum `1`.
`hasNextPage`	boolean	no	Whether `page + 1` exists.
`hasPrevPage`	boolean	no	Whether `page - 1` exists.

Default and maximum limits differ per endpoint. The endpoint pages document the exact cap.

Date and time rules

Input type	Rule
Date-only fields	Use canonical `YYYY-MM-DD`.
Date-time fields	Use ISO 8601 with `Z` or an explicit offset.
Response date-times	UTC ISO strings when serialized by the API.
Timezone display	Clients are responsible for display conversion.

Range endpoints reject invalid dates, dateTo < dateFrom, and ranges above the documented maximum.

Numeric input rules

Public write endpoints accept JSON numbers for numeric fields. Measurement values also accept localized numeric strings such as "82,5" or "1.250,5". Numeric fields reject display strings with units or labels:

{
  "value": "82.5 kg"
}

Send units in their own documented field.

Object ID rules

IDs are MongoDB ObjectId strings. Invalid ID shape returns 400. Valid IDs that do not belong to the authenticated company or client relationship return 404 or 403 depending on the underlying access check. The Public API never accepts companyId from resource request bodies. The company is always derived from the Bearer token.

Short-lived download and booking tokens

Token or URL	Issuer	TTL	Validation
`availabilityToken`	`GET /public/v1/availability`	10 minutes	HMAC signature, company match, expiry, and live slot bookability on booking.
`invoicePdf.downloadUrl`	`GET /public/v1/finance/invoices/{invoiceId}/pdf`	15 minutes	Bearer scope, company scope, invoice access, existing `pdfLink`, and media signer when configured.
`progressPhoto.image.downloadUrl`	`GET /public/v1/clients/{clientId}/progress-photos*`	15 minutes by default	Bearer scope, client access, historical progress-photo grant, existing image URL, and media signer when configured.

Availability tokens are not reservations. Callers should submit the token to POST /public/v1/bookings quickly and handle stale-capacity errors. Invoice PDF URLs are read-only metadata for an existing PDF. The Public API does not generate missing PDFs on read endpoints. Progress photo URLs expose a signed or normalized media URL only. The raw storage URL, storage key, uploader actor IDs, dimensions, and file-size metadata remain internal.

Start here

Public API guides

Access Devices

DTO allowlist policy

Compatibility policy

Base URL

Authentication

Resource response envelope

Error envelopes

Idempotency

Access-device contracts

Rate limits

Date and time rules

Numeric input rules

Object ID rules

Short-lived download and booking tokens

​DTO allowlist policy

​Compatibility policy

​Base URL

​Authentication

​Resource response envelope

​Error envelopes

​Idempotency

​Access-device contracts

​Rate limits

​Pagination fields

​Date and time rules

​Numeric input rules

​Object ID rules

​Short-lived download and booking tokens

DTO allowlist policy

Compatibility policy

Base URL

Authentication

Resource response envelope

Error envelopes

Idempotency

Access-device contracts

Rate limits

Pagination fields

Date and time rules

Numeric input rules

Object ID rules

Short-lived download and booking tokens