---
title: "Files - request an upload URL"
method: POST
path: "/api/v1/files/upload"
tags: ["Files"]
---

# Files - request an upload URL

`POST /api/v1/files/upload`

Returns a pre-signed URL for uploading a file via PUT.

## Request body

- FileUploadBody — Request a pre-signed upload URL. After receiving the URL, PUT the raw file bytes to it within the expiration window.
  - `filename` string, required — Original filename including extension (e.g. 'part.step', 'model.obj'). Used for display and format detection.
  - `contentType` string, required — MIME type of the file (e.g. 'application/step', 'model/gltf-binary'). Must match the actual file content.
  - `bytes` integer, required — Exact file size in bytes. Must match the Content-Length of the subsequent PUT to the upload URL. Maximum: 1 GB.
  - `sha256` string — SHA-256 hex digest of the file content. When provided, enables server-side deduplication - if an identical file was previously uploaded under this API key, the existing file is reused and no upload is needed.

## Response `201`

Upload URL and file ID

- UploadResponse — Success envelope containing the pre-signed upload URL and file metadata
  - `ok` true, required
  - `data` UploadResult, required — Response after requesting a file upload. Contains the pre-signed URL to PUT your file to.
    - `fileId` string, uuid, required — Assigned file identifier - use this to reference the file in subsequent API calls
    - `uploadUrl` string, uri, required — Pre-signed URL to PUT the raw file bytes to. Send the file content with Content-Type and Content-Length headers matching the request.
    - `expiresIn` integer, required — Seconds until the upload URL expires. You must complete the PUT within this window.
    - `maxBytes` integer, required — Maximum allowed file size in bytes for this upload. Determined by your plan tier.
    - `status` 'pending', required

## Other responses

- `400` — Validation error
- `500` — Server error

---

[API](https://skmtc.dev/bitbybit-dev/apis/bitbybit-cad-cloud-api.md) · [All operations](https://skmtc.dev/bitbybit-dev/apis/bitbybit-cad-cloud-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bitbybit-dev/bitbybit-cad-cloud-api/revisions/1135d4473bc2/schema)