# Create

> 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](/developers/rest/edit) instead.

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

## The flow

1. `POST /v1/create` with the file name and the paragraphs. Returns `202` and a `creation_id`.
2. `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 |

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

```json
{ "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](/developers/rest/edit#writing-content) 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`.

```json
{
  "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](/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 `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 |

## Related

- [Edit](/developers/rest/edit): to change the created document with tracked changes, upload it
  with [`POST /v1/files`](/developers/rest/files#post-v1files) first
- [Data handling](/developers/reference/data-handling): what is kept, and for how long