Cloud Office API

Your backend requests a document URL; the user views or edits the document in their browser. Thinkfree operates the Office server. Your application calls the REST API directly with its HTTP client; no Cloud Office client package is required.

The API creates a browser client session and reports Office events. The user can save changes inside Office. Save and download are available after a successful open and before the document closes.

Before you call the API

1. Follow Prepare an API Key to create a key.
2. Store the key on your backend. The examples below read it from THINKFREE_API_KEY in your server environment.
3. Choose a document in an active Storage, or upload one file with Upload & Edit.
4. Authenticate the user in your application and check that the user may access the requested document before requesting a URL.

Keep the API Key on your server

Do not put the key in browser JavaScript, a mobile app, document URLs, source control, or logs. An API Key identifies your Developer Console account; it does not check your application's individual users or their document permissions.

Authentication and responses

The base URL is https://api.thinkfree.com. Send the following header on every API request:

Authorization: Bearer tfoak-replace-with-your-key

A successful JSON response contains { "success": true, "code": 0, "codeDescription": "SUCCESS", "data": { ... } }. Read endpoint results from data. For failures, check the HTTP status and numeric code; use errorMessage to explain what failed. Do not compare message wording to decide application behavior. See response fields and error codes.

Browser interaction and backend API calls

Create a session at POST /api/office/v1/client-sessions. Send JSON for a storage document, or multipart with file and a request part with Content-Type application/json for an upload. The browser opens browser.openUrl; your backend calls api.statusUrl with the exact API Key that created the session. The api group also contains save/download endpoints for backend API calls. Office's own Save and Download buttons are separate browser actions.

Prepare user and document IDs

Before creating a session, read userId and docId from the mappings your backend keeps for the user and document. Reuse the same value for the same user or document, and give different users and documents different values. A person's display name or email and a file's display name are not identity keys.

Both fields are optional, but omitting them does not retain user or document identity across independent sessions. A new clientSessionId identifies each successful creation request. See ID roles and reuse examples before connecting repeated opens or co-editing.

1. Request a document URL

Open a document in connected storage

List the storages owned by your API Key account:

curl --fail-with-body \
  https://api.thinkfree.com/api/office/v1/storages \
  -H "Authorization: Bearer $THINKFREE_API_KEY"

Select an ACTIVE storage and pass its permanent storageId, along with the document's path relative to that storage. The storage's editable name is not its API identifier.

curl --fail-with-body \
  https://api.thinkfree.com/api/office/v1/client-sessions \
  -H "Authorization: Bearer $THINKFREE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clientType": "BROWSER",
    "mode": "EDITOR",
    "storageId": "74a73536-3024-48c2-a850-76cf7872323f",
    "documentPath": "proposals/proposal-2026-0042.docx",
    "userId": "user-1042",
    "docId": "proposal-2026-0042",
    "userDisplayName": "Alex Kim",
    "language": "en_US"
  }'

Replace the storage ID and path with your values. In this example, Alex always uses user-1042, and this proposal uses proposal-2026-0042 on every open. Another collaborator uses their own userId with the same document ID and path.

userDisplayName, userEmail, and userAvatarUrl are optional profile information. For userAvatarUrl, use a public HTTPS image URL readable by anyone without login, authentication headers, or authentication cookies. This Beta field does not yet set the Office profile icon.

Office saves the document to the connected storage. Your backend can also call api.saveUrl or api.downloadUrl after a successful open and before the document closes.

Upload a file instead

Upload & Edit requires no storage setup. Send multipart data and let your HTTP client set its boundary:

curl --fail-with-body \
  https://api.thinkfree.com/api/office/v1/client-sessions \
  -H "Authorization: Bearer $THINKFREE_API_KEY" \
  -F "file=@./sample.docx" \
  -F 'request={"clientType":"BROWSER","mode":"EDITOR","userId":"user-1042","docId":"upload-2026-0081","userDisplayName":"Alex Kim"};type=application/json'

Here upload-2026-0081 identifies the uploaded copy, while user-1042 still identifies Alex. A separately uploaded copy needs a separate document ID; matching filenames do not establish that it is the stored proposal or an earlier uploaded document.

Both request formats return HTTP 201. Inside data, read clientSessionId, mode, browser.openUrl, browser.openUrlExpiresAt, api.statusUrl, and api.downloadUrl. EDITOR sessions also return api.saveUrl. See the upload guide for supported files, size limits, and a complete response example.

2. Open the selected URL in the browser

Send the returned browser.openUrl to the intended signed-in user. The browser opens this URL directly or in your Office iframe, without an API Key header. Each URL contains a single-use ticket that currently expires after 5 minutes. Request the URL when the user is ready to open the document. Keep it out of logs, analytics, and support messages.

