What if an API call returns 405 Method Not Allowed?

This usually happens when the static openapi page uses relative paths and requests hit the static server port. Explicitly configure the backend server URL in Environment Setup.

What if an API call returns 401 Unauthorized?

End-to-end import and other authorized APIs require a token. Make sure your access token is valid and not expired.

What if it says no permission to access the document?

Make sure the new document permission is edit or the token matches the document owner, and the api parameter in the editor link points to the same backend.

Why does the test result flash and disappear?

Live Server may watch backend file writes and reload the page. The page automatically restores the last result from localStorage.

JitWord OpenAPI Docs — DOCX Import/Export · Template Batch Generation

Quick Start

From uploading a DOCX to opening the online editor, follow these steps for your first integration.

1. Get a TokenObtain a JWT via the login API or an existing session.

2. Configure URLsFill in the backend API URL and editor URL.

3. Upload & ImportCall the end-to-end import API to get a documentId.

4. Open the EditorOpen the online document via the returned link.

Environment Setup

Settings are saved to browser localStorage for repeated testing. When the static page runs on port 5500, you must explicitly configure the backend URL.

Backend server URL

Used to build /api/v1 requests.

Editor URL

Used to build document editor links.

Access token

Required for end-to-end import and private document access.

Imported document permission

Use private in production; edit is convenient for testing.

Editor links automatically carry token and api parameters so the editor talks to the same backend as the import API.

Authentication

APIs that require user identity expect a JWT in the request header; the server binds the document owner to the token.

Location	Format	Notes
Header	`Authorization: Bearer <token>`	Required by import, export, document list, document info, open document data, version list, revision and comment APIs.
Login allowlist	`IP / CIDR / Domain`	Admins can restrict register/login sources in the portal's Open Access panel; disabled or empty rules mean allow-all.
Same-origin session	`localStorage.jwt_token`	When this page is deployed on the same origin as the editor and no token is set manually, the editor session is reused automatically.
Editor link	`?token=<token>&api=<apiBase>`	The editor stores the session locally after opening and cleans the URL parameters.

Register & Login

The open auth APIs reuse the existing user system. A successful login returns a JWT used by all subsequent APIs.

POST

API	Request body	Notes
/api/v1/user/register	`{ "username": "demo", "password": "123456" }`	Returns a token on success; may be limited by the login allowlist.
/api/v1/user/login	`{ "username": "demo", "password": "123456" }`	Returns `data.token` on success.

Username

Password

curl -X POST "http://localhost:3002/api/v1/user/register" \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456"}'

curl -X POST "http://localhost:3002/api/v1/user/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"demo","password":"123456"}'

My Documents

Fetch documents owned by the current logged-in user. Regular users can only query their own documents.

GET

/api/v1/documents?filter=active&scope=mine

curl -X GET "http://localhost:3002/api/v1/documents?filter=active&scope=mine" \
  -H "Authorization: Bearer <token>"

DOCX Import & Create

Recommended integration API. After uploading a DOCX, the server parses it, creates a document, writes content, persists comments and returns a documentId.

POST

/api/v1/parse/docx-v2-import

Business value

Use cases

One-click Word import

Migrating contracts, official documents, proposals and knowledge bases.

Output

Online document ID

Open directly by appending it to the editor URL.

Permission model

Token binds owner

Supports private/read/edit access levels.

Request parameters

Field	Type	Required	Notes
file	file	Yes	DOCX file; the field name must be file.
publicPermission	string	No	private/read/edit. This test page defaults to edit.
name	string	No	Document name; defaults to the file name.

Choose a DOCX file

Click to select or drag a file here

DOCX

Document created

Open in the editor

curl -X POST "http://localhost:3002/api/v1/parse/docx-v2-import" \
  -H "Authorization: Bearer <token>" \
  -F "file=@demo.docx" \
  -F "publicPermission=edit"

Excel Import & Create

After uploading an XLSX, the server parses it into a sheet snapshot, creates a sheet document and returns a link that opens the Excel editor directly.

