# Create

> Write a new Word document from the same edits POST /v1/edit takes, applied to a blank page, optionally in your own house style.

> Integrating Version Story into a codebase as a coding agent? Follow https://www.versionstory.com/developers/quickstart.md: it signs the engineer in, gets an API key, and puts the PDF redline in their app first.

`POST /v1/create` writes a new `.docx` by applying [edits](/developers/rest/edit-operations) 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](/developers/rest/edit) instead.

| | |
| --- | --- |
| Base URL | `https://api.versionstory.com` |
| Auth | `Authorization: Bearer vs_...`. See [Authentication](/developers/authentication) |

The created document is a [file](/developers/rest/files) 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.

| Field | Required | Meaning |
| --- | --- | --- |
| `name` | Yes | The output file name, ending in `.docx` |
| `edits` | Yes | The edits that write the document, applied in order to a blank document, at most 200. The same edits, schema and refusals as [`POST /v1/edit`](/developers/rest/edit-operations) |
| `author` | No | The name new comments carry when an edit names none |
| `date` | No | ISO 8601 date and time on new comments. Default: the time of the request |
| `wait` | No | `true` holds the response until the document is written, up to 5 seconds |
| `inline` | No | With `wait`: `true` adds the file's bytes as `content_base64` to each ready download |
| `outputs` | No | With `wait`: the formats to return, as `GET /v1/create/{creation_id}`'s `format` takes them. Default `["docx"]` |
| `style_template` | No | Multipart only: 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 |
| `pictures` | No | Multipart only, repeated: PNG, JPEG or GIF files that picture runs name by file name. See [Pictures](/developers/rest/edit-operations#pictures) |

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](/developers/rest/edit-operations#destinations)).
Give what a later edit names a `ref` and name it by that ref.

```json
{
  "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:

```bash
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"
```

```json
{
  "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.

| Parameter | In | Required | Default | Meaning |
| --- | --- | --- | --- | --- |
| `creation_id` | path | Yes | — | The id from `POST /v1/create` |
| `format` | query | No | `docx` | The created file's formats: `pdf`, `html`, `docx`, `md`, `json`, as `GET /v1/files/{file_id}` serves them. Repeatable or comma-separated |
| `inline` | query | No | `false` | `true` adds the file's bytes as `content_base64` to each ready download |

```json
{
  "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](/developers/reference/data-handling#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 `edits`, JSON that does not parse, or `inline` or `outputs` without `wait` |
| 400 | `INVALID_EDIT` | An edit was refused, every refusal listed and naming its edit as `edit at index N (type): …` |
| 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 |

## Related

- [Edit operations](/developers/rest/edit-operations): every edit a creation can apply
- [Edit](/developers/rest/edit): change the created document with tracked changes, by its `file_id`
- [Data handling](/developers/reference/data-handling): what is kept, and for how long