Build upload API

The build upload API provides a mechanism to upload a new build of your app to Mesmer for automated testing. It’s intended primarily for use with CI/CD systems.

Mesmer accepts builds for Android and iOS as described in the documentation for uploading your first app build.

When the upload is complete, Mesmer will run tests against the app. Use the tags field in the request body to determine which tagged test cases to run.

You can indicate that Mesmer should, instead instead of running tests, crawl the uploaded app by passing a Data header with the value {"exec":"crawl"}.

After successfully uploading a build, you can monitor its progress using project stats API and build stats API.


You will need the following items of configuration in order to call this API:

  • Console URL The URL to your Mesmer console, including both the scheme and host. (e.g. This URL also hosts the API endpoint for your account.

  • Access token The security token (API key) assigned to your account. You can get this string from your Mesmer contact.

Request protocol

Endpoint URL


HTTP method


HTTP headers

  • X-Access-Token

REQUIRED: <your access token>

  • Origin

REQUIRED: <your console url>

  • Content-Type

REQUIRED: multipart/form-data

  • Data

OPTIONAL: Serialized JSON object with extra options. Currently only accepts these two literal strings:

{"exec":"crawl"} indicates that Mesmer should crawl the app instead of running tests.

{"exec":"replay"} indicates that Mesmer should run tests against the build. This is the same behavior as no Data header at all.

Request body form fields

  • file

REQUIRED: Attached app build file to upload.

  • projectName

OPTIONAL: Name of the project to upload to. If a project with this name doesn’t already exist, a new project will be created with this name. If omitted, Mesmer will find the matching project based on the properties of the uploaded app.

  • tags

OPTIONAL: Serialized JSON array containing a list of tags previously assigned to test cases in the Mesmer console. For example:


Only the test cases with any these tags will be run upon successful upload. If this field is omitted, Mesmer will execute all tests.

Example request using curl

curl \
$YOUR_CONSOLE_URL/api/v1/build/upload \
-H 'X-Access-Token: <your-access-token>' \
-H 'Origin: <your-console-url>' \
-H 'Content-Type: multipart/form-data' \
-H 'Data: {"exec": "crawl"}' \
-F 'file=@/path/to/apk-ipa-app-zip.file' \
-F 'projectName=<project-name>' \
-F 'tags=["regression","smoke","sanity"]'

Response payload

The response is JSON BuildUploadResponse object containing a nested BuildMetadata object describing the build that was successfully uploaded.

Example response payload

"success": true,
"data": {
"projectId": "<project-id>",
"projectName": "<project-name>",
"projectPackage": "<project-package-name>",
"projectType": "<project-type-android-ios>",
"buildId": "<build-id>",
"buildName": "<build-name>",
"buildPackage": "<build-package-name>",
"buildType": "<build-type-apk-ipa-app-zip>",
"buildVersion": "<build-version>"