Create

POST /v1/create writes a new .docx by applying edits to a blank document: headings and lists, formatted text, tables, headers and footers, comments, a table of contents. It is a one-off job: it needs no source document and makes no comparison. To change an existing document, use Edit instead.

The created document is a file like an upload, so it is served as a PDF, Word, HTML and its listing, and it can be edited with POST /v1/edit by its file_id.

The flow

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

POST /v1/create

A JSON body, or multipart/form-data when it uploads style_template or pictures, with edits and outputs as JSON strings.

A blank document has no paragraph to name, so the first content goes at the body's start or end: "destination": {"position": "end"} (see Destinations). Give what a later edit names a ref and name it by that ref.

{
  "name": "Report.docx",
  "edits": [
    { "type": "insert_paragraphs", "destination": { "position": "end" },
      "new_paragraphs": [
        { "content": "Quarterly report", "style_id": "Heading1" },
        { "content": [{ "text": "Prepared for: ", "format": { "bold": true } }, { "text": "Example Co." }], "ref": "intro" }
      ] },
    { "type": "insert_paragraphs", "destination": { "position": "end" },
      "list": { "new": "bulleted" }, "new_paragraphs": [{ "content": "Revenue grew" }, { "content": "Costs fell" }] },
    { "type": "insert_table", "destination": { "position": "end" }, "header_row": true,
      "rows": [["Region", "Q1", "Q2"], ["West", "10", "20"],
               [{ "new_paragraphs": [{ "content": "Total" }], "span": 2 }, "30"]] },
    { "type": "add_comment", "paragraphs": { "ref": "intro" }, "content": "Confirm the name" },
    { "type": "add_header_footer", "part": { "kind": "footer", "type": "default", "section": { "index": 0 } },
      "new_paragraphs": [{ "content": [{ "text": "Page " }, { "type": "field", "code": "PAGE" }],
                           "paragraph_format": { "alignment": "center" } }] }
  ]
}

With a house style, as multipart:

curl -sS https://api.versionstory.com/v1/create \
  -H "Authorization: Bearer vs_live_..." \
  -F "name=Outline.docx" \
  --form-string 'edits=[{"type":"insert_paragraphs","destination":{"position":"end"},"new_paragraphs":[{"content":"Webinar outline","style_id":"Heading1"},{"content":"Introduction"}]}]' \
  -F "style_template=@house-style.dotx"

{
  "creation_id": "crt_...",
  "status": "processing",
  "file": { "file_id": "5b7c...", "file_name": "Outline.docx", "status": "processing", "pending_formats": ["docx"] }
}

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 edit the job cannot apply as written, such as one naming an unknown style, fails the creation with INVALID_EDIT and the reason.

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; it answers at once.

{
  "creation_id": "crt_...",
  "status": "ready",
  "file": {
    "file_id": "5b7c...",
    "file_name": "Outline.docx",
    "status": "ready",
    "downloads": [
      { "format": "docx", "url": "https://documents.versionstory.com/...", "file_name": "Outline.docx", "expires_at": "2026-10-22T18:00:00Z" }
    ]
  }
}

status is the creation's: processing until the Word document is written, ready once it is, and failed when the job failed, with error {"code": "INVALID_EDIT", "message": "edit at index N (type): …"} when an edit could not be applied as written, or {"code": "CREATION_FAILED"} otherwise. file.status is the file's: a PDF, HTML or listing is made from the Word document after it is written, so a ready creation can have a processing file. Either one still processing returns Retry-After: 5. The document is clean, with no tracked changes. Links are valid for one hour; poll again for fresh ones.

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

Related

• Edit operations: every edit a creation can apply
• Edit: change the created document with tracked changes, by its file_id
• Data handling: what is kept, and for how long