Documents

Documents have a dedicated section in the API Reference. The current Public API operates on documents belonging to a specific client in the authenticated company.

Action	Endpoint	Scope
List client folders	`GET /public/v1/clients/{clientId}/document-folders`	`documents:read`
Create client folder	`POST /public/v1/clients/{clientId}/document-folders`	`documents:write`
Prepare binary upload	`POST /public/v1/clients/{clientId}/documents/uploads`	`documents:write`
Publish binary upload	`POST /public/v1/clients/{clientId}/documents/uploads/{uploadId}/complete`	`documents:write`
List client documents	`GET /public/v1/clients/{clientId}/documents`	`documents:read`
Register an external document	`POST /public/v1/clients/{clientId}/documents/links`	`documents:write`
Update document metadata	`PATCH /public/v1/clients/{clientId}/documents/{documentId}`	`documents:write`
Archive document metadata	`PATCH /public/v1/clients/{clientId}/documents/{documentId}/archive`	`documents:write`

All writes require an Idempotency-Key header. Registering a document stores an existing HTTP(S) URL; it does not upload a file. Archiving hides the document from Public API and company MCP document listings; it does not delete the document or its file from FITsociety or the external host. Company-wide document listing and management are not currently exposed through the Public API. Client routes do not provide a company-wide document collection.

List document folders

GET /public/v1/clients/{clientId}/document-folders
Authorization: Bearer <access_token>

Required scope: documents:read Response fields:

Field	Type	Nullable	Description
`data.page`	integer	no	Current page.
`data.limit`	integer	no	Page size after cap.
`data.total`	integer	no	Total matching folders.
`data.totalPages`	integer	no	Total pages.
`data.hasNextPage`	boolean	no	Next page availability.
`data.hasPrevPage`	boolean	no	Previous page availability.
`data.folders[].folderId`	string	no	Folder ID.
`data.folders[].name`	string	no	Folder name.
`data.folders[].clientId`	string	yes	Client ID.
`data.folders[].sharedWithAllClients`	boolean	no	Shared-default flag.
`data.folders[].createdAt`	string	yes	Creation timestamp.

List documents

GET /public/v1/clients/{clientId}/documents?folderId={folderId}
Authorization: Bearer <access_token>

Required scope: documents:read Validation:

Parameter	Type	Required	Rule
`page`	integer	no	Minimum `1`.
`limit`	integer	no	Default `10`, maximum `100`.
`folderId`	string	no	Valid folder ObjectId.

Response fields:

Field	Type	Nullable	Description
`data.page`	integer	no	Current page.
`data.limit`	integer	no	Page size after cap.
`data.total`	integer	no	Total matching documents.
`data.totalPages`	integer	no	Total pages.
`data.hasNextPage`	boolean	no	Next page availability.
`data.hasPrevPage`	boolean	no	Previous page availability.
`data.documents[].documentId`	string	no	Document ID.
`data.documents[].name`	string	no	Document name.
`data.documents[].mimeType`	string	no	MIME type.
`data.documents[].fileSize`	string	no	File size as stored.
`data.documents[].folderId`	string	yes	Folder ID.
`data.documents[].clientId`	string	yes	Client ID.
`data.documents[].sharedWithAllClients`	boolean	no	Shared-default flag.
`data.documents[].addedByRole`	string	no	Uploader role.
`data.documents[].createdAt`	string	yes	Creation timestamp.

Not exposed in v1: delete, folder rename/delete, nested folders, signed document download URLs, raw media, provider metadata, message IDs, or file contents.

Create a client folder

Send POST /public/v1/clients/{clientId}/document-folders with {"name":"Progress"}, Bearer authentication, documents:write, health consent, and an Idempotency-Key. The response is 201 with data.folder using the folder fields above. Names must be non-empty and at most 160 characters. Folders are client-owned and flat; parentFolderId and parentId are rejected.

Upload and publish a file