POST

/api/v1/parse/excel-v2-import

Business value

Use cases

One-click Excel import

Migrating spreadsheets, statistics reports and ledgers.

Output

Sheet document ID

Opens the /sheet/{documentId} editor page directly.

Data format

Univer snapshot

Reuses the existing sheet editing, saving and collaboration pipeline.

Request parameters

Field	Type	Required	Notes
file	file	Yes	Excel file; the field name must be file, .xlsx recommended.
publicPermission	string	No	private/read/edit. This test page defaults to edit.
name	string	No	Sheet name; defaults to the file name.

Choose an Excel file

Click to select or drag an .xlsx file here

Excel

Sheet created

Open in the Excel editor

curl -X POST "http://localhost:3002/api/v1/parse/excel-v2-import" \
  -H "Authorization: Bearer <token>" \
  -F "file=@demo.xlsx" \
  -F "publicPermission=edit"

High-fidelity DOCX Parsing

Parses without creating a document. Returns JitWord JSON, a parsing summary, a diagnostics report and Word comment info.

POST

/api/v1/parse/docx-v2

Capability	Notes
Structure parsing	Body text, headings, tables, lists, tab stops, styles and more.
Formula parsing	Supports OMML formula conversion.
Best for	Callers that store document content themselves or run parsing quality checks.

DOCX to HTML

Basic HTML parsing for lightweight previews or legacy integrations.

POST

API	Notes	Auth
/api/v1/parse/doc2html	Returns full HTML.	No login
/api/v1/parse/doc2html2	Paginated HTML parsing; returns docId and page count.	No login

Export DOCX by Doc ID

Export an existing online document as a Word file by its ID.

GET

/api/v1/export/docx/{docId}

Pick from my documents

Documents are queried with the current token.

Document ID

Export DOCX from JSON

Submit editor JSON content directly; the server generates and returns a Word file.

POST

/api/v1/export/docx

{
  "content": { "type": "doc", "content": [] },
  "filename": "demo.docx",
  "documentId": "optional, used to load comments"
}

This API suits system-to-system integration. For live testing, start with “Export DOCX by Doc ID”.

Export PDF by Doc ID

Render and export an existing online document as a PDF on the server.

GET

/api/v1/export/pdf/{docId}

Key point	Notes
Response	`application/pdf` byte stream; `Content-Disposition` carries a file name based on the document name.
Rendering	A server-side headless browser reuses the editor print pipeline; output matches the front-end “Print → Save as PDF”.
Latency	Synchronous response, usually a few seconds; large documents up to ~90s. Requires the rendering service (browser-service) online; behind a gateway, set read timeout ≥120s.
Common errors	404 document not found \| 403 no permission \| 429 export busy \| 503 rendering service down \| 504 rendering timeout.

Pick from my documents

Documents are queried with the current token.

Document ID

curl -X GET "http://localhost:3002/api/v1/export/pdf/<documentId>" \
  -H "Authorization: Bearer <token>" \
  -o export.pdf

Document Info

Fetch document metadata, header/footer, content presence and the current token's permission for a document by ID.

GET

/api/v1/documents/{documentId}

Field	Notes
id / name / type	Unique document ID, name and type; for regular documents type can be empty or doc.
ownerId / ownerName	Owner info, useful for ownership mapping in business systems.
publicPermission	`private`, `read` or `edit`.
headerFooter	Header/footer configuration; `null` if not configured.
hasContent	Whether real body content is stored on the server.
_userPermission	Current token's view, edit and comment permission for this document.

Document ID

curl -X GET "http://localhost:3002/api/v1/documents/<documentId>" \
  -H "Authorization: Bearer <token>"

Document Content Data

Unified content reading for documents, sheets and mind maps, reusing the existing document permission checks.

GET

/api/v1/open/documents/{documentId}/data

