# Attach Files to Build

> Attach supplementary files (dSYMs, test reports, release notes) to Applivery Builds using the Integrations or Workspace API.

Source: https://docs.applivery.com/en/app-distribution/api/builds/attached-files/  •  Last updated: 2026-03-31

**Key topics:** Attaching files to builds, Integrations API, Workspace API, API authentication, API endpoints, Applivery, App API Token, Service Account, dSYM files, CI/CD pipelines

---

**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.

:::info
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](https://www.applivery.com/app-distribution-pricing/).
:::

---

## 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](https://docs.applivery.com/en/app-distribution/api/app-api-token/).

### 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](https://docs.applivery.com/en/app-distribution/api/builds/upload-build/) and [GET – List of Builds](https://docs.applivery.com/en/app-distribution/api/builds/list-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

```bash
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

**✓ 200 OK**

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

```json
{
  "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"
  }
}
```

**✗ 400 Bad Request**

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

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

**✗ 401 Unauthorized**

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

**✗ 404 Not Found**

```json
{
  "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](https://docs.applivery.com/en/platform/api/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

```bash
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` |