api.mdx

title	API

This page lists common Univer Server APIs. The default base URL is http://localhost:8000.

Note: type parameter values: 1 for Docs, 2 for Sheets.

Document Management

Create Document

<APITable request={{ method: 'POST', url: '/universer-api/snapshot/{type}/unit/-/create', headers: content-type: application/json, parametersType: 'Body', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1 (docs), 2 (sheets) for path and body', }, { name: 'name', type: 'string', required: true, description: 'Document name', }, { name: 'creator', type: 'string', required: true, description: 'Creator id', }, { name: 'idempotencyKey', type: 'string', required: false, description: 'Introduced since v0.20.0. Optional idempotency key; The total byte size must be ≤ 64.', }, { name: 'metaData', type: 'string', required: false, description: 'Introduced since v0.20.0. User-defined information, bound to the created unit, will be transparently passed through in subsequent synchronization events and USIP calls. The total byte size must be ≤ 1024.', }], example: curl http://localhost:8000/universer-api/snapshot/{type}/unit/-/create \\ -X POST \\ -H 'Content-Type: application/json' \\ --data-raw '{"type":2,"name":"New Sheet By Univer","creator":"userID","idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }, { name: 'unitID', type: 'string', description: 'Document id', }], example: JSON.stringify({ error: { code: 1, message: 'success', }, unitID: 'ETVf-B4lQqOSE_p09mcp9Q', }, null, 2), }} />

List Documents

<APITable request={{ method: 'GET', url: '/universer-api/snapshot/{type}/units', parametersType: 'Query', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1 (doc), 2 (sheet) for path and body', }, { name: 'nextCursor', type: 'string', required: false, description: 'Next page cursor', }], example: curl -X GET 'http://localhost:8000/universer-api/snapshot/1/units?nextCursor=100', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }, { name: 'units', type: 'array[object]', description: 'Document list', properties: [{ name: 'unitID', type: 'string', description: 'Document id', }, { name: 'name', type: 'string', description: 'Document name', }, { name: 'type', type: 'enum(int)', description: '1 (doc), 2 (sheet)', }], }, { name: 'nextCursor', type: 'string', description: 'Next page cursor; empty means last page', }], example: JSON.stringify({ error: { code: 1, message: '', }, units: [{ unitID: '1', name: 'a', type: 1, }], nextCursor: '200', }, null, 2), }} />

Delete Documents

<APITable request={{ method: 'DELETE', url: '/universer-api/snapshot/-/units', headers: content-type: application/json, parametersType: 'Query', parameters: [{ name: 'unitIds', type: 'array[string]', required: true, description: 'Document id list', }, { name: 'hardDelete', type: 'boolean', required: false, description: 'Whether to permanently delete the documents. true permanently deletes them; false or omitted only marks them as deleted.', }], example: curl -X DELETE 'http://localhost:8000/universer-api/snapshot/-/units?unitIds=1&unitIds=2&hardDelete=true', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }], example: JSON.stringify({ error: { code: 1, message: '', }, }, null, 2), }} />

Fork Document (Experimental API)

Note: This is an experimental API and may change incompatibly in future releases.

<APITable request={{ method: 'POST', url: '/universer-api/snapshot/{type}/unit/{unitId}/fork', headers: content-type: application/json, parametersType: 'Path', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1 (docs), 2 (sheets) for path', }, { name: 'unitId', type: 'string', required: true, description: 'Document id to fork', }], example: curl -X POST 'http://localhost:8000/universer-api/snapshot/2/unit/ETVf-B4lQqOSE_p09mcp9Q/fork', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }, { name: 'unitId', type: 'string', description: 'New document id generated by the fork', }], example: JSON.stringify({ error: { code: 1, message: '', }, unitId: 'FORKED_ETVf-B4lQqOSE_p09mcp9Q', }, null, 2), }} />

Create Snapshot

<APITable request={{ method: 'GET', url: '/universer-api/snapshot/{type}/unit/{unitID}/rev/0/ensure', parametersType: 'Query', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1 (doc), 2 (sheet) for path', }, { name: 'unitID', type: 'string', required: true, description: 'Document id', }], example: curl -X GET 'http://localhost:8000/universer-api/snapshot/2/unit/ETVf-B4lQqOSE_p09mcp9Q/rev/0/ensure', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }], example: JSON.stringify({ error: { code: 1, message: '', }, }, null, 2), }} />

Files and Import/Export

Upload File [#upload-file]

<APITable request={{ method: 'POST', url: '/universer-api/stream/file/upload', headers: content-type: multipart/form-data, parametersType: 'Body', parameters: [{ name: 'size', type: 'int', required: true, description: 'File size in bytes (query param). Must match actual size.', }, { name: 'file', type: 'Form.file', required: true, description: 'File in HTML form', }], example: curl 'http://localhost:8000/universer-api/stream/file/upload?size=125466' \\ --header 'cookie: _univer=XXXXXX' \\ --form 'file=@"demo.xlsx"', }} response={{ type: 'application/json', parameters: [{ name: 'FileId', type: 'string', description: 'File id for import/export', }], example: JSON.stringify({ FileId: 'xxxx', }, null, 2), }} />

Import [#import-file]

<APITable request={{ method: 'POST', url: '/universer-api/exchange/{type}/import', headers: content-type: application/json, parametersType: 'Body', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1 (doc), 2 (sheet)', }, { name: 'outputType', type: 'enum(int)', required: true, description: '1 (unit), 2 (json)', }, { name: 'fileID', type: 'string', required: true, description: 'Uploaded file id', }, { name: 'minSheetRowCount', type: 'int', required: true, description: 'Minimum rows; import validates row count', }, { name: 'minSheetColumnCount', type: 'int', required: true, description: 'Minimum columns; import validates column count', }, { name: 'idempotencyKey', type: 'string', required: false, description: 'Introduced since v0.20.0. Optional idempotency key; The total byte size must be ≤ 64.', }, { name: 'metaData', type: 'string', required: false, description: 'Introduced since v0.20.0. User-defined information, bound to the imported unit, will be transparently passed through in subsequent synchronization events and USIP calls. The total byte size must be ≤ 1024.', }], example: curl -X POST 'http://localhost:8000/universer-api/exchange/2/import' \\ -H 'Content-Type: application/json' \\ --data-raw '{"fileID":"123","outputType":1,"minSheetRowCount":1000,"minSheetColumnCount":20,"idempotencyKey":"a-idgenerator-unique-id","metaData":"tenant12345"}', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }, { name: 'taskID', type: 'string', description: 'Task id for polling', }], example: JSON.stringify({ error: { code: 1, message: '', }, taskID: '456', }, null, 2), }} />

Export [#export-file]

<APITable request={{ method: 'POST', url: '/universer-api/exchange/{type}/export', headers: content-type: application/json, parametersType: 'Body', parameters: [{ name: 'type', type: 'enum(int)', required: true, description: '1 (doc), 2 (sheet)', }, { name: 'unitID', type: 'string', required: true, description: 'Collaborative document id; if exporting as jsonID, unitID can be empty string', }, { name: 'jsonID', type: 'string', required: true, description: 'For non-collaborative document export, jsonID is the FileId returned after uploading the file generated from frontend json; if exporting as unitID, jsonID can be empty string', }, { name: 'sscSwitch', type: 'boolean', required: false, description: 'Enable SSC (server-side calculation); default false', }, { name: 'useImageUrl', type: 'boolean', required: false, description: 'Whether to disable converting cell images to links; if true, cell images will not be converted to links; default false', }, { name: 'ignoreTableExport', type: 'boolean', required: false, description: 'Whether to ignore table export; default false', }], example: curl -X POST 'http://localhost:8000/universer-api/exchange/2/export' \\ -H 'Content-Type: application/json' \\ --data-raw '{"unitID":"xxxx","type":2}', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }, { name: 'taskID', type: 'string', description: 'Task id for polling', }], example: JSON.stringify({ error: { code: 1, message: '', }, taskID: '456', }, null, 2), }} />

Get Task Result [#get-task-result]

<APITable request={{ method: 'GET', url: '/universer-api/exchange/task/{taskID}', parametersType: 'Path', parameters: [{ name: 'taskID', type: 'string', required: true, description: 'Task id', }], example: curl -X GET 'http://localhost:8000/universer-api/exchange/task/123', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }, { name: 'status', type: 'enum(string)', description: '"pending", "done", "failed"', }, { name: 'export', type: 'object', properties: [{ name: 'fileID', type: 'string', description: 'Exported file id', }], }, { name: 'import', type: 'object', properties: [{ name: 'unitID', type: 'string', description: 'Imported unitID', }, { name: 'jsonID', type: 'string', description: 'JSON file id', }], }], example: JSON.stringify({ error: { code: 1, message: '', }, status: 'done', export: { fileID: '456', }, import: { unitID: '789', jsonID: '012', }, }, null, 2), }} />

Get File [#get-file]

<APITable request={{ method: 'GET', url: '/universer-api/file/{fileID}/sign-url', parametersType: 'Path', parameters: [{ name: 'fileID', type: 'string', required: true, description: 'Result file id (export.fileID or import.jsonID)', }], example: curl -X GET 'http://localhost:8000/universer-api/file/1234/sign-url', }} response={{ type: 'application/json', parameters: [{ name: 'error', type: 'object', properties: [{ name: 'code', type: 'enum(int)', description: '1 (success)', }, { name: 'message', type: 'string', description: 'Error message', }], }, { name: 'url', type: 'string', description: 'Download URL', }], example: JSON.stringify({ error: { code: 1, message: '', }, url: 'https://example.com/path/to/file.xlsx', }, null, 2), }} />