Favicon

You are here: Home > App Distribution > API > Builds > POST - Upload a Build

POST - Upload a Build

Learn about Applivery's two distinct APIs for uploading builds: Integrations API for CI/CD and Workspace API for multi-app management. Choose the right one for your needs.

5 min read

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

Integrations API

Workspace API

Designed for

CI/CD pipelines, build tools, and per-app integrations

Workspace-level automation and multi-app management

Authentication

App API Token (per-app)

Service Account token (workspace-level)

Base URL

https://upload.applivery.io

https://api.applivery.io

App context

Implicit — token is already scoped to an app

Explicit — organizationId and applicationId required in the path

Typical users

Fastlane, Bitrise, Jenkins, Azure DevOps, custom CI scripts

Platform engineers managing multiple apps programmatically

Warning

Access to the different APIs might not be available in your current plan. Please check availability on our pricing page.

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.

Endpoint

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

Authentication

Authorization: Bearer <your_app_token>

Request format

multipart/form-data

Parameters

Build file

Parameter

Type

Required

Description

build

File

Yes

The build file to upload. Supported formats: .ipa, .apk, .aab. See Custom Build Platforms for additional supported formats.

buildPlatform

String

Conditional

Required when uploading a Custom Build Platform. Values: ios, android, or a custom platform identifier.

packageName

String

Conditional

Required when the build file cannot be processed automatically (e.g., custom platforms). The app's unique identifier.

packageVersion

String

Conditional

Required when the build file cannot be processed automatically. The version string for this build.

packageIcon

File

Conditional

Required when the build file cannot be processed automatically. Must be .png or .jpeg.

Build metadata

Parameter

Type

Required

Description

versionName

String

No

Human-readable version label for this build. E.g. RC-1, v2.4.0-beta.

tags

Array

No

Comma-separated list of tags to categorize the build. E.g. staging, sprint-42, hotfix.

changelog

String

No

Release notes or description of changes in this build. Supports plain text.

Notifications

Parameter

Type

Required

Description

notifyCollaborators

Boolean

No

Whether to send an email notification to app and workspace collaborators. Default: false.

notifyEmployees

Boolean

No

Whether to send an email notification to store employees. Default: false.

notifyMessage

String

No

Custom message to include in the notification email. E.g. New build ready for testing!.

notifyLanguage

String

No

Language for the notification email. Supported values: en, es, fr, de, it, zh, pt, ru.

filter

Nested array

No

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: [["group1","group2"],["group3"]].

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.

Parameter

Type

Description

deployer.name

String

Display name for the CI/CD system. E.g. Jenkins CI, Bitrise, GitHub Actions.

deployer.info.commitMessage

String

Git commit message associated with this build.

deployer.info.commit

String

Git commit SHA. E.g. f52ace0.

deployer.info.branch

String

Git branch name. E.g. develop, release/2.4.

deployer.info.tag

String

Git tag associated with this build. E.g. RC-1, v2.4.0.

deployer.info.triggerTimestamp

String

Unix timestamp (ms) of when the CI build was triggered. E.g. 1558359012580.

deployer.info.buildUrl

String

Direct URL to the CI build run.

deployer.info.ciUrl

String

Base URL of the CI platform.

deployer.info.repositoryUrl

String

URL of the version control repository.

deployer.info.buildNumber

String

CI platform's build number. E.g. 173.

Example Request

curl 'https://upload.applivery.io/v1/integrations/builds' \
  -X POST \
  --retry 5 \
  --fail \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -F '[email protected]' \
  -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

{
  "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": "[email protected]",
      "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"
  }
}

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

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

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

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 endpoint to poll for the final status if needed.

For a full list of error codes returned during build processing, see Build Processing 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.

Endpoint

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

Path Parameters

Parameter

Type

Required

Description

organizationId

String

Yes

The unique identifier of your Applivery organization.

applicationId

String

Yes

The unique identifier of the app to upload the build to.

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

curl 'https://upload.applivery.io/v1/organizations/ORG_ID/apps/APP_ID/builds' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  -F '[email protected]' \
  -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'

Key Takeaways

  • Applivery offers two APIs for build uploads, each suited for different use cases.
  • The Integrations API is designed for CI/CD pipelines and uses an App API Token.
  • The Workspace API is designed for workspace-level automation and uses a Service Account token.
  • Understanding the authentication method and required parameters is crucial for successful build uploads.
  • CI/CD deployer information can be included to trace builds back to their origin.