# Upload New File Version (/docs/api-reference/start_file_version_upload)

`POST /v1/files/{file_id}/versions` · operation `start_file_version_upload`

Starts a resumable TUS upload of a new version of an existing uploaded File. Finish it with complete_file_upload. The File keeps serving its current version until the new one passes the file checks; then the File, and every Room that has it, shows the new version, and each Room's activity says who uploaded it. Requires edit access to the File and its current revision. One new version uploads at a time.

**Sign-in:** a signed-in person's access token (`Authorization: Bearer …`), which AI apps get through MCP sign-in; or a Workspace API key in the `X-SMB-API-Key` header.

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file_id` | string | yes | Stable File ID. |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `SMB-Workspace-Id` | string (uuid) | yes | Workspace where this operation runs. Required for user tokens and Workspace API keys. |
| `Idempotency-Key` | string | yes |  |

### Request body (JSON)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `expected_revision` | integer | yes |  |
| `file_name` | string | no | Name of the uploaded file, kept with this version. The File's own name doesn't change. |
| `content_type` | one of `application/pdf`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `application/vnd.openxmlformats-officedocument.presentationml.presentation`, `text/csv`, `text/tab-separated-values`, `text/plain`, `text/markdown`, `application/json`, `image/png`, `image/jpeg`, `image/webp` | yes |  |
| `size_bytes` | integer | yes |  |
| `sha256` | string | no |  |

### Response

**200** The existing resource or idempotent replay was returned. · **201** The resource was created.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | object | yes |  |
| `file.file_id` | string | yes | Stable File ID. |
| `file.business_id` | string or null | yes | Associated Business, or null for a Workspace File. |
| `file.name` | string | yes |  |
| `file.description` | string or null | yes |  |
| `file.classification` | one of `financial`, `legal`, `operational`, `marketing`, `other`, `null` | yes |  |
| `file.tags` | array of string | yes |  |
| `file.origin` | one of `upload`, `artifact`, `legacy_document` | yes |  |
| `file.lifecycle` | one of `active`, `archived` | yes |  |
| `file.current_version` | object or null | yes |  |
| `file.revision` | integer | yes |  |
| `file.created_at` | string (date-time) | yes |  |
| `file.updated_at` | string (date-time) | yes |  |
| `file.archived_at` | string (date-time) or null | yes |  |
| `file.access_level` | one of `view`, `edit`, `full_access` | yes |  |
| `upload` | object | yes |  |
| `upload.upload_id` | string | yes | Resumable upload session ID. |
| `upload.protocol` | `tus` | yes |  |
| `upload.url` | string (uri) | yes |  |
| `upload.headers` | object | yes |  |
| `upload.expires_at` | string (date-time) | yes |  |
| `upload.max_size_bytes` | `104857600` | yes |  |
| `new_version` | object | yes |  |
| `new_version.file_version_id` | string | yes | Immutable File version ID. |
| `new_version.version_number` | integer | yes |  |
| `new_version.content_type` | string | yes |  |
| `new_version.size_bytes` | integer | yes |  |
| `new_version.sha256` | string or null | yes |  |
| `new_version.processing_status` | one of `pending_upload`, `processing`, `ready`, `quarantined`, `failed` | yes |  |
| `new_version.processing_error` | string or null | no | Upload processing failure code, when available. |
| `new_version.summary` | string or null | no | What changed in this version, when the author said. |
| `new_version.created_by` | object | no |  |
| `new_version.created_at` | string (date-time) | yes |  |
| `new_version.ready_at` | string (date-time) or null | yes |  |
| `new_version.protection` | object or null | no | What SMB's check for private numbers found: state, reason, items (kind and page, never a number), hidden. Null if unchecked. |
| `new_version.redacted_from` | string or null | no | Copy's original version. |
| `new_version.redacted_copy` | string or null | no | Original's redacted copy. |
| `action_receipt` | object | yes |  |
| `action_receipt.receipt_id` | string (uuid) | yes |  |
| `action_receipt.command_id` | string (uuid) | yes |  |
| `action_receipt.operation` | string | yes |  |
| `action_receipt.workspace_id` | string (uuid) | yes |  |
| `idempotent_replay` | boolean | yes |  |
| `request_id` | string | yes |  |

### Errors

- `400` The request is invalid.
- `401` Authentication is required.
- `403` The caller is not authorized.
- `404` The resource was not found.
- `409` The resource revision or idempotency input conflicts.
- `413` The request body is too large.
- `415` The request must be JSON.
- `422` Required evidence is missing.
- `429` Rate limit reached; honor Retry-After.
- `500` The request could not be completed.
- `502` A dependency returned an invalid response.
- `503` The service is temporarily unavailable.

### Example

```bash
curl --request POST "https://api.smb.co/v1/files/$FILE_ID/versions" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "SMB-Workspace-Id: $WORKSPACE_ID" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{"expected_revision":1,"content_type":"application/pdf","size_bytes":1}'
```