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

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.

Encode each path segment as UTF-8 URL data, preserving / between directories. Generate a URL-safe docId for the editing session. Do not reuse an untrusted filesystem path as a session identifier.

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.