Request to Start Upload

This endpoint initiates the build upload process by requesting presigned URLs. Requires builds:create scope. 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.

When using a Workspace API key, the application_id field is required to specify which application the build belongs to. Application-level keys target their app automatically.

You can optionally attach labels, specify architectures, provide CI/CD pipeline metadata (pipeline name, run ID, URL, duration), and version control details (host, repo, branch, commit) to enrich the build record.

POST/upload/request

Authorization

bearerAuth

AuthorizationBearer <token>

API key. Bearer authentication header of the form Bearer <token>, where <token> is your Workspace or Application API key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Initiate a build file upload.

application_id?string

Application ID. Required when using a Workspace API key.

Example"aBc1234"

structure*string

Upload structure type. Use 'file' unless including an Android OBB expansion file.

Default"file"

Value in

"file"
"file+expansion"

platform*string

Platform identifier. Must match an enabled platform slug. See Platforms for the full list.

Example"windows"

custom_target?|

Custom target for this build. Must exactly match the name of a target you've defined.

Lengthlength <= 20

Example"Samsung Galaxy Store"

stream*string

Stream name. Must match exact name setup in your app.

Match^[\w\-\+]+$

Lengthlength <= 12

Example"nightlies"

source*string

Source of the upload. See Build Sources for valid identifiers.

Example"ghactions"

primary_file*

expansion_files?array<>

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

Itemsitems <= 1

version_component_1_major*integer

Semantic versioning: Major version component

Range0 <= value <= 9999

Example1

version_component_2_minor*integer

Minor version component

Range0 <= value <= 9999

Example0

version_component_3_patch*integer

Patch version component. At least one version component must be greater than zero.

Range0 <= value <= 9999

Example1

version_component_extra?|

Optional pre-release label such as 'alpha', 'beta', 'rc'

Match^[a-zA-Z0-9\-]+(\.[a-zA-Z0-9\-]+)*$

Lengthlength <= 25

Example"alpha"

version_component_meta?|

Optional metadata such as build number or commit hash

Match^[a-zA-Z0-9\-]+(\.[a-zA-Z0-9\-]+)*$

Lengthlength <= 64

Example"2025.07.30"

custom_build_number?|

Custom build number. Alphanumeric characters, dots, underscores, and hyphens only.

Match^[a-zA-Z0-9._-]*$

Lengthlength <= 100

Example"398"

labels?array<>

Labels for the build (will be created if they do not already exist). Each label name may be up to 25 characters.

Itemsitems <= 10

Example

[  "signed",  "to-test"]

architectures?array<>

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

Itemsitems <= 15

Example

[  "x64",  "arm64v8"]

notes?|

Additional notes

Lengthlength <= 1000

Example"Example build notes here."

ci_pipeline?|

CI pipeline name

Lengthlength <= 100

Example"Nightly Build"

ci_run_id?|

CI run ID (numeric, up to 30 digits).

Match^[0-9]+$

Lengthlength <= 30

Example"12345678901"

ci_run_url?|

CI run URL

Example"https://github.com/buildstash/example/actions/runs/12345678901"

ci_build_duration?|

CI build duration.

Match^[a-zA-Z0-9.: -]+$

Lengthlength <= 30

Example"00:05:00"

vc_host_type?|

Version control host type. scm_host_type is accepted as an alias. See SCM Host Types for valid identifiers.

Example"git"

vc_host?|

Version control host. scm_host is accepted as an alias. See SCM Sources for valid identifiers.

Example"github"

vc_repo_name?|

Repository name

Lengthlength <= 200

Example"buildstash/example"

vc_repo_url?|

Repository URL

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

vc_branch?|

Branch name

Lengthlength <= 100

Example"main"

vc_commit_sha?|

Commit SHA (alphanumeric, up to 40 characters).

Match^[a-zA-Z0-9]+$

Lengthlength <= 40

Example"1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"

vc_commit_url?|

Commit URL

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

ci_pipeline_url?|

CI pipeline URL.

Example"https://github.com/buildstash/example/actions/workflows/nightly.yml"

Response Body

`application/json`

curl -X POST "https://example.comupload/request" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d @- <<'EOF'{  "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}EOF

{  "message": "Upload request successful.",  "pending_upload_id": "550e8400-e29b-41d4-a716-446655440000",  "primary_file": {    "filename": "example.exe",    "presigned_data": {      "url": "https://buildstash.s3.amazonaws.com/aBc1234/xYz9876/example.exe?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAEXAMPLE%2F20250615%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250615T143000Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=abc123",      "headers": {        "Content-Type": "application/octet-stream"      }    },    "chunked_upload": false,    "chunked_number_parts": null,    "chunked_part_size_mb": null  },  "expansion_files": []}

{  "message": "Unauthorized"}

Empty

{  "message": "string",  "errors": {    "property1": [      "string"    ],    "property2": [      "string"    ]  }}

Request to Start Upload

Authorization

Request Body

Response Body

200application/json

401application/json

415

422application/json

`application/json`

`application/json`

`application/json`