Field	Notes
document	Trimmed document metadata: id, name, type, owner, permission and timestamps.
permission	Current token's access permission for this document.
contentType	`doc`, `sheet` or `mindmap`.
content	Body data; `null` with an explicit message when there is no content yet.

Document ID

curl -X GET "http://localhost:3002/api/v1/open/documents/<documentId>/data" \
  -H "Authorization: Bearer <token>"

Version List

Fetch historical versions of a document (metadata only, no content), reusing the existing document permission checks.

GET

/api/v1/open/documents/{documentId}/versions?page=1&limit=20

Field	Notes
document	Trimmed document metadata (id, name, type, owner, permission, timestamps).
permission	Current token's access permission for this document.
versions	Versions in the current page, each with id, title, description, isAutoSave, author, createdAt, size; version body content is not included.
total / page / limit	Total count and pagination parameters.

Version body content is not returned by this API. Private documents are accessible only to owners and admins.

Document ID

curl -X GET "http://localhost:3002/api/v1/open/documents/<documentId>/versions?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

Revisions & Comments

Read review-related data of a document: the revisions API returns tracked-change marks in the document body (insertions/deletions/format changes, same scope as the editor review panel), and the comments API returns inline comment data; the live test requests both in parallel and merges the display.

GET

/api/v1/open/documents/{documentId}/revisions

/api/v1/comments?documentId={documentId}

API	Parameters	Notes
`/api/v1/open/documents/{documentId}/revisions`	None	Fetch tracked changes: multiple text fragments of the same revision are merged into one record with type, author, time, text fragments and a summary. Note this is different data from the version list or edit history.
`/api/v1/comments`	`documentId`	Fetch comments and replies for the document, including content, quoted text, author and extension fields.

Note: the revisions API uses the same permission policy as the open document data API (readable if you can access the document); private documents are readable only by the owner or an admin. Only doc-type documents support revisions.

Document ID

curl -X GET "http://localhost:3002/api/v1/open/documents/<documentId>/revisions" \
  -H "Authorization: Bearer <token>"

curl -X GET "http://localhost:3002/api/v1/comments?documentId=<documentId>" \
  -H "Authorization: Bearer <token>"

Create Document

Create a new document with optional initial content (ProseMirror JSON). Returns the document ID for subsequent save, export, or delete operations.

POST

/api/v1/open/documents

Request Body (JSON)

Field	Type	Required	Description
`name`	string	Yes	Document name
`type`	string	No	Document type: `doc` (default) / `sheet` / `mindmap`
`content`	object	No	Initial body (ProseMirror JSON, only effective when type=doc), e.g. `{"type":"doc","content":[...]}`
`publicPermission`	string	No	Document permission: `private` (default) / `read` (public read-only) / `edit` (public editable)

After creation, use GET /api/v1/open/documents/{id}/data to read the full content, or PUT /api/v1/open/documents/{id}/content to update it.

Document Name

Document Type

curl -X POST "http://localhost:3002/api/v1/open/documents" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Open API Test Doc","type":"doc"}'

Save Document Content

Write document body directly via REST (ProseMirror JSON). Suitable for programmatic content generation and bulk import scenarios.

PUT

/api/v1/open/documents/{documentId}/content

Request Body (JSON)

Field	Type	Required	Description
`content`	object	Yes	Standard ProseMirror JSON; top-level type must be `"doc"`, content is an array of nodes

Important: if the document is currently open in the online editor (active collaborative connections exist), the API returns 409 Conflict to prevent overwriting real-time edits. Ensure no users are editing before calling this endpoint.

Document ID

Content JSON

curl -X PUT "http://localhost:3002/api/v1/open/documents/<documentId>/content" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"content":{"type":"doc","content":[{"type":"paragraph","content":[{"type":"text","text":"Hello"}]}]}}'

Set Document Permission

Change the public permission of a document. Supports three levels: private (owner/admin only), public read-only, and public editable. Only the document owner or an admin can perform this action.

PUT

/api/v1/open/documents/{documentId}/permission

Request Body (JSON)

