Request to Start Upload

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.

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.

POST/upload/request

Authorization

AuthorizationBearer <token>

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

In: header

Request Body

Upload request details

structurestring

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

Default"file"

Value in"file" | "file+expansion"

Example"file"

platformstring

Platform identifier. See full list

Value in

"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"

streamstring

Stream name. Must match exact name setup in your app

Example"nightlies"

sourcestring

Source of the upload. See full list

Value in

"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

expansion_files?

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

version_component_1_majorinteger

Semantic versioning: Major version component

Example1

version_component_2_minorinteger

Minor version component

Example0

version_component_3_patchinteger

Patch version component

Example1

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?array<string>

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

Example

[
  "signed",
  "to-test",
  "release"
]

architectures?array<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?string

Version control host type. See full list

Example"git"

vc_host?string

Version control host. See full list

Value in

"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 Body

application/json

curl -X POST "https://app.buildstash.com/api/v1/upload/request" \
  -H "Content-Type: application/json" \
  -d '{
    "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
  }'

curl -X POST "https://app.buildstash.com/api/v1/upload/request" \  -H "Content-Type: application/json" \  -d '{    "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\""
        }
      }
    }
  ]
}

{
  "message": "Error message explaining why the upload failed"
}

{
  "message": "Unauthorized"
}

Request to Start Upload

Authorization

Request Body

Response Body

200application/json

400application/json

401application/json

application/json

application/json

application/json