---
title: "Start a file upload"
method: POST
path: "/api/v1/files"
tags: ["Files"]
---

# Start a file upload

`POST /api/v1/files`

## Request

- Base URL: `https://your-deployment.example.com`
- URL: `https://your-deployment.example.com/api/v1/files`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Registers a file and returns a presigned `upload_url`. Uploading is three steps: (1) call this endpoint with the file name, MIME type, and size in bytes; (2) `PUT` the raw bytes to `upload_url` before `upload_url_expires_at` - send no `Authorization` header, the URL signature is the credential, and do send a `Content-Type` matching `mime_type`; (3) poll `GET /api/v1/files/{id}` until `moderation_status` is `clean` (usually a few seconds after the PUT), then pass `id` wherever an endpoint takes a file id (for example `fabFileIds` and `referenceImageFabFileIds` on `POST /api/v1/image-edits`). Unsupported types, a size over the upload limit, or a size that would exceed your storage quota are rejected with 400 before any URL is issued. Authenticate with an API key (`b4m_live_`) carrying `files:write`, or a JWT.

## Request body

- CreateFileUploadRequest
  - `file_name` string, required
  - `mime_type` string, required
  - `file_size` integer, required

## Response `201`

The file is registered; PUT its bytes to `upload_url`.

- CreateFileUploadResponse201
  - `id` string, required
  - `upload_url` string, required
  - `upload_url_expires_at` string, required

## Other responses

- `400`: Unsupported file type, file larger than the upload limit, or storage quota exceeded. A size or quota refusal carries a stable `errorCode` plus `used_bytes`, `limit_bytes`, `requested_bytes` and `owner`, always together; an unsupported type carries none of them. This endpoint checks only the user quota and the per-file cap, so `org_storage_limit_exceeded` is never returned here.
- `401`: Missing or invalid credentials.
- `403`: The API key does not hold any of the required scopes.
- `405`: The path does not serve this HTTP method.
- `422`: Request failed validation.
- `429`: Per-user rate limit exceeded.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/0de0bdb0d113?raw)