# Create Publication

> Create App Store Publications in Applivery using the Integrations API or Workspace API. Control app distribution and access.

Source: https://docs.applivery.com/en/app-distribution/api/publications/create-publication/  •  Last updated: 2026-04-01

**Key topics:** Applivery Publications, Integrations API, Workspace API, API Authentication, Build Selection Filters, Applivery, App API Token, Service Account token

---

**TL;DR:** Create and manage Applivery App Store publications programmatically using the Integrations or Workspace API to control app distribution and access.

Create a new Publication in the Applivery App Store. A Publication is the distribution configuration that controls how and to whom a specific Build (or set of Builds) of an App is made available — including its URL slug, security mode, visibility, access filters, and branding overrides.

For a conceptual overview of Publications and how they relate to Builds, see [How to Distribute Your Apps](https://docs.applivery.com/en/app-distribution/distribute/distribute-apps/).

Applivery provides two separate APIs for creating Publications, each requiring a different authentication credential.

* * *

## Choosing the right API

|  | Integrations API | Workspace API |
| --- | --- | --- |
| **Designed for** | Per-app 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 `storeId` required in the path |
| **Typical users** | Scripts that auto-publish after a Build is uploaded | Platform engineers managing Publications 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 creating Publications 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://api.applivery.io/v1/integrations/distributions
```

### Authentication

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

### Request format

`application/json`

* * *

### Parameters

Parameters are grouped by area of configuration.

#### Required parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `slug` | String | The URL-friendly identifier for this Publication. Must be unique within your Workspace. Used to construct the Publication URL: `yourworkspace.applivery.com/{slug}`. Only lowercase letters, numbers, and hyphens allowed. |
| `security` | String | Authentication mode. Allowed values: `public`, `password`, `logged`. See Security modes below. |
| `visibility` | String | Publication visibility. Allowed values: `active`, `inactive`, `unlisted`. See Visibility modes below. |
| `filter.type` | String | Build selection strategy. Allowed values: `last`, `build`, `Builds`, `gitBranch`, `gitTag`, `tag`. See Filter configuration below. |

#### Build Selection Filter

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `filter.type` | String | Yes | Build selection strategy. See Filter configuration. |
| `filter.value` | String | Conditional | Required for `gitBranch`, `gitTag`, and `tag` filter types. The branch name, git tag, or build tag to match. |
| `filter.ios` | String | Conditional | Build ID for the iOS build. Required when `filter.type` is `build` and the App has iOS Builds. |
| `filter.android` | String | Conditional | Build ID for the Android build. Required when `filter.type` is `build` and the App has Android Builds. |
| `filter.macos` | String | Conditional | Build ID for the macOS build. Required when `filter.type` is `build` and the App has macOS Builds. |
| `filter.Builds` | Array | Conditional | Required when `filter.type` is `Builds`. Array of objects with `buildPlatform` and `id`. |
| `filter.Builds[].buildPlatform` | String | Conditional | Platform identifier. Supported values: `ios`, `macos`, `android`, `ps4`, `ps5`, `switch`, `xbox-one`, `xbox-series`. |
| `filter.Builds[].id` | String | Conditional | Build ID for the specified platform. |

#### Access Control

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `password` | String | Conditional | Required when `security` is `password`. The password users must enter to access the Publication. |
| `groups` | Array | No | Restricts access to specific User Groups. Supports AND/OR logic. Each inner array is an AND clause; each outer element is an OR clause. E.g. to allow users in group1 AND group2, OR users in group3: `[["group1","group2"],["group3"]]`. Only applies when `security` is `logged`. |
| `activateUserAudiences` | Boolean | No | Whether to enable audience-based access for this Publication. |
| `userAudienceMap` | Array | No | Array of audience assignments. Each element defines an audience and its notification preference. |
| `userAudienceMap[].id` | String | Conditional | ID of the audience to assign to this Publication. |
| `userAudienceMap[].notifyNewBuildsProcessed` | Boolean | No | Whether users in this audience should receive notifications when a new Build is processed. |
| `allowedCountries` | Array | No | ISO 3166-1 alpha-2 country codes to **allow** access from. If set, only users from these countries can access the Publication. Cannot be combined with `blockedCountries`. |
| `blockedCountries` | Array | No | ISO 3166-1 alpha-2 country codes to **block** access from. Cannot be combined with `allowedCountries`. |

#### Build Display Options

| Parameter | Type | Required | Description |
|---|---|---|---|
| `tags` | Array | No | Tags to categorize this Publication. Comma-separated. E.g. `["staging", "sprint-42"]`. |
| `showHistory` | Boolean | No | Whether users can browse and install previous Builds of the App. Default: `false`. |
| `showDevInfo` | Boolean | No | Whether to display technical build information (git metadata, certificate details, tags) to users. Default: `false`. |
| `expirationDate` | String | No | ISO 8601 timestamp after which the Publication becomes unavailable for download. Use to create time-limited distributions, beta programs, or promotional campaigns. E.g. `"2025-12-31T23:59:59Z"`. Once expired, the Publication behaves as if set to `inactive`. |

#### Legal Terms

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `terms.active` | Boolean | No | Whether users must accept legal terms before accessing the Publication. |
| `terms.text` | String | Conditional | Required when `terms.active` is `true`. The legal terms text to display. |

#### Branding and App configuration overrides

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `configuration.application.name` | String | No | Overrides the App name displayed in the Publication. |
| `configuration.application.description` | String | No | Overrides the App description displayed in the Publication. |
| `configuration.branding.logo` | String | No | Overrides the store logo for this Publication. |
| `configuration.branding.primaryColor` | String | No | Overrides the primary branding color (hex format). E.g. `#FF5733`. |
| `configuration.branding.buttonColor` | String | No | Overrides the button color (hex format). |

* * *

### Security modes

| Value | Description |
| --- | --- |
| `public` | No authentication required. Anyone with the Publication URL can access and download. |
| `password` | A password (specified in the `password` field) is required to access the Publication. |
| `logged` | Users must be logged in with an Applivery account or your Workspace SSO to access the Publication. |

### Visibility modes

| Value | Description |
| --- | --- |
| `active` | The Publication is listed in the App Store and accessible to all authorized users. |
| `inactive` | The Publication is not accessible to anyone. |
| `unlisted` | The Publication is not listed in the App Store but is accessible to anyone who has the direct URL. |

### Filter configuration

| `filter.type` | Description |
| --- | --- |
| `last` | Always serves the most recently processed build. No additional `filter.value` needed. |
| `build` | Serves a specific Build, identified by `filter.ios`, `filter.android`, or `filter.macos`. |
| `Builds` | Serves specific Builds per platform, defined in `filter.Builds`. Supports custom platforms. |
| `gitBranch` | Serves the latest Build matching the git branch specified in `filter.value`. E.g. `develop`. |
| `gitTag` | Serves the Build matching the git tag specified in `filter.value`. E.g. `v2.4.0`. |
| `tag` | Serves Builds matching the Applivery build tag specified in `filter.value`. |

* * *

### Example Request

Minimal Publication — public, always serving the latest Build:

```bash
curl 'https://api.applivery.io/v1/integrations/distributions' \
  -X POST \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my-app-staging",
    "security": "public",
    "visibility": "active",
    "filter": {
      "type": "last"
    }
  }'
```

Private Publication with group access control and build history:

```bash
curl 'https://api.applivery.io/v1/integrations/distributions' \
  -X POST \
  -H 'Authorization: Bearer YOUR_APP_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my-app-internal",
    "security": "logged",
    "visibility": "active",
    "filter": {
      "type": "gitBranch",
      "value": "develop"
    },
    "groups": [["qa-team", "developers"]],
    "showHistory": true,
    "showDevInfo": true,
    "tags": ["internal", "qa"]
  }'
```

* * *

### Responses

**✓ 200 OK**

:::info
The `distributionUrl` field in the response contains the full public URL of the created Publication. Share this URL with your users to give them access to the Publication.
:::

```json
{
  "status": true,
  "data": {
    "id": "string",
    "updatedAt": "string",
    "createdAt": "string",
    "application": "string",
    "applicationInfo": {
      "id": "string",
      "slug": "string",
      "name": "string",
      "picture": "string"
    },
    "slug": "string",
    "filter": {
      "type": "last",
      "value": "string",
      "ios": "string",
      "android": "string",
      "windows": "string",
      "macos": "string",
      "builds": [
        {
          "buildPlatform": "string",
          "id": "string"
        }
      ]
    },
    "security": "public",
    "tags": ["string"],
    "groups": [["string"]],
    "visibility": "active",
    "showHistory": true,
    "showDevInfo": true,
    "distributionUrl": "string",
    "terms": {
      "active": true,
      "text": "string"
    }
  }
}
```

**✗ 400 Bad Request**

Slug already in use.

```json
{
  "status": false,
  "error": {
    "code": 5024,
    "message": "Slug already used"
  }
}
```

**✗ 401 Unauthorized**

```json
{
  "status": false,
  "error": {
    "code": 4002,
    "message": "No auth token"
  }
}
```

**✗ 404 Not Found**

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

* * *

## Workspace API

Use this endpoint when creating Publications at the Workspace level — for example, in platform engineering workflows 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://api.applivery.io/v1/organizations/{organizationId}/stores/{storeId}/pubApps
```

### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | String | Yes | The unique identifier of your Applivery organization. |
| `storeId` | String | Yes | The unique identifier of the store (app project) to create the Publication in. |

### Authentication

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

### Example request

```bash
curl 'https://api.applivery.io/v1/organizations/ORG_ID/stores/STORE_ID/pubApps' \
  -X POST \
  -H 'Authorization: Bearer YOUR_SERVICE_ACCOUNT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "slug": "my-app-release",
    "security": "public",
    "visibility": "active",
    "filter": {
      "type": "last"
    }
  }'
```

The request body parameters and response schema are identical to the Integrations API.