Call POST /public/v1/clients/{clientId}/documents/uploads with fileName, mimeType, sizeBytes (an integer), optional name, and optional folderId. The folder must belong to this client and must not be a shared/default folder.
Read data.upload: uploadId, method (POST), url, expiresAt (UTC), and fields (an array of {name,value} entries). Using an HTTP client, send a multipart form to that URL with every field unchanged, followed by the binary file in a field named file. Do not send your FITsociety Bearer token to the upload endpoint. A prepared upload expires after 15 minutes.
After the file upload succeeds, call POST /public/v1/clients/{clientId}/documents/uploads/{uploadId}/complete. An empty body is allowed. The response is 200 with data.document, using the document fields above. Only then does the document appear for the client.

Both FITsociety POST calls require documents:write, health consent and their own Idempotency-Key. Reuse a key only for the exact same request. If an upload fails validation, correct the problem and retry completion with a new key. Completion is also safe to repeat with a new key: it returns the same document. Replaying a preparation response does not extend its upload expiry. Supported file types:

Format	MIME type
PDF	`application/pdf`
TXT	`text/plain`
DOCX	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
XLSX	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
JPEG	`image/jpeg`
PNG	`image/png`

Extension and declared type must match. Maximum size is 26,214,400 bytes (25 MiB); empty files are rejected. Completion checks the actual byte count and declared MIME type. Retrying an upload cannot overwrite a published document. These checks do not inspect file contents or replace malware scanning. Expected errors include missing upload (404), inaccessible folder (404), expired/missing/in-progress upload (409), and size/type mismatch (400). Document lists still omit file contents and download URLs. Upload publication does not send email or chat messages.

curl -X POST "$FIT_API_BASE_URL/public/v1/clients/$CLIENT_ID/documents/uploads" \
  -H "Authorization: Bearer $FIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: progress-upload-prepare-001" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"progress.pdf","mimeType":"application/pdf","sizeBytes":12345}'

Use the exact byte count of your file. Transfer the binary file with all returned upload fields before completing. A successful preparation alone does not upload the file.

Link external document metadata

POST /public/v1/clients/{clientId}/documents/links
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope: documents:write This endpoint stores metadata for a document managed outside FITsociety. It does not upload binary files and does not expose raw download links in list/read responses. Request body:

Field	Type	Required	Rule
`name`	string	yes	Trimmed, maximum 160 characters.
`documentUrl` or `externalUrl`	URL string	yes	Must be an absolute `http` or `https` URL.
`mimeType` or `type`	string	no	Trimmed, maximum 120 characters. Defaults to `application/octet-stream`.
`fileSize`	string	no	Trimmed, maximum 40 characters.
`folderId`	ObjectId string	no	Folder must belong to the client, be company-shared, or be a shared default folder.

Validation:

Rule	Behavior
Client access	Client must belong to the authenticated company.
Coach context	The OAuth client must have a usable default coach context for attribution.
Folder access	Invalid or inaccessible folders return a document-folder error.
URL protocol	Non-HTTP(S) URLs are rejected.

Response fields:

Field	Type	Nullable	Description
`data.document.documentId`	string	no	Linked document ID.
`data.document.name`	string	no	Document name.
`data.document.mimeType`	string	no	MIME type.
`data.document.fileSize`	string	no	File size as stored.
`data.document.folderId`	string	yes	Folder ID.
`data.document.clientId`	string	yes	Client ID.
`data.document.sharedWithAllClients`	boolean	no	Shared-default flag.
`data.document.addedByRole`	string	no	Uploader role.
`data.document.createdAt`	string	yes	Creation timestamp.

curl -X POST "https://api.fitsociety.io/public/v1/clients/64b64c0f2f5f4c0012345678/documents/links" \
  -H "Authorization: Bearer $FITSOCIETY_ACCESS_TOKEN" \
  -H "Idempotency-Key: document-link-training-agreement-20260823" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Training agreement",
    "documentUrl": "https://files.example.com/agreements/jane-doe.pdf",
    "mimeType": "application/pdf",
    "fileSize": "182 KB",
    "folderId": "64b64c0f2f5f4c00123456e0"
  }'

