# Update Build

> Update the editable metadata of an existing Build in Applivery using the Integrations API or Workspace API — version name, tags, changelog, and more.

Source: https://docs.applivery.com/en/app-distribution/api/builds/update-build/  •  Last updated: 2026-06-09

**Key topics:** Build metadata update, Integrations API, Workspace API, API authentication, Applivery, App API Token, Service Account

---

**TL;DR:** Update Build metadata in Applivery via the Integrations API (App API Token) or Workspace API (Service Account token). Only the fields you include are updated — the rest are left unchanged.

Updates the editable metadata of an existing Build — version name, tags, changelog, and, for the Workspace API, additional fields like custom metadata, default scripts, and disabled state. The build binary and processing information are not affected.

Only include the fields you want to change. Fields not included in the request body retain their current values.

Applivery provides two separate APIs for updating Builds, each requiring a different authentication credential.

---

## Choosing the Right API

| | Integrations API | Workspace API |
|---|---|---|
| **Designed for** | Per-app integrations and CI/CD pipelines | Workspace-level automation across multiple Apps |
| **Authentication** | App API Token (per-app) | Service Account token (Workspace-level) |
| **App context** | Implicit — token is already scoped to an App | Explicit — `organizationId` and `applicationId` required in the path |
| **Available fields** | `versionName`, `tags`, `changelog` | All of the above, plus `metadata`, `defaultScripts`, `disabled` |
| **Typical users** | CI scripts updating labels and notes after upload | Platform engineers managing build metadata 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 to update Build metadata 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

```
PUT https://api.applivery.io/v1/integrations/builds/{buildId}
```

### Authentication

```
Authorization: Bearer <your_app_token>
```

### Request format

`application/json`

### Path Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `buildId` | String | Yes | The unique identifier of the Build to update. 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/). |

### Parameters

| Parameter | Type | Description |
|---|---|---|
| `versionName` | String | Human-readable version label for this Build. E.g. `RC-2`, `v2.5.0-beta`. |
| `tags` | Array | List of tags to categorize the Build. Replaces the existing tags array. E.g. `["staging", "sprint-43"]`. |
| `changelog` | String | Release notes or description of changes in this Build. |

### Example Request

```bash
curl 'https://api.applivery.io/v1/integrations/builds/552ae3cfcb5abfc58d733b81' \
  -X PUT \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "versionName": "v2.5.0-rc2",
    "tags": ["staging", "sprint-43"],
    "changelog": "Fixed crash on settings screen"
  }'
```

### Responses

**✓ 200 OK**

```json
{
  "status": true,
  "data": {
    "id": "string",
    "status": "success",
    "tags": ["string"],
    "versionName": "string",
    "application": "string",
    "applicationInfo": {
      "id": "string",
      "name": "string",
      "slug": "string",
      "picture": "string"
    },
    "changelog": "string",
    "os": "ios",
    "versionCode": "string",
    "deployer": {
      "name": "string",
      "info": {
        "commitMessage": "string",
        "commit": "string",
        "branch": "string",
        "tag": "string"
      }
    },
    "uploadedBy": {
      "id": "string",
      "email": "user@example.com",
      "firstName": "string",
      "lastName": "string"
    },
    "updatedAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z"
  }
}
```

**✗ 401 Unauthorized**

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

**✗ 404 Not Found**

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

---

## Workspace API

Use this endpoint when updating Builds at the Workspace level — for example, in platform engineering workflows where a single credential manages metadata across multiple Apps.

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/).

:::info
This endpoint requires the `mad.build.management.update` permission on the Service Account.
:::

### Endpoint

```
PUT https://api.applivery.io/v1/organizations/{organizationId}/apps/{applicationId}/builds/{buildId}
```

### 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 update. |

### Authentication

```
Authorization: Bearer <your_service_account_token>
```

### Request format

`application/json`

### Parameters

In addition to the `versionName`, `tags`, and `changelog` fields available in the Integrations API, the Workspace API exposes the following fields:

| Parameter | Type | Description |
|---|---|---|
| `metadata` | Object | Custom key-value metadata object for storing additional build information. |
| `defaultScripts.preInstall` | String | Script to run before the Build is installed on a device. |
| `defaultScripts.postInstall` | String | Script to run after the Build is installed on a device. |
| `defaultScripts.audit` | String | Audit script associated with this Build. |
| `defaultScripts.enforce` | String | Enforcement script associated with this Build. |
| `defaultScripts.runner` | String | Script runner configuration for this Build. |
| `disabled` | Boolean | Whether the Build is disabled. Disabled Builds cannot be downloaded. |

### Example Request

```bash
curl 'https://api.applivery.io/v1/organizations/ORG_ID/apps/APP_ID/builds/552ae3cfcb5abfc58d733b81' \
  -X PUT \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "versionName": "v2.5.0-rc2",
    "changelog": "Fixed crash on settings screen",
    "tags": ["staging", "sprint-43"],
    "metadata": {
      "environment": "staging",
      "team": "mobile"
    }
  }'
```

The response schema is identical to the Integrations API. A successful update returns `{ "status": true, "data": { ... } }` with the updated Build object.