Create document URLs

To open a document from a registered storage adapter, use the Office open endpoint. First, start Self-hosted Office. This example uses port 8080 and the preconnected Host Storage adapter host-storage.

http://localhost:8080/cloud-office/api/{ADAPTER_NAME}/{DOCUMENT_PATH}/open
  ?app={APP_MODE}
  &user_id={USER_ID}
  &docId={UNIQUE_DOCUMENT_ID}

Choose an editor or viewer

Choose an editor to edit and save documents, or a viewer to read them without editing. Set the URL's app value for the document type and intended use.

Document extensions	Editor app value	Viewer app value
DOC, DOCX, ODT	WORD_EDITOR	WORD_VIEWER
XLS, XLSX, ODS	CELL_EDITOR	CELL_VIEWER
PPT, PPTX, ODP	SHOW_EDITOR	SHOW_VIEWER
PDF	-	PDF_VIEWER

For example, use app=WORD_VIEWER in the same open URL to open a Word document in the viewer. Specify the adapter name and document path in the same way as for the editor. PDF documents open only in the viewer with app=PDF_VIEWER; there is no PDF editor.

Encode each path segment as UTF-8 URL data, preserving / between directories. Set docId to a URL-safe ID identifying the document in Office. Do not use an untrusted filesystem path directly as the document ID.

Example for /home/thinkfree/docs/contracts/Proposal 2026.docx:

http://localhost:8080/cloud-office/api/host-storage/contracts/Proposal%202026.docx/open?app=WORD_EDITOR&user_id=local-user&docId=contract-2026-001

Create URLs in JavaScript

The following function creates an editor URL for the file extension.

const editorMode = {
  doc: "WORD_EDITOR", docx: "WORD_EDITOR", odt: "WORD_EDITOR",
  xls: "CELL_EDITOR", xlsx: "CELL_EDITOR", ods: "CELL_EDITOR",
  ppt: "SHOW_EDITOR", pptx: "SHOW_EDITOR", odp: "SHOW_EDITOR",
};

export function createOfficeUrl(baseUrl, adapterName, documentPath, userId = "local-user") {
  // Keep directory separators while encoding every untrusted segment.
  const encodedPath = documentPath.split("/").map(encodeURIComponent).join("/");
  const extension = documentPath.split(".").pop().toLowerCase();
  const app = editorMode[extension];
  if (!app) throw new Error(`Unsupported document type: ${extension}`);

  // A unique ID keeps this open request separate from other editing sessions.
  const docId = crypto.randomUUID().replaceAll("-", "");
  const query = new URLSearchParams({app, user_id: userId, docId});
  const encodedAdapter = encodeURIComponent(adapterName);
  return `${baseUrl.replace(/\/$/, "")}/cloud-office/api/${encodedAdapter}/${encodedPath}/open?${query}`;
}

The example below returns a URL that opens the built-in Word sample in the preconnected Host Storage adapter. Run it in a browser JavaScript module or add it to application code that uses the function above. If you mounted your own directory, replace the path with an actual file path.

const url = createOfficeUrl("http://localhost:8080", "host-storage", "sample.docx");
console.log(url);

To open the same Word sample in the viewer, change app in the generated URL and assign a new docId.

const viewerUrl = new URL(url);
viewerUrl.searchParams.set("app", "WORD_VIEWER");
viewerUrl.searchParams.set("docId", crypto.randomUUID().replaceAll("-", ""));
console.log(viewerUrl.href);

Verify the result

1. Create an editor URL for a file under /home/thinkfree/docs.
2. Open the URL in your browser.
3. Edit and save the open document.
4. Check that the original document was updated.

To use an editor operated by Thinkfree without running Office yourself, see the Cloud Office API reference for short-lived viewer and editor URLs returned for account-owned storage connections.