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`
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 `100`, 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: upload, delete, folder mutation, signed document download URLs, raw media, provider metadata, message IDs, or file contents.

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

Link external document metadata

Update document metadata

Archive document metadata

​List document folders

​List documents

​Link external document metadata

​Update document metadata

​Archive document metadata

List document folders

List documents

Link external document metadata

Update document metadata

Archive document metadata