# Upload Build

> Applivery offers two APIs for uploading Builds: Integrations API for CI/CD and Workspace API for multi-app management. Choose the right one for your use.

Source: https://docs.applivery.com/en/app-distribution/api/builds/upload-build/  •  Last updated: 2026-06-17

**Key topics:** Integrations API, Workspace API, App API Token, Service Account Token, Build Upload Parameters, Applivery, Fastlane, Bitrise, Jenkins, Azure DevOps

---

**TL;DR:** Applivery provides two APIs for build uploads: Integrations API for CI/CD using an App API Token, and Workspace API for multi-app management using a Service Account token.

Applivery provides **two separate APIs** for uploading Builds, each designed for a different use case and requiring a different authentication credential. It is important to understand which one applies to your workflow before integrating.

* * *

## Choosing the right API

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p></p></th><th colspan="1" rowspan="1"><p>Integrations API</p></th><th colspan="1" rowspan="1"><p>Workspace API</p></th></tr><tr><td colspan="1" rowspan="1"><p><strong>Designed for</strong></p></td><td colspan="1" rowspan="1"><p>CI/CD pipelines, build tools, and per-app integrations</p></td><td colspan="1" rowspan="1"><p>Workspace-level automation and multi-app management</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Authentication</strong></p></td><td colspan="1" rowspan="1"><p>App API Token (per-app)</p></td><td colspan="1" rowspan="1"><p>Service Account token (Workspace-level)</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Base URL</strong></p></td><td colspan="1" rowspan="1"><p><code>https://upload.applivery.io</code></p></td><td colspan="1" rowspan="1"><p><code>https://upload.applivery.io</code></p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>App context</strong></p></td><td colspan="1" rowspan="1"><p>Implicit — token is already scoped to an App</p></td><td colspan="1" rowspan="1"><p>Explicit — <code>organizationId</code> and <code>applicationId</code> required in the path</p></td></tr><tr><td colspan="1" rowspan="1"><p><strong>Typical users</strong></p></td><td colspan="1" rowspan="1"><p>Fastlane, Bitrise, Jenkins, Azure DevOps, custom CI scripts</p></td><td colspan="1" rowspan="1"><p>Platform engineers managing multiple Apps programmatically</p></td></tr></tbody></table>

