Favicon

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

Choosing the Right Applivery API for Build Uploads: Integrations API vs. Workspace API

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.