Field	Type	Required	Description
`publicPermission`	string	Yes	Target permission: `private` / `read` (public read-only) / `edit` (public editable)

Permission Levels

Value	Effect
`private`	Only the owner and admins can view and edit
`read`	Any logged-in user can view; only owner/admin can edit
`edit`	Any logged-in user can view and edit

You can also set the initial permission at creation time via the publicPermission parameter in the Create Document API, without needing this endpoint.

Document ID

Target Permission

curl -X PUT "http://localhost:3002/api/v1/open/documents/<documentId>/permission" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"publicPermission":"edit"}'

Delete Document

Soft-delete a document (move to trash). Only the document owner or an admin can perform this action. Template documents cannot be deleted via this endpoint.

DELETE

/api/v1/open/documents/{documentId}

Path Parameters

Field	Type	Description
`documentId`	string	The document ID to delete

This is a soft delete (moved to trash); document data is not immediately purged. Only the owner or an admin can delete; public documents require admin privileges.

Document ID

curl -X DELETE "http://localhost:3002/api/v1/open/documents/<documentId>" \
  -H "Authorization: Bearer <token>"

Template Batch Generation · Overview

Generate contracts, notices, certificates and reports in bulk with "one template + rows of variable data". Auth reuses the existing JWT — no extra integration cost.

Token required

Use cases

Bulk document production

Mass-produce standardized documents: contracts, offer letters/notices, certificates and reports.

Two outputs

Online doc / JSON

output=doc persists the document and returns a docId with an editor link; output=json returns the merged ProseMirror JSON without persisting.

Available templates

Public + your own

Public templates are available to any logged-in user; private templates only to their creator or admins.

Integration flow

1. List templatesGET /open/templates to fetch templates available for generation.

2. Read variablesPick a template and inspect its variable schema (fields/types/required).

3. Fill in dataProvide one or more rows of data following the variable schema.

4. GenerateSingle or batch generation, returning docIds and editor links.

All template APIs live under the /api/v1/open/templates namespace and are automatically protected by JWT. First fill in the backend URL and access token in "Environment Setup" (you can grab a token in "Register & Login").

Template List

List templates the current token can use for generation. Filter by scope and optionally include the variable schema.

GET

/api/v1/open/templates?scope=official&withVariables=1

Request parameters

Parameter	Type	Required	Notes
scope	string	No	Omit = all visible templates; `official` = public templates; `mine` = templates you created.
withVariables	string	No	Pass `1` to include the full variables schema per item — handy for building input skeletons.

Response fields

Field	Notes
id / title / category / desc	Template ID, title, category and description.
variableCount / hasVariables	Number of variables and whether the template has any.
public	Whether the template is public.
updatedAt / variablesUpdatedAt	Last update time of the template and its variables.

Template scope

Fetches templates available to the current token and auto-fills the test panels below.

curl -X GET "http://localhost:3002/api/v1/open/templates?withVariables=1" \
  -H "Authorization: Bearer <token>"

Template Variable Schema

Inspect a template's variable definitions (field name, type, required, enum options) and organize generation data accordingly.

GET

/api/v1/open/templates/{templateId}/variables

Field	Notes
templateId / title	Template ID and title.
variables	Array of variable definitions; each has key, label, type, required, defaultValue, options, etc. (flat, backward compatible).
schema	Structured description: `scalars` (top-level scalar variables), `tables` (repeating tables grouped by `tableId` with column lists and sample rows), `example` (a values skeleton ready to submit).
variablesUpdatedAt	Last update time of the variable schema.

Variable type values: text, number, date, select, image, signature, seal, tableColumn.

Repeating table variables (tableColumn) are not strings and are not top-level values fields; they are keyed by the table's tableId with an array of row objects — one object per row, field names matching column keys. Follow schema.example / schema.tables to organize the data.

Select template

curl -X GET "http://localhost:3002/api/v1/open/templates/<templateId>/variables" \
  -H "Authorization: Bearer <token>"