:::warning
Access to the different APIs might not be available in your current plan. Please check availability on our [pricing page](https://www.applivery.com/app-distribution-pricing/).
:::

* * *

## Integrations API

Use this endpoint when uploading Builds from a CI/CD pipeline or any integration that operates within the scope of a single app. Authentication uses an **App API Token**, which is scoped to the specific App you are uploading to.

To create an App API Token, see [Apps API Authentication](https://docs.applivery.com/en/app-distribution/api/app-api-token/).

### Endpoint

```
POST https://upload.applivery.io/v1/integrations/builds
```

### Authentication

```
Authorization: Bearer <your_app_token>
```

### Request format

`multipart/form-data`

### Parameters

**Build file**

<table style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Parameter</p></th><th colspan="1" rowspan="1"><p>Type</p></th><th colspan="1" rowspan="1"><p>Required</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>build</code></p></td><td colspan="1" rowspan="1"><p>File</p></td><td colspan="1" rowspan="1"><p>Yes</p></td><td colspan="1" rowspan="1"><p>The Build file to upload. Supported formats: <code>.ipa</code>, <code>.apk</code>, <code>.aab</code>. See Custom Build Platforms for additional supported formats.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>buildPlatform</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Conditional</p></td><td colspan="1" rowspan="1"><p>Required when uploading a Custom Build Platform. Values: <code>ios</code>, <code>android</code>, or a custom platform identifier.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>packageName</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Conditional</p></td><td colspan="1" rowspan="1"><p>Required when the Build file cannot be processed automatically (e.g., custom platforms). The App's unique identifier.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>packageVersion</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Conditional</p></td><td colspan="1" rowspan="1"><p>Required when the Build file cannot be processed automatically. The version string for this Build.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>packageIcon</code></p></td><td colspan="1" rowspan="1"><p>File</p></td><td colspan="1" rowspan="1"><p>Conditional</p></td><td colspan="1" rowspan="1"><p>Required when the Build file cannot be processed automatically. Must be <code>.png</code> or <code>.jpeg</code>.</p></td></tr></tbody></table>

**Build metadata**

<table style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Parameter</p></th><th colspan="1" rowspan="1"><p>Type</p></th><th colspan="1" rowspan="1"><p>Required</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>versionName</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Human-readable version label for this Build. E.g. <code>RC-1</code>, <code>v2.4.0-beta</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>tags</code></p></td><td colspan="1" rowspan="1"><p>Array</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Comma-separated list of tags to categorize the Build. E.g. <code>staging, sprint-42, hotfix</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>changelog</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Release notes or description of changes in this Build. Supports plain text.</p></td></tr></tbody></table>

**Notifications**

<table style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Parameter</p></th><th colspan="1" rowspan="1"><p>Type</p></th><th colspan="1" rowspan="1"><p>Required</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>notifyCollaborators</code></p></td><td colspan="1" rowspan="1"><p>Boolean</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Whether to send an email notification to app and Workspace Collaborators. Default: <code>false</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>notifyEmployees</code></p></td><td colspan="1" rowspan="1"><p>Boolean</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Whether to send an email notification to store employees. Default: <code>false</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>notifyMessage</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Custom message to include in the notification email. E.g. <code>New Build ready for testing!</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>notifyLanguage</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Language for the notification email. Supported values: <code>en</code>, <code>es</code>, <code>fr</code>, <code>de</code>, <code>it</code>, <code>zh</code>, <code>pt</code>, <code>ru</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>filter</code></p></td><td colspan="1" rowspan="1"><p>Nested array</p></td><td colspan="1" rowspan="1"><p>No</p></td><td colspan="1" rowspan="1"><p>Limits notifications to specific employee groups. Supports AND/OR logic. Each inner array is an AND clause; each outer element is an OR clause. E.g. to notify users in group1 AND group2, OR users in group3: <code>[["group1","group2"],["group3"]]</code>.</p></td></tr></tbody></table>

**CI/CD deployer information**

These optional fields populate the Build's deployment metadata in the Applivery Dashboard, making it easy to trace a Build back to its CI/CD origin.

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Parameter</p></th><th colspan="1" rowspan="1"><p>Type</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.name</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Display name for the CI/CD system. E.g. <code>Jenkins CI</code>, <code>Bitrise</code>, <code>GitHub Actions</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.commitMessage</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Git commit message associated with this Build.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.commit</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Git commit SHA. E.g. <code>f52ace0</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.branch</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Git branch name. E.g. <code>develop</code>, <code>release/2.4</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.tag</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Git tag associated with this Build. E.g. <code>RC-1</code>, <code>v2.4.0</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.triggerTimestamp</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Unix timestamp (ms) of when the CI build was triggered. E.g. <code>1558359012580</code>.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.buildUrl</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Direct URL to the CI build run.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.ciUrl</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Base URL of the CI platform.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.repositoryUrl</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>URL of the version control repository.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>deployer.info.buildNumber</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>CI platform's build number. E.g. <code>173</code>.</p></td></tr></tbody></table>

### Example Request

```bash
curl 'https://upload.applivery.io/v1/integrations/builds' \
  -X POST \
  --retry 5 \
  --fail \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -F 'build=@file.ipa' \
  -F 'versionName=v2.4.0-rc1' \
  -F 'tags=staging, sprint-42' \
  -F 'changelog=Fixed crash on login screen' \
  -F 'notifyCollaborators=true' \
  -F 'notifyEmployees=false' \
  -F 'notifyMessage=New build ready for QA' \
  -F 'notifyLanguage=en' \
  -F 'filter[0][0]=group1' \
  -F 'filter[0][1]=group2' \
  -F 'filter[1][0]=group3' \
  -F 'deployer.name=GitHub Actions' \
  -F 'deployer.info.commitMessage=Fix crash on login' \
  -F 'deployer.info.commit=f52ace0' \
  -F 'deployer.info.branch=release/2.4' \
  -F 'deployer.info.tag=v2.4.0-rc1' \
  -F 'deployer.info.triggerTimestamp=1558359012580' \
  -F 'deployer.info.buildUrl=https://github.com/myorg/myapp/actions/runs/123' \
  -F 'deployer.info.ciUrl=https://github.com/myorg/myapp/actions' \
  -F 'deployer.info.repositoryUrl=https://github.com/myorg/myapp' \
  -F 'deployer.info.buildNumber=173'
```

### Responses

**✓ 200 OK**

```json
{
  "status": true,
  "data": {
    "id": "string",
    "status": "pending",
    "tags": ["string"],
    "versionName": "string",
    "application": "string",
    "applicationInfo": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "picture": "string"
    },
    "changelog": "string",
    "info": {
      "icon": "string",
      "android": {
        "targetSdkVersion": "string",
        "minSDKVersion": "string",
        "packageName": "string",
        "platformBuildVersionName": "string",
        "platformBuildVersionCode": "string",
        "versionName": "string",
        "versionCode": "string",
        "icon": "string"
      },
      "ios": {
        "plist": {
          "CFBundleDisplayName": "string",
          "CFBundleSupportedPlatforms": ["string"],
          "MinimumOSVersion": "string",
          "CFBundleIdentifier": "string",
          "CFBundleShortVersionString": "string",
          "CFBundleVersion": "string",
          "CFBundleName": "string",
          "CFBundleIcons": ["string"],
          "UIDeviceFamily": ["string"]
        },
        "mobileprovision": {
          "ExpirationDate": "2019-08-24T14:15:22Z",
          "TeamIdentifier": "string",
          "ProvisionsAllDevices": true,
          "TeamName": "string",
          "ProvisionedDevices": "string",
          "signingType": "ad-hoc"
        }
      },
      "pkg": {
        "CFBundleDisplayName": "string",
        "CFBundleIdentifier": "string",
        "CFBundleShortVersionString": "string",
        "CFBundleVersion": "string",
        "CFBundleName": "string"
      }
    },
    "size": 0,
    "processTime": 0,
    "queuedTime": 0,
    "versionCode": "string",
    "os": "ios",
    "deployer": {
      "name": "string",
      "info": {
        "commitMessage": "string",
        "commit": "string",
        "branch": "string",
        "triggerTimestamp": "string",
        "buildUrl": "string",
        "ciUrl": "string",
        "repositoryUrl": "string",
        "buildNumber": "string",
        "tag": "string"
      }
    },
    "uploadedBy": {
      "id": "string",
      "email": "user@example.com",
      "firstName": "string",
      "lastName": "string",
      "picture": "string"
    },
    "originalExtension": "string",
    "storageProvider": {
      "id": "string",
      "name": "string",
      "region": "string"
    },
    "updatedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z"
  }
}
```

**✗ 400 Bad Request**

```json
{
  "status": false,
  "error": {
    "code": 5024,
    "message": "Slug already used"
  }
}
```

**✗ 401 Unauthorized**

```json
{
  "status": false,
  "error": {
    "code": 3002,
    "message": "Token Expired"
  }
}
```

**✗ 404 Not Found**

```json
{
  "status": false,
  "error": {
    "code": 3001,
    "message": "Entity not found"
  }
}
```

:::info
The Build `status` in the response will initially be `pending`. Applivery processes the Build asynchronously — the status will update to `success` or `error` once processing is complete. Use the [GET – Build details](https://docs.applivery.com/en/app-distribution/api/builds/build-details/) endpoint to poll for the final status if needed.
:::

For a full list of error codes returned during build processing, see [Build Processing Codes](https://docs.applivery.com/en/app-distribution/builds/processing-error-codes/).

* * *

## Workspace API

Use this endpoint when you need to upload Builds at the Workspace level — for example, in platform engineering workflows where a single credential manages multiple Apps across an organisation.

Authentication uses a **Service Account** token, which is Workspace-scoped and not tied to any individual app. The App context is provided explicitly via path parameters.

To create a Service Account, see [Service Accounts](https://docs.applivery.com/en/platform/api/service-accounts/).

### Endpoint

```
POST https://upload.applivery.io/v1/organizations/{organizationId}/apps/{applicationId}/builds
```

### Path Parameters

<table style="min-width: 100px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Parameter</p></th><th colspan="1" rowspan="1"><p>Type</p></th><th colspan="1" rowspan="1"><p>Required</p></th><th colspan="1" rowspan="1"><p>Description</p></th></tr><tr><td colspan="1" rowspan="1"><p><code>organizationId</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Yes</p></td><td colspan="1" rowspan="1"><p>The unique identifier of your Applivery organization.</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>applicationId</code></p></td><td colspan="1" rowspan="1"><p>String</p></td><td colspan="1" rowspan="1"><p>Yes</p></td><td colspan="1" rowspan="1"><p>The unique identifier of the App to upload the Build to.</p></td></tr></tbody></table>

### Authentication

```
Authorization: Bearer <your_service_account_token>
```

### Request format

`multipart/form-data`

### Parameters

The Workspace API accepts the same build file, metadata, notification, and deployer parameters as the Integrations API.

### Example Request

```bash
curl 'https://upload.applivery.io/v1/organizations/ORG_ID/apps/APP_ID/builds' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  -F 'build=@file.apk' \
  -F 'versionName=v3.1.0' \
  -F 'changelog=Performance improvements' \
  -F 'notifyCollaborators=true' \
  -F 'deployer.name=Internal Deploy Bot' \
  -F 'deployer.info.branch=main' \
  -F 'deployer.info.buildNumber=88'
```