Document Builder API

For the interaction with the web document builder service the POST requests are used. The request parameters are entered in JSON format in the request body. The requests are sent to the https://documentserver/docbuilder address where documentserver is the name of the server with the ONLYOFFICE Docs installed.

Starting from version 8.1, it is recommended to add the shardkey parameter to the URL QueryString with the key value in it. For example, ?shardkey=Khirz6zTPdfd7. This allows you to load balance requests.

Request parameters and their description

Parameter	Type	Presence	Description
argument	object	optional	Defines the arguments to pass to the created document. See supported properties for details on how the argument is used.
async	boolean	optional	Defines the type of the request to the document builder service: asynchronous or not. When true, the response is formed instantly with a key in the response. You must then poll by sending requests with this key until document generation is finished (when end becomes true). The default value is false.
key	string	conditional	Defines the request identifier used to unambiguously identify the request. The key is formed on the document builder service side and is returned as the response to the first request. When the asynchronous request is used (the async parameter is set to true) the key is not present in the first request, but must be present in all the following requests which will be sent before the generation is complete. When the synchronous request is used (the async parameter is set to false), this parameter is not required.
token	string	required by configuration	Defines the encrypted signature added to the ONLYOFFICE Docs config in the form of a token.
url	string	required	Defines the absolute URL to the .js script file.

The .js script file is a JavaScript file that uses the Office JavaScript API to generate output document files (text documents, spreadsheets, or presentations). It uses builder.CreateFile() to create a document, the Office API classes to manipulate content, builder.SaveFile() to specify the output format and name, and builder.CloseFile() to finalize. You can find more information about the script file syntax here. Once document generation is complete, the response with the absolute URL to the resulting file will be returned (see below).

note

The .js script file can contain several output files as a result. The URL to them all will be returned in the response to the request once the file generation is finished.

caution

When using builder.OpenFile() in your script, you must provide an absolute URL to the file (e.g., https://example.com/document.docx), not a local path. The Document Server needs to download the file from a publicly accessible location.

Response parameters and their description

The request result is returned in JSON format.

Parameter	Type	Example	Description
end	boolean	true	Defines if the document generation is completed or not. When false, the task is still being processed and the urls parameter is not included in the response. When true, the task is complete and the urls parameter will be present.
error	integer	-8	Defines an error that occurred during document generation. Possible error codes can be found below.
key	string	af86C7e71Ca8	Defines the unique identifier of the document generation task. If the key parameter was provided in the request, the same value is returned. If the key parameter was not provided in the first asynchronous request, a new key is generated by the document builder service. Use this value in all subsequent polling requests.
urls	object	{"output.docx": "https://documentserver/..."}	Defines an object containing the absolute URLs to the generated output files. The object keys are the output file names as specified in the .js script. This parameter is present only when the end value is true.

Sample script

Below is a simple .js script that creates a document with "Hello World!" text:

builder.CreateFile("docx");
var oDocument = Api.GetDocument();
var oParagraph = oDocument.GetElement(0);
oParagraph.AddText("Hello World!");
builder.SaveFile("docx", "output.docx");
builder.CloseFile();

Host this file on a publicly accessible server to use it with the API requests below.

Examples

info

In the examples below, example.com represents the server where your document storage service is installed and .js files are served from. See the How it works section to learn more about ONLYOFFICE Docs service client-server interactions.

Asynchronous request

Step 1. Send the initial request with the .js script file URL:

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": true,
    "url": "https://example.com/url-to-example-script.js"
  }'

Response:

{
  "key": "af86C7e71Ca8",
  "end": false
}

Step 2. Poll using the returned key until end is true:

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": true,
    "key": "af86C7e71Ca8"
  }'

Response:

{
  "key": "af86C7e71Ca8",
  "urls": {
    "output.docx": "https://documentserver/output.docx"
  },
  "end": true
}

Synchronous request

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": false,
    "url": "https://example.com/url-to-example-script.js"
  }'

Response:

{
  "key": "af86C7e71Ca8",
  "urls": {
    "output.docx": "https://documentserver/output.docx"
  },
  "end": true
}

Asynchronous request with token

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhc3luYyI6dHJ1ZSwidXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS91cmwtdG8tZXhhbXBsZS1zY3JpcHQuZG9jYnVpbGRlciJ9.dzoTbRzSMa95Fpg34CjnF3ZUPdGA2CnBedFL_qOOxAs"
  }'

Response:

{
  "error": -8
}

info

This example demonstrates the error response when the token is invalid. See the error codes section for more details.

Synchronous request with arguments

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": false,
    "url": "https://example.com/url-to-example-script.js",
    "argument": {
      "key": "string",
      "key2": "string2"
    }
  }'

Response:

{
  "key": "af86C7e71Ca8",
  "urls": {
    "output.docx": "https://documentserver/output.docx"
  },
  "end": true
}

Multiple output files

A .js script can generate multiple files. For example:

builder.CreateFile("docx");
var oDocument = Api.GetDocument();
var oParagraph = oDocument.GetElement(0);
oParagraph.AddText("Document 1");
builder.SaveFile("docx", "document1.docx");
builder.CloseFile();

builder.CreateFile("xlsx");
var oWorksheet = Api.GetActiveSheet();
oWorksheet.GetRange("A1").SetValue("Spreadsheet 1");
builder.SaveFile("xlsx", "spreadsheet1.xlsx");
builder.CloseFile();

curl -X POST "https://documentserver/docbuilder" \
  -H "Content-Type: application/json" \
  -d '{
    "async": false,
    "url": "https://example.com/url-to-example-script.js"
  }'

Response:

{
  "key": "af86C7e71Ca8",
  "urls": {
    "document1.docx": "https://documentserver/document1.docx",
    "spreadsheet1.xlsx": "https://documentserver/spreadsheet1.xlsx"
  },
  "end": true
}

Possible error codes and their description

Error code	Description
-1	Unknown error.
-2	Generation timeout error.
-3	Document generation error.
-4	Error while downloading the document file to be generated.
-6	Error while accessing the document generation result database.
-8	Invalid token.