If the initial ticket expires or has already been used, request a new browser client session. For Upload & Edit, that means uploading the file again. The API does not provide a way to recover earlier edits by resubmitting the file or its docId.

Choose mode when creating the session. Select EDITOR if the user needs to edit. The API does not change an existing Viewer session to Editor.

In EDITOR mode, the user can edit for up to 12 hours from document opening. After 12 hours, the user can no longer edit in that session. This limit is separate from the 5-minute deadline for opening the URL.

3. Read the last reported status

Call the returned api.statusUrl from your backend with the exact API Key that created the session. Another key from the same account cannot access it. Replace the example ID below:

curl --fail-with-body \
  https://api.thinkfree.com/api/office/v1/client-sessions/YOUR_CLIENT_SESSION_ID \
  -H "Authorization: Bearer $THINKFREE_API_KEY"

status reports CREATED, OPEN, FAILED, or CLOSED. lastSavedAt and saveCount describe successful save events received from Office. This is the last reported state, not a real-time check of the browser or proof that all current edits have been saved. If you poll, limit both the frequency and total wait; an unchanged result alone does not prove failure.

4. Save or download through the API

The response includes api.downloadUrl for both document sources and api.saveUrl for EDITOR sessions. After a successful open, POST to api.saveUrl to save an Editor document or GET api.downloadUrl to receive document bytes. Use the same API Key that created the session. Neither operation is available after closing or after the 12-hour operation window.

The endpoints already check the creating API Key, document state, storage availability, and access deadline. A Viewer cannot use the save endpoint. See the API reference for access conditions and response formats.

Which expiration applies?

Item	Availability
browser.openUrl	Use once, before browser.openUrlExpiresAt. This is the opening deadline only.
Editor session	Editing is available for up to 12 hours from document opening. After that, the user cannot edit in that session.
api.statusUrl	Until closedAt + 1 hour. Without a successful close, until documentOpenedAt + 12 hours; without a successful open, until createdAt + 12 hours.
Save/download APIs	Requests require a successful open. They are rejected after a successful close is reported or at documentOpenedAt + 12 hours.
API Key	Must be active for every API call. Key expiry and revocation are independent of these deadlines.

documentOpenedAt and closedAt are event times reported by Office. They are not the times Developers received those events. Developers checks deadlines when it receives an API call. Temporary uploads are not an archive. See the complete field definitions.

Credits for document opening

Creating links does not deduct Credits (creditsCharged: 0). The API checks capacity for 5 Credits (VIEWER) or 10 Credits (EDITOR) when creating the initial URL. A successful Viewer open costs 5 Credits; a successful Editor open costs 10. Failed opens are not charged.

Capacity includes enabled paid overage within its allowed limit. Insufficient capacity returns HTTP 402, code 4020 INSUFFICIENT_CREDIT. Check balances and expiration under Credits, and subscription or overage settings under Billing.

API endpoints

Method	Endpoint	Purpose
GET	/api/office/v1/storages	List account-owned storages; omit storage secrets from the response
POST	/api/office/v1/client-sessions	Create a session from storage (JSON) or an uploaded file (multipart)
GET	/api/office/v1/client-sessions/{clientSessionId}	Read the last reported document state
POST	/api/office/v1/client-sessions/{clientSessionId}/save	Save an Editor document
GET	/api/office/v1/client-sessions/{clientSessionId}/download	Download the current document

See the status API response fields and access conditions.

Try it

The explorer keeps the test key only in this tab's memory. Use a revocable test key. Your production application must send these requests from its backend.

Interactive API Explorer

Call the Cloud Office API

Not saved

Use a revocable test key. This page keeps it only in this tab's memory and never writes it to browser storage, but the value is still visible in your browser's network inspector. Production applications must call the API from a trusted backend.

API Key

The key must begin with tfoak-.

01 · Discover

List storage connections

Returns only non-secret connection summaries owned by this key's account.

GET /api/office/v1/storages

02 · Open a document

Create browser client session

Use an active storage connection, or upload one short-lived document without creating a connection.

Open modeViewer (read only)Editor (edit and save)

Storage connectionDocument path

Client session options (optional)

Optional values are sent to Office only when provided. If docId is omitted, Developers assigns a new document ID for the session. Office uses its configured language and skin when those values are omitted. For connected-storage co-editing, use the same docId suffix for the same document and a different stable userId for each participant.

User IDDocument ID suffixLanguageSkin

POST /api/office/v1/client-sessions

Enter a test API Key to enable the examples.