Create Word Documents REST API Reference

Make a clean Word document from an ordered list of styled paragraphs, optionally in your own house style.

POST /v1/create turns a list of paragraphs into a new .docx, each paragraph in a named style. It is a one-off job: it needs no source document, and it makes no comparison. To change an existing document, use Edit instead.


Base URL	`https://api.versionstory.com`
Auth	`Authorization: Bearer vs_...`. See Authentication

The flow

POST /v1/create with the file name and the paragraphs. Returns 202 and a creation_id.
GET /v1/create/{creation_id} until status is ready, then download the document from downloads[].url.

POST /v1/create

multipart/form-data.

Field	Required	Meaning
`name`	Yes	The output file name, ending in `.docx`
`paragraphs`	Yes	A JSON array of paragraphs, in document order
`style_template`	No	A `.docx`, `.dotx` or `.dotm` whose styles, numbering, and theme fonts and colors the document uses. Its content, macros, headers and footers, and page layout are not copied

curl -sS https://api.versionstory.com/v1/create \
  -H "Authorization: Bearer vs_live_..." \
  -F "name=Outline.docx" \
  --form-string 'paragraphs=[{"text":"Webinar outline","style_id":"Heading1"},{"text":"Introduction","style_id":"Normal"}]' \
  -F "style_template=@house-style.dotx"

{ "creation_id": "crt_...", "status": "processing" }

Paragraphs

Each item makes exactly one paragraph and has a style_id and exactly one of text and runs. Other keys are refused.

text: the paragraph's plain text, with no newline characters. Empty text makes a blank paragraph.
runs: the paragraph's content as runs, each with its own character format, the same runs edits take. For example, {"runs":[{"text":"Term: ","format":{"bold":true}},{"text":"definition"}],"style_id":"Normal"}.

Markdown is not parsed: map your headings and body text to paragraph styles before you send them. Without a template, the styles are Normal, Heading1, Heading2, Heading3 and Heading4, on a US Letter page with one-inch margins. A template's styles replace those with the same id and add the rest. An unknown style id, or one that is not a paragraph style, fails the job.

paragraphs is limited to 200 KiB. A template has the same 100 MB limit as any other file. Each creation counts as one document against your usage; sending the POST again starts another creation, so keep the creation_id and poll it instead.

GET /v1/create/{creation_id}

Read-only and safe to poll. While the job runs, the response carries Retry-After: 5.

{
  "creation_id": "crt_...",
  "status": "ready",
  "downloads": [
    {
      "format": "docx",
      "url": "https://documents.versionstory.com/...",
      "file_name": "Outline.docx",
      "expires_at": "2026-10-15T18:00:00+00:00"
    }
  ]
}

The download is a clean .docx with no tracked changes. Its URL is valid for one hour, and polling again mints a fresh one. A job that failed answers {"creation_id": "crt_...", "status": "failed", "error": {"code": "CREATION_FAILED"}}; correct the request and send a new POST.

POST /v1/create/{creation_id}/acknowledge

For an organization with zero-day retention, deletes the created document as soon as you have saved it, instead of an hour after it was made. No body; the response is 202 with "status": "deletion_queued".

Errors

Status	Code	Cause
400	`INVALID_REQUEST`	A missing `name` or `paragraphs`, `paragraphs` that is not a valid list of paragraphs, or more than 200 KiB of it
400	`UNSUPPORTED_FILE_TYPE`	`name` does not end in `.docx`, or `style_template` is not a `.docx`, `.dotx` or `.dotm`
400	`INVALID_CREATION_ID`	The `creation_id` is malformed
401	`INVALID_API_KEY`	Missing, malformed, unknown, revoked, or expired key
402	`USAGE_LIMIT_REACHED`	The organization's monthly upload allowance is exhausted
404	`CREATION_NOT_FOUND`	No such creation, or it belongs to another organization
409	`CONFLICT`	An acknowledgment of a creation that is still processing, or that has no zero-day retention
410	`CONTENT_DELETED`	The document was deleted under zero-day retention
413	`FILE_TOO_LARGE`	`style_template` exceeds the 100 MB limit

Edit: to change the created document with tracked changes, upload it with POST /v1/files first
Data handling: what is kept, and for how long

Create