---
title: "Upload File"
method: POST
path: "/v1/files"
tags: ["files"]
---

# Upload File

`POST /v1/files`

## 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/files`
- Auth: HTTP bearer

Upload a file and return its file_id. Call this first when the user asks to change, fix, revise or redraft a
document; then GET /v1/files/{file_id}?format=md and POST /v1/edit. Every call uploads a new copy, so upload a file once and reuse its file_id for
every edit, merge and comparison of it.

Send the file's bytes as multipart/form-data in the document field (with curl, -F document=@<path>): a docx, doc or
pdf to read, edit, compare or merge, or an xlsx or pptx to compare. A docx answers status processing while it is
prepared, and work sent with its file_id waits for that. A doc or pdf is converted to Word first: the call waits up to
20 seconds for it and answers ready, failed with error, or processing.

## Headers

- `X-Customer-Id` string, 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 `multipart/form-data`

- BodyUploadFileV1FilesPost
  - `document` string, binary, required: The document to upload
  - `track_redline_changes` boolean: When an uploaded PDF is a redline (insertions underlined in one color, deletions struck through in another), turn its insertions and deletions into tracked changes in the Word document made from it. Default true. A PDF that is not a redline, and any other kind of document, is unaffected.

## Response `202`

Successful Response

- FileUploadResponse
  - `file_id` string, required
  - `status` 'processing' | 'ready' | 'failed', required: The uploaded document's preparation; work queued against the file waits for it.
  - `error` ComparisonErrorDescriptor
    - `code` string, required
    - `upstream_code` string, nullable

## Other responses

- `400`: The request is invalid: INVALID_REQUEST when a parameter or the body fails validation, otherwise the code of the operation's own refusal.

---

[API](https://skmtc.dev/versionstory/apis/version-story-public-api.md) - [All operations](https://skmtc.dev/versionstory/apis/version-story-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/versionstory/apis/version-story-public-api/revisions/994ce15faf32?raw)