Create Document File

Create a new Word document, with no source file, by applying edits to a blank document: the same edits, schema and refusals POST /v1/edit takes, resolved against a document of no paragraphs and one section.

Put the first content at the body's start or end, with the destination {"position": "end"} (no paragraph or table), give each paragraph, table or header that a later edit names a ref, and name it by that ref, as an edit names content its own request creates. Every edit type is accepted: headings and lists (insert_paragraphs with style_id, list and list_level), runs with their formats, fields and hyperlinks, tables (header_row, and {"new_paragraphs": [...], "span": 2} for a cell merged across two grid columns), headers and footers (add_header_footer for section {"index": 0}, a page number being the field run {"type": "field", "code": "PAGE"}; a first-page one needs set_page_setup's different_first_page), comments, a table of contents, page setup and document settings. An edit naming something a blank document lacks is refused as POST /v1/edit refuses it. The result is one clean Word document with every change accepted. Paragraph styles are Normal (the default), Heading1 to Heading4, and those of an uploaded template. The edits reference lists every edit type's fields with an example of each.

The created document is a file like an uploaded one: the answer carries it as GET /v1/files/{file_id} answers for it, its file_id reads with GET /v1/files/{file_id}?format=md and changes with POST /v1/edit, and it is served as docx (the default), pdf, md, json or html. With wait true the request holds until the document is made (up to 5 s) and answers as GET /v1/create/{creation_id} does, the file's downloads in the formats outputs names, each with its bytes when inline is true; otherwise, or while it is still processing, poll GET /v1/create/{creation_id} until it is ready. Its pdf, md, json and html are made from the document once it is written, so a ready creation's file can still list them in pending_formats: poll again after Retry-After.

post/v1/create

Request

  • Base URL
    https://api.versionstory.com (the document declares no server; this is the origin it was published from)
  • URL
    https://api.versionstory.com/v1/create
  • Auth
    HTTP bearer

Headers

X-Customer-Idstring nullable

Id of one of your customers (created in the developer dashboard) to attribute this request's credit usage to. Billing and limits stay organization-wide.

Request body

namestring required

The new document's file name, ending in .docx.

authorstring nullable

The name new comments carry when an edit names none; at most 255 characters, one line. Omitted, it is the signed-in user's own name (Version Story AI for an API key, which acts as its organization's service account).

datestring nullable

ISO 8601 date and time on new comments; defaults to the time of the request.

waitboolean

Hold the response until the job finishes (up to 5 s).

inlineboolean

With wait: return the created file's bytes in the body.

outputsstring[] nullable

With wait: the created file's formats, docx (the default), pdf, md, json or html, as GET /v1/create/{creation_id} takes them.

Response

Successful Response

OR

Changes

No recorded changes to this operation across all 1 revision of this API.