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
documents:read
Response fields:
List documents
documents:read
Validation:
Response fields:
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
SendPOST /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/uploadswithfileName,mimeType,sizeBytes(an integer), optionalname, and optionalfolderId. The folder must belong to this client and must not be a shared/default folder. - Read
data.upload:uploadId,method(POST),url,expiresAt(UTC), andfields(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 namedfile. 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 is200withdata.document, using the document fields above. Only then does the document appear for the client.
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:
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.
Example: deliver an onboarding PDF from Make
Use HTTP requests when your Make connector does not expose the upload operations. Choose the PDF for the assigned programme, then obtain its binary data and exact byte count before preparing the upload.-
Send a JSON request to prepare the upload:
Replace
12345with the actual file size in bytes. OmitfolderIdto place the document at the client’s document root. -
Send a multipart/form-data HTTP
POSTtodata.upload.url. Add one text form part for each entry indata.upload.fields, preserving itsnameandvalue. Add the PDF binary as a file part namedfile, after the text parts. Let the HTTP module generate the multipart boundary; do not manually set theContent-Typeheader. Use no FITsociety authentication on this request. -
After the transfer succeeds, publish the document:
Map
{uploadId}fromdata.upload.uploadIdin step 1. A successful response containsdata.document.documentId; the document is now available in the client’s Documents section. The 15-minute expiry applies to the upload authorization, not the published document. - Only after publication succeeds, send the welcome message through your existing conversation-message request. Document publication does not send that message automatically.
documents:write and health data consent;
documents:read is only needed if the scenario also lists documents or folders.
Link external document metadata
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.
The linked document appears in the client’s Documents section. Use a stable
HTTPS URL that the client can open. FITsociety does not copy the file from that
URL or extend its validity: if the external file is removed or the URL expires,
the link stops working. A temporary FITsociety download URL copied from another
client’s document is therefore unsuitable as a stable source. The Public API
does not expose a copy-from-document operation or stable download URLs for
existing FITsociety files. To publish the same PDF for another client, upload
the source file for that client using the flow above, or register a stable
externally hosted URL.
Request body:
Validation:
Response fields:
201 Created):
Update document metadata
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:
Archive document metadata
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: