Beta

Upload New File Version

Last updated Nov 19, 2026View as MarkdownAgent setup / MCP
POST
/v1/files/{file_id}/versions

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.

Authorization

headerAuthorizationBearer <token>

A signed-in SMB user's access token. Workspace-scoped operations also require SMB-Workspace-Id.

Path Parameters

file_id*string

Stable File ID.

Match^fil_[0-7][0-9A-HJKMNP-TV-Z]{25}$

Header Parameters

SMB-Workspace-Id*string

Workspace where this operation runs. Required for user tokens and Workspace API keys.

Formatuuid
Idempotency-Key*string
Length8 <= length <= 200

Request Body

application/json
  1. body
expected_revision*integer
Range1 <= value
file_name?string

Name of the uploaded file, kept with this version. The File's own name doesn't change.

Length1 <= length <= 300
content_type*ContentType
Value in"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"
size_bytes*integer
Range1 <= value <= 104857600
sha256?smb_v0_operations_check_api_health_response.__local.Digest
Match^sha256:[0-9a-f]{64}$

Response Body

The existing resource or idempotent replay was returned.

application/json
  1. response
file*
upload*
new_version*
action_receipt*
idempotent_replay*smb_v0_operations_create_list_request.__local.properties.body.__schema16
request_id*string
curl -X POST 'https://example.com/v1/files/string/versions' \  -H 'SMB-Workspace-Id: 497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Idempotency-Key: stringst' \  -H 'Content-Type: application/json' \  -d '{  "expected_revision": 1,  "content_type": "application/pdf",  "size_bytes": 1}'
{  "file": {    "file_id": "string",    "business_id": "string",    "name": "string",    "description": "string",    "classification": "financial",    "tags": [      "string"    ],    "origin": "upload",    "lifecycle": "active",    "current_version": {      "file_version_id": "string",      "version_number": 1,      "content_type": "string",      "size_bytes": 1,      "sha256": "string",      "processing_status": "pending_upload",      "processing_error": "string",      "summary": "string",      "created_by": {        "type": "person",        "user_id": "string",        "name": "string",        "via": null      },      "created_at": "2019-08-24T14:15:22Z",      "ready_at": "2019-08-24T14:15:22Z",      "protection": {},      "redacted_from": "string",      "redacted_copy": "string"    },    "revision": 1,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "archived_at": "2019-08-24T14:15:22Z",    "access_level": "view"  },  "upload": {    "upload_id": "string",    "protocol": "tus",    "url": "http://example.com",    "headers": {      "x-signature": "string",      "upload-metadata": "string"    },    "expires_at": "2019-08-24T14:15:22Z",    "max_size_bytes": 104857600  },  "new_version": {    "file_version_id": "string",    "version_number": 1,    "content_type": "string",    "size_bytes": 1,    "sha256": "string",    "processing_status": "pending_upload",    "processing_error": "string",    "summary": "string",    "created_by": {      "type": "person",      "user_id": "string",      "name": "string",      "via": null    },    "created_at": "2019-08-24T14:15:22Z",    "ready_at": "2019-08-24T14:15:22Z",    "protection": {},    "redacted_from": "string",    "redacted_copy": "string"  },  "action_receipt": {    "receipt_id": "64d0a161-468e-472a-b00e-a06ee9ab7de7",    "command_id": "7d510d78-7444-4252-aeac-9e473949661e",    "operation": "string",    "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"  },  "idempotent_replay": true,  "request_id": "string"}