Favicon

You are here: Home > App Distribution > API > Builds > POST - Build Attached Files

POST - Build Attached Files

Learn how to attach supplementary files (dSYMs, test reports, release notes) to Applivery builds using the Integrations or Workspace API.

5 min read

TL;DR

Attach supplementary files to Applivery builds using the Integrations API (per-app) or the Workspace API (workspace-level).

Attaches one or more supplementary files to an existing build. This is useful for associating additional assets with a build — such as release notes documents, test reports, dSYM files for crash symbolication, mapping files, screenshots, or any other file you want to make available alongside the build in Applivery.

Attached files are separate from the build binary itself and do not affect the build's installation or processing. They are displayed in the build's detail view in the Applivery dashboard and are accessible via the API.

Note

The build must have a status of processed before files can be attached. Attempting to attach files to a build that is still pending or in_progress will return a 400 error.

Applivery provides two separate APIs for attaching files, each requiring a different authentication credential.

Choosing the right API

Integrations API Workspace API
Designed for CI/CD pipelines attaching artifacts per-app Workspace-level automation across multiple apps
Authentication App API Token (per-app) Service Account token (workspace-level)
Base URL https://upload.applivery.io https://upload.applivery.io
App context Implicit — token is already scoped to an app Explicit — organizationId and applicationId required in the path
Typical users CI scripts attaching test reports or dSYM files after a build Platform engineers managing build artifacts across multiple apps
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 attaching files within the scope of a single app. Authentication uses an App API Token, scoped to the specific app.

To create an App API Token, see Apps API Authentication.

Endpoint

POST https://upload.applivery.io/v1/integrations/builds/{buildId}/files

Authentication

Authorization: Bearer <your_app_token>

Request format

multipart/form-data

Path parameters

Parameter Type Required Description
buildId String Yes The unique identifier of the build to attach the file to. E.g. 552ae3cfcb5abfc58d733b81. Returned by POST – Upload a Build and GET – List of Builds.

Body parameters

Parameter Type Required Description
file File Yes The file to attach to the build. Any file type is accepted.
description String No A human-readable description of the attached file. E.g. dSYM file for crash symbolication, QA test report, Release notes PDF.

Example Request

curl 'https://upload.applivery.io/v1/integrations/builds/552ae3cfcb5abfc58d733b81/files' \
  -X POST \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -F 'file=@/path/to/report.zip' \
  -F 'description=Automated test report'

Responses

File attached successfully. The response returns the full updated build object, including the files array, which now contains the newly attached file.

{
  "status": true,
  "data": {
    "id": "string",
    "status": "processed",
    "tags": ["string"],
    "versionName": "string",
    "application": "string",
    "applicationInfo": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "picture": "string"
    },
    "changelog": "string",
    "info": {},
    "size": 0,
    "processTime": 0,
    "queuedTime": 0,
    "versionCode": "string",
    "error": "string",
    "errorCode": "string",
    "os": "ios",
    "buildPlatform": "string",
    "deployer": {},
    "uploadedBy": {},
    "originalExtension": "string",
    "storageProvider": {},
    "files": [
      {
        "id": "string",
        "type": "string",
        "description": "string",
        "file": {
          "originalName": "string",
          "mimetype": "string",
          "size": 0,
          "bucket": "string",
          "key": "string",
          "location": "string",
          "region": "string",
          "storageProviderId": "string",
          "checksum": "string",
          "updatedAt": "string",
          "createdAt": "string"
        }
      }
    ],
    "hasEmmJson": true,
    "updatedAt": "string",
    "createdAt": "string"
  }
}

Build not yet processed. Files can only be attached to builds with status: processed. Retry after the build finishes processing.

{
  "status": false,
  "error": {
    "code": 5014,
    "message": "Build Not Processed"
  }
}

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

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

Key fields in the files array

Field Description
id Unique identifier of the attached file record.
description The description provided at upload time.
file.originalName The original filename of the uploaded file.
file.mimetype The detected MIME type of the file.
file.size File size in bytes.
file.location The storage URL where the file is hosted.
file.checksum Checksum for integrity verification.

Workspace API

Use this endpoint when attaching files at the workspace level — for example, in automation pipelines that operate across multiple apps using a single credential.

Authentication uses a Service Account token, which is workspace-scoped and not tied to any individual app.

To create a Service Account, see Service Accounts.

Endpoint

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

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 the build belongs to.
buildId String Yes The unique identifier of the build to attach the file to.

Authentication

Authorization: Bearer <your_service_account_token>

Example Request

curl 'https://upload.applivery.io/v1/organizations/ORG_ID/apps/APP_ID/builds/BUILD_ID/files' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  -F 'file=@/path/to/mapping.txt' \
  -F 'description=ProGuard mapping file'

The response schema is identical to the Integrations API.

Common use cases

File type Example description
iOS dSYM archive dSYM file for crash symbolication
Android ProGuard mapping ProGuard mapping file
Automated test report XCTest results — regression suite
QA sign-off document QA approval — v2.4.0
Release notes PDF Release notes for stakeholders
Screenshot set App Store screenshots — en-US

Key Takeaways

  • Applivery provides two APIs for attaching files: Integrations API and Workspace API.
  • The Integrations API uses an App API Token for authentication and is scoped to a single app.
  • The Workspace API uses a Service Account token for authentication and is workspace-scoped.
  • Files can only be attached to builds with a 'processed' status.
  • Attached files are displayed in the build's detail view in the Applivery dashboard.