Skip to main content

Upload & Edit

Upload and edit without setting up a storage connection. Send one Office file from your backend and use browser.openUrl from the response to open the document in the user’s browser.

You need a Developer Console API Key and one supported Office file. If you do not have a key yet, start with the Prepare an API Key. Keep the key in your backend, never in browser code.

The maximum upload size is 100 MB (104,857,600 bytes, 100 MiB). Supported types are doc, docx, odt, xls, xlsx, ods, ppt, pptx, and odp. The file bytes must carry the OOXML/ODF ZIP or legacy OLE container signature that matches the extension family; renaming arbitrary bytes does not create a valid Office file. Temporary uploads are not a document archive.

Save and download through the API

After opening, call api.downloadUrl with the creating API Key to retrieve file bytes. Editor sessions also provide api.saveUrl for POST requests. Neither operation is available after the document closes.

Workflow​

  1. From your backend, send multipart/form-data with a file part and a request part containing clientType: "BROWSER" and mode: "EDITOR". Set the request part’s Content-Type to application/json. Choose VIEWER for read-only access.
  2. Open browser.openUrl in the intended user's browser.
  3. The user edits and saves the document inside Office.
  4. Your backend calls api.statusUrl to check the last reported document state. If you poll, limit the frequency and total wait.
  5. Before the user closes the document, your backend can POST to api.saveUrl to save or GET api.downloadUrl to receive the file bytes. To save and then download, wait for data.saved: true before requesting the download.
curl --fail-with-body \
  -X POST https://api.thinkfree.com/api/office/v1/client-sessions \
  -H "Authorization: Bearer tfoak-replace-with-your-key" \
  -F "file=@./sample.docx" \
  -F 'request={"clientType":"BROWSER","mode":"EDITOR","fileDisplayName":"customer-proposal.docx","userId":"user-1042","docId":"upload-2026-0081"};type=application/json'

fileDisplayName is optional when the multipart file already has a filename. It sets the name shown in Office, and its extension selects the document app. Use an extension that matches the file content. The request part must not include storageId or documentPath.

The example identifies the application user as user-1042 and this uploaded copy as upload-2026-0081. Replace these with IDs mapped to your own records. Keep the user's ID across uploads, but give a separately uploaded copy its own document ID. Each upload creates a separate temporary source file; matching names or contents do not establish the same document identity. This API does not support reopening a previous upload by docId.

userId and docId are optional. Omitting them does not preserve user or document identity across independent sessions. See ID reuse and omission rules. Use Bring Your Own Storage when users must repeatedly open or co-edit the same stored document.

Response​

A successful request returns HTTP 201 Created. The example below is an Editor session: browser.openUrl opens Office, and the api URLs allow your backend to check status, save, and download. Viewer responses omit api.saveUrl:

{
  "success": true,
  "code": 0,
  "codeDescription": "SUCCESS",
  "data": {
    "clientSessionId": "9169250d-5328-4d45-844b-9a37cb52f7ac",
    "clientType": "BROWSER",
    "documentSourceType": "UPLOAD",
    "documentLifecycleId": "0d102ee8-cbdd-4667-a5cf-f2e3a1007927",
    "mode": "EDITOR",
    "status": "CREATED",
    "creditsCharged": 0,
    "createdAt": "2026-08-11T10:00:00Z",
    "browser": {
      "openUrl": "https://office.developers.thinkfree.com/cloud-office/api/open-document?ticket=<ticket>",
      "openUrlExpiresAt": "2026-08-11T10:05:00Z"
    },
    "api": {
      "statusUrl": "https://api.thinkfree.com/api/office/v1/client-sessions/9169250d-5328-4d45-844b-9a37cb52f7ac",
      "saveUrl": "https://api.thinkfree.com/api/office/v1/client-sessions/9169250d-5328-4d45-844b-9a37cb52f7ac/save",
      "downloadUrl": "https://api.thinkfree.com/api/office/v1/client-sessions/9169250d-5328-4d45-844b-9a37cb52f7ac/download"
    }
  }
}

documentSourceType is UPLOAD because this client session was created through Upload & Edit. It describes where the document came from, not the selected mode.

Save As is not available

Upload & Edit cannot save the document as a new file in another storage.

The ticket placeholders represent the short-lived values returned by the API. Do not replace them yourself or append the API Key to an Office URL. Use browser.openUrl to open the document; each ticket can be used once. See the API reference for every response field.

Creating links does not deduct Credits (creditsCharged: 0). Each successful open costs 5 Credits in viewer mode or 10 Credits in editor mode; failed opens are not charged. Link creation requires capacity for 5 Credits with VIEWER or 10 Credits with EDITOR, including enabled paid overage within its limit. Insufficient capacity returns HTTP 402 / 4020 INSUFFICIENT_CREDIT.

Try it​

Enter a revocable test API Key, choose an Office document, and submit the form. A successful response enables buttons for opening the selected mode and checking the last reported state. The form demonstrates opening and status lookup. Use the save and download API examples for backend file operations. Need a key? Sign in to Developer Console and create one under API Keys.

Interactive API Explorer

Upload a document and open Office

Not saved
The API Key is not saved. This form keeps it only in this tab's memory and never writes it to browser storage. Use a revocable test key because it remains visible in your browser's network inspector, and call the API from a trusted backend in production.

The key must begin with tfoak-.

Enter a test API Key and choose an Office document.

Open the editor in a browser​

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.

Keep the API Key and the upload request on your backend. Your backend sends the Office URL to the intended signed-in user’s browser. The browser opens that URL when the user selects the open button. In the form above, select Open editor for editing or Open viewer for the VIEWER session you requested. Open the URL promptly: it is a bearer capability and its launch ticket currently expires 5 minutes after it is issued. Deliver it only to the intended signed-in user, and do not put it in logs, analytics, support messages, or persistent browser storage.

The browser opens the Office URL without an API Key header. Your backend calls api.statusUrl with the exact API Key that created the session. Another key from the same account cannot access this session.

Check status from your backend. Replace the example ID with clientSessionId from the upload response and use the same API Key that created the session.

curl --fail-with-body \
  https://api.thinkfree.com/api/office/v1/client-sessions/YOUR_CLIENT_SESSION_ID \
  -H "Authorization: Bearer tfoak-replace-with-your-key"

lastSavedAt records the most recent successful save event received from Office. It does not prove that all edits currently visible in the editor have been saved.

Expected result​

Thinkfree Office opens the uploaded document in the selected mode. Your backend can read the last reported state with the creating API Key. Status remains available until closedAt plus 1 hour. If Office has not reported a successful close, the deadline is documentOpenedAt plus 12 hours; before a successful open, it is createdAt plus 12 hours.

The save/download endpoints check document state and access deadlines. See the lifetime comparison.

After the form and example work, use the Cloud Office API reference for every multipart field, response property, lifecycle status, and error code. For durable documents that remain in your own storage, use Bring Your Own Storage.