Skip to main content
Resource endpoints expose the fields documented in their response schemas. 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.

Response fields and privacy

Use each endpoint’s documented response fields. Fields available in the FITsociety dashboard, MCP server, or a payment provider are not necessarily available through the Public API. The Public API omits the following sensitive data unless an endpoint explicitly documents a masked, derived, or authorized value: Use the documented fields for protected resources. Examples include pdfAvailable instead of pdfLink, a short-lived downloadUrl instead of a storage key, and masked bank-account identifiers instead of full account details. Scopes that expose health data (measurements, progress summaries and photos, intakes, checkups, form assignments, habits, goals, documents) or private communication (messages, conversations, client notes) are consent-gated. They can only be assigned to an API client whose creating coach accepted the matching consent (consents.healthData or consents.privateCommunication), and at runtime the API returns 403 scopes.health_consent_required or 403 scopes.private_communication_consent_required when the stored consent is missing. GET /public/v1/scopes marks these scopes with a requiresConsent field. See Authentication.

Compatibility policy

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

Base URL

Authentication

Resource endpoints require:
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: Example:
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: Example:

Error key families

error.key values come in two families, both stable: Treat both families the same way: match on the exact key string. The complete key reference is on the error reference page. 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, diagnostic context, or raw records.

Idempotency

Bearer write requests require an Idempotency-Key header:
Idempotency applies to POST, PUT, PATCH, and DELETE resource requests. The key is scoped to the authenticated company and Public API client. 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: 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: Every authenticated resource response includes rate-limit data in meta.rateLimit and rate-limit headers: Rate-limit response:

Pagination fields

List endpoints use 1-based pagination unless explicitly documented otherwise. Public collection pages default to 10 and clamp sizes above 100 to 100. Cursor and offset endpoints retain their existing continuation fields.

Date and time rules

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:
Send units in their own documented field.

Object ID rules

IDs are 24-character hexadecimal 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

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 are not included in the response.

Collection pagination transition

This release intentionally changes existing v1 list defaults to 10 and the hard page maximum to 100. Previous controllers independently used 100/500, 25, 50, or complete arrays. There is no new v2 route and omitted pagination is no longer an instruction to return all tags or custom field definitions. Deploy updated consumers before releasing this backend policy. Existing item fields, collection keys, permissions, ownership checks and stable record IDs are retained. Make and Zapier polling follow multiple pages to retain the newest 500-record polling horizon. Selectors and n8n return-all operations follow metadata until completion or their documented consumer safety budget. A third-party consumer that ignores continuation metadata must be updated; it cannot be guaranteed a complete import after this transition. The finance product catalog has a deterministic order by product type, stored name, and ID, so every page can be read directly from the database. Localized names still appear in the DTO; translation changes do not reorder earlier pages. Recent-client IDs remain company relationship IDs and recent-booking IDs remain booking IDs. Cursor endpoints keep their cursor contracts with the same 10/100 page widths. Existing cursor formats are preserved; owned public records have no artificial page-count ceiling. Shared public workout catalogue page eleven is rejected with a validation error. Pagination metadata does not advertise pages beyond ten. This is a per-query browse bound, not an account-wide download quota. Public API rate limits still apply. This release changes only Public API v1: ordinary app and MCP responses, limits, ordering, totals, cursor formats and schema definitions remain unchanged.