Skip to main content
POST
/
upload
/
request
Request Upload
curl --request POST \
  --url https://app.buildstash.com/api/v1/upload/request \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "structure": "file",
  "platform": "windows",
  "stream": "nightlies",
  "source": "ghactions",
  "primary_file": {
    "filename": "example.exe",
    "size_bytes": 52428800
  },
  "version_component_1_major": 1,
  "version_component_2_minor": 0,
  "version_component_3_patch": 1
}'
{
  "message": "Upload request successful",
  "pending_upload_id": "<string>",
  "primary_file": {
    "filename": "example.exe",
    "chunked_upload": true,
    "chunked_number_parts": 14,
    "chunked_part_size_mb": 52428800,
    "presigned_data": {
      "url": "<string>",
      "headers": {
        "Content-Type": "application/x-msdownload",
        "Content-Length": "734003200",
        "Content-Disposition": "attachment; filename=\"example.exe\""
      }
    }
  },
  "expansion_files": [
    {
      "filename": "expansion.obb",
      "chunked_upload": false,
      "chunked_number_parts": "",
      "chunked_part_size_mb": "",
      "presigned_data": {
        "url": "<string>",
        "headers": {
          "Content-Type": "application/octet-stream",
          "Content-Length": "734003200",
          "Content-Disposition": "attachment; filename=\"expansion.obb\""
        }
      }
    }
  ]
}
This endpoint initiates the build upload process by requesting presigned URLs. The response will indicate whether single-part or multipart upload is possible. Multipart is always required for files larger than 5GB.

​
Overview

The upload request endpoint is the first step in uploading a new build. It provides all key build information, and returns a presigned URL for direct upload or multipart upload information for larger files.

Authorizations

​
Authorization
string
header
required

App-specific auth token. Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Upload request details

​
structure
enum<string>
default:file
required

Upload structure type. Should use 'file' unless you're including an Android OBB expansion file

Available options:
file,
file+expansion
Example:

"file"

​
platform
enum<string>
required

Platform identifier. See full list

Available options:
generic,
windows,
macos,
android,
ios,
quest,
switch,
switch2,
ps5,
ps4,
xbox-series,
vision-pro,
pico,
wearos,
vive,
homepod,
apple-tv,
apple-watch,
freebsd,
openbsd,
linux,
debian,
redhat,
gentoo,
arch,
playdate,
magic-leap,
zephyr,
roblox,
opensuse,
alpine,
nixos,
slackware,
void,
mageia,
kaios
Example:

"windows"

​
stream
string
required

Stream name. Must match exact name setup in your app

Example:

"nightlies"

​
source
enum<string>
required

Source of the upload. See full list

Available options:
web-upload,
cli-upload,
ghactions,
jenkins,
unity-build,
gitlab-ci,
azure-devops,
circleci,
travisci,
appveyor,
teamcity,
bitbucket-pipelines,
bitrise,
codemagic,
buildkite,
google-cloud-build,
bamboo,
semaphore,
aws-codebuild,
abstruse,
cirrus-ci,
drone,
concourse
Example:

"ghactions"

​
primary_file
object
required
​
version_component_1_major
integer
required

Semantic versioning: Major version component

Example:

1

​
version_component_2_minor
integer
required

Minor version component

Example:

0

​
version_component_3_patch
integer
required

Patch version component

Example:

1

​
expansion_files
object[]

Expansion files (only include if structure is 'file+expansion')

​
version_component_extra
string

Extra version component. Optional pre-release label like such as 'alpha', 'beta', 'rc', etc

Example:

"alpha"

​
version_component_meta
string

Version metadata. Optional metadata like such as 'build number', 'commit hash', etc

Example:

"2025.07.30"

​
custom_build_number
string

Custom build number (any preferred format)

Example:

"398"

​
labels
string[]

Labels for the build (will be created if they don't already exist)

Example:
["signed", "to-test", "release"]
​
architectures
enum<string>[]

Architectures this build supports (the platform must also support the architecture). See full list

Example:
["x86", "x64", "armv7"]
​
ci_pipeline
string

CI pipeline name

Example:

"Nightly Build"

​
ci_run_id
string

CI run ID

Example:

"38836019427"

​
ci_run_url
string

CI run URL

Example:

"https://github.com/buildstash/example/actions/runs/38836019427"

​
ci_build_duration
string

CI build duration

Example:

"00:05:00"

​
vc_host_type
enum<string>

Version control host type. See full list

Available options:
git,
svn,
hg,
perforce,
bzr,
fossil,
darcs,
cvs,
monotone,
diversion,
unity-vc
Example:

"git"

​
vc_host
enum<string>

Version control host. See full list

Available options:
github,
gitlab,
gitlab-self,
perforce,
bitbucket,
gitea,
forgejo,
gogs,
codeberg,
sourceforge,
sourcehut,
rhodecode,
unity-vc,
aws-codecommit,
azure-repos,
beanstalk,
assembla,
codebase,
bonobo-git,
phabricator,
launchpad,
onedev,
diversion
Example:

"github"

​
vc_repo_name
string

Repository name

Example:

"buildstash/example"

​
vc_repo_url
string

Repository URL

Example:

"https://github.com/buildstash/example"

​
vc_branch
string

Branch name

Example:

"main"

​
vc_commit_sha
string

Commit SHA

Example:

"1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"

​
vc_commit_url
string

Commit URL

Example:

"https://github.com/buildstash/example/commit/1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"

​
notes
string

Additional notes

Example:

"Example build notes here."

Response

Upload request successful

​
message
string

Success response message

Example:

"Upload request successful"

​
pending_upload_id
string

Unique identifier for the pending upload

​
primary_file
object
​
expansion_files
object[]