Skip to main content
POST
Permission Required: project:manage-build-storage
Initiate a build upload. The API automatically selects single-part or multipart upload based on file size.
For most users, we recommend using the CLI or GitHub Action instead of the API directly.

Upload Methods

The API automatically uses multipart for files ≥3GB unless you explicitly set multipart: false.

Request Body

string
Optional. The project is taken from the URL. If provided, it must match the projectId in the route.
string
required
Build name (1-255 characters)
string
required
File name (1-255 characters)
integer
required
Size in bytes (positive integer)
string
required
Target platform: windows, macos, linux, android, ios-native, ios-simulator, xbox, playstation
string
Description (max 1000 characters)
boolean
Force multipart upload. Auto-enabled for files ≥3GB.
boolean
default:"false"
Auto-delete old builds when storage capacity is reached
string
default:"least_recent"
Deletion policy: least_recent (LRU) or oldest (FIFO)
integer
Timeout in minutes (1-1440). Default: 10 for single-part, 60 for multipart.
string[]
Array of tags (1-50 characters each)
object
Build metadata (VCS, CI, app info)

Response (Single-Part)

string
required
Always single-part
string
required
Build ID for completing the upload
string
required
Presigned URL to PUT the file
string
required
Object key for the upload

Response (Multipart)

string
required
Always multipart
string
required
Build ID for completing the upload
string
required
Upload ID for getting part URLs
string
required
Object key for the upload
integer
required
Total number of parts to upload
integer
required
Size of each part in bytes (typically 100MB)

Upload Flow

1

Initiate

POST to /builds/upload with multipart: false
2

Upload

PUT the file to the returned upload_url
3

Complete

POST to /builds/upload/complete

Complete Single-Part Example

Authorizations

X-Api-Key
string
header
required

API key for authentication

Path Parameters

projectId
string
required

The project ID. You can copy it from the project settings page or the project URL in the dashboard.

Body

application/json
name
string
required

Build name (1-255 chars)

file_name
string
required

File name (1-255 chars)

file_size
integer
required

Size in bytes (positive integer)

platform
enum<string>
required

Target platform

Available options:
windows,
macos,
linux,
android,
ios-native,
ios-simulator,
xbox,
playstation
project_id
string

Optional. The project is taken from the URL. If provided, it must match the projectId in the route.

description
string

Description (max 1000 chars)

multipart
boolean

Use multipart upload? (Auto for files ≥3GB)

auto_delete
boolean
default:false

Auto-delete old builds when capacity reached

deletion_policy
enum<string>
default:least_recent
Available options:
least_recent,
oldest
upload_timeout
integer

Timeout in minutes (1-1440)

tags
string[]

Array of tags (1-50 chars each)

details
object

Optional build metadata

Response

Upload initiated successfully

upload_type
string
Allowed value: "single-part"
build_id
string
upload_url
string
object_key
string