Single Generation

Generate one document from a set of variable values. By default it creates an online document and returns a docId with an editor link; it can also return the merged JSON only.

POST

/api/v1/open/templates/{templateId}/generate

Request parameters

Field	Type	Required	Notes
values	object	Yes	Variable key-value pairs. Scalar variables use their key directly; repeating table variables use the `tableId` as key with an array of row objects (see schema.example in the variable schema).
unfilledStrategy	string	No	How to handle unfilled variables: `default` (use default value), `empty` (leave blank), `keepPlaceholder` (keep the placeholder).
name	string	No	Generated document name; defaults to the template title.
output	string	No	`doc` (default; persists and counts against quota) or `json` (content only; no persistence, no quota).

output=doc consumes the current user's document quota (admins are exempt); if you only need content for server-side rendering/export, prefer output=json.

Template ID

Variable data values (JSON object)

Unfilled strategy

Output

Document name (optional)

Generated successfully

curl -X POST "http://localhost:3002/api/v1/open/templates/<templateId>/generate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"values":{},"output":"doc"}'

Batch Generation

Generate multiple documents from one template + rows of data. Up to 200 items per request; a single failed item does not affect the others.

POST

/api/v1/open/templates/{templateId}/batch-generate

Request parameters

Field	Type	Required	Notes
items	array	Yes	Array of data rows, each `{ name?, values, unfilledStrategy? }`, up to 200 items.
output	string	No	`doc` (default) or `json`.
stopOnError	boolean	No	When `true`, stop after the first failure; defaults to false (best-effort processing of all items).

Response structure

Field	Notes
summary	`{ total, success, failed }` statistics.
results	Per-item result: `{ index, status, docId?, name?, url?, content?, message? }`.

Example: use one "notice / contract" template + multiple data rows to generate many documents at once; every successful item in results carries a docId and an editor link.

Template ID

Data rows items (JSON array)

Output

Stop on first failure (stopOnError)

JS fetch example

const res = await fetch(`${API}/api/v1/open/templates/${templateId}/batch-generate`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    output: 'doc',
    items: [
      { name: 'Alice-Offer Letter', values: { Name: 'Alice' } },
      { name: 'Bob-Offer Letter', values: { Name: 'Bob' } },
    ],
  }),
});
const { data } = await res.json();
console.log(data.summary, data.results);

curl -X POST "http://localhost:3002/api/v1/open/templates/<templateId>/batch-generate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"output":"doc","items":[{"values":{}}]}'

Core Fields

The most frequently used data fields during integration.

Field	Meaning	Recommendation
documentId	Unique ID of the online document.	Store it in your business system for opening, export and collaboration.
publicPermission	Access level: private/read/edit.	Use private in production; edit is fine for demos and testing.
ownerId	User ID of the document owner.	Should match the id in the import token.
api	Runtime API URL used by the editor.	Must match the upload backend in cross-origin / standalone deployments.

FAQ

The most common errors during integration and how to troubleshoot them.

405 Method Not Allowed

Usually the static page used a relative path and the request hit port 5500. Configure the backend URL.

401 Unauthorized

End-to-end import requires a token; make sure the access token is valid and not expired.

"No permission to access document"

Confirm the new document's permission is edit or the token matches the owner; also confirm the api parameter in the editor link points to the same backend.

Result flashes then disappears

Live Server may watch backend file writes and reload the page. This page restores the last result from localStorage.

JitWord Document Processing Open APIs

Quick Start

Environment Setup

Authentication

Register & Login

My Documents

DOCX Import & Create

Excel Import & Create

High-fidelity DOCX Parsing

DOCX to HTML

Export DOCX by Doc ID

Export DOCX from JSON

Export PDF by Doc ID

Document Info

Document Content Data

Version List

Revisions & Comments

Create Document

Save Document Content

Set Document Permission

Delete Document

Template Batch Generation · Overview

Template List

Template Variable Schema

Single Generation

Batch Generation

Core Fields

FAQ