const clientId = "64b64c0f2f5f4c0012345678";
const response = await fetch(
  `https://api.fitsociety.io/public/v1/clients/${clientId}/documents/links`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FITSOCIETY_ACCESS_TOKEN}`,
      "Idempotency-Key": "document-link-training-agreement-20260823",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Training agreement",
      documentUrl: "https://files.example.com/agreements/jane-doe.pdf",
      mimeType: "application/pdf",
      fileSize: "182 KB",
      folderId: "64b64c0f2f5f4c00123456e0",
    }),
  },
);

const body = await response.json();
if (response.status === 201) {
  console.log("Linked document", body.data.document.documentId);
}

import os
import requests

client_id = "64b64c0f2f5f4c0012345678"
response = requests.post(
    f"https://api.fitsociety.io/public/v1/clients/{client_id}/documents/links",
    headers={
        "Authorization": f"Bearer {os.environ['FITSOCIETY_ACCESS_TOKEN']}",
        "Idempotency-Key": "document-link-training-agreement-20260823",
    },
    json={
        "name": "Training agreement",
        "documentUrl": "https://files.example.com/agreements/jane-doe.pdf",
        "mimeType": "application/pdf",
        "fileSize": "182 KB",
        "folderId": "64b64c0f2f5f4c00123456e0",
    },
)
response.raise_for_status()

body = response.json()
if response.status_code == 201:
    print("Linked document", body["data"]["document"]["documentId"])

Response (201 Created):

{
  "data": {
    "document": {
      "documentId": "64b64c0f2f5f4c00123456e1",
      "name": "Training agreement",
      "mimeType": "application/pdf",
      "fileSize": "182 KB",
      "folderId": "64b64c0f2f5f4c00123456e0",
      "clientId": "64b64c0f2f5f4c0012345678",
      "sharedWithAllClients": false,
      "addedByRole": "coach",
      "createdAt": "2026-08-23T10:00:00.000Z"
    }
  },
  "meta": {
    "requestId": "req_0123456789abcdef",
    "rateLimit": { "limit": 10, "remaining": 8, "resetSeconds": 1 }
  }
}

Update document metadata

PATCH /public/v1/clients/{clientId}/documents/{documentId}
Authorization: Bearer <access_token>
Content-Type: application/json

Required scope: documents:write Allowed fields: name, documentUrl, externalUrl, mimeType, type, fileSize, and folderId. At least one field is required. The same name, URL, type, file-size, client, and folder validations as Link external document metadata apply. Response fields:

Field	Type	Nullable	Description
`data.document.documentId`	string	no	Document ID.
`data.document.name`	string	no	Document name.
`data.document.mimeType`	string	no	MIME type.
`data.document.fileSize`	string	no	File size as stored.
`data.document.folderId`	string	yes	Folder ID.
`data.document.clientId`	string	yes	Client ID.
`data.document.sharedWithAllClients`	boolean	no	Shared-default flag.
`data.document.addedByRole`	string	no	Uploader role.
`data.document.createdAt`	string	yes	Creation timestamp.

Archive document metadata

PATCH /public/v1/clients/{clientId}/documents/{documentId}/archive
Authorization: Bearer <access_token>

Required scope: documents:write Archive is a metadata-only soft archive. The document is excluded from Public API list responses after archiving. It does not delete a binary file from external storage. Response fields:

Field	Type	Nullable	Description
`data.document.documentId`	string	no	Document ID.
`data.document.archived`	boolean	no	Always `true` for successful responses.
`data.document.updatedAt`	string	yes	Update timestamp.

Start here

Public API guides

Access Devices

Resources

List document folders

List documents

Create a client folder

Upload and publish a file

Link external document metadata

Update document metadata

Archive document metadata

​List document folders

​List documents

​Create a client folder

​Upload and publish a file

​Link external document metadata

​Update document metadata

​Archive document metadata

List document folders

List documents

Create a client folder

Upload and publish a file

Link external document metadata

Update document metadata

Archive document metadata