What is an Applivery publication?

A publication in Applivery controls how a specific app build is distributed, including its URL, security, visibility, and access filters.

What are the required parameters for creating an Applivery publication?

The required parameters are `slug` (URL identifier), `security` (authentication mode), `visibility` (publication visibility), and `filter.type` (build selection strategy).

What authentication methods can I use to create a publication in Applivery?

You can use either an App API Token (for the Integrations API) or a Service Account token (for the Workspace API).

What are the allowed values for the `security` parameter in an Applivery publication?

The allowed values for the `security` parameter are `public`, `password`, and `logged`.

What are the allowed values for the `visibility` parameter in an Applivery publication?

The allowed values for the `visibility` parameter are `active`, `inactive`, and `unlisted`.

What is the purpose of the `slug` parameter when creating a publication?

The `slug` parameter is a URL-friendly identifier for the publication, used to construct the publication URL (yourworkspace.applivery.com/{slug}).

What build selection strategies are available when creating an Applivery publication?

Available build selection strategies include `last`, `build`, `builds`, `gitBranch`, `gitTag`, and `tag`, specified via the `filter.type` parameter.

Create Applivery App Store Publications via API

Q: When should I use the Integrations API to create a publication?

Use the Integrations API when creating publications within the scope of a single app, typically in per-app CI/CD pipelines.

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.

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.

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.

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:

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:

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

Note

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.

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

Slug already in use.

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

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

{
  "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.

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

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.

Creating App Store Publications with the API

Choosing the right API

Integrations API

Endpoint

Authentication

Request format

Parameters

Required parameters

Build Selection Filter

Access Control

Build Display Options

Legal Terms

Branding and App configuration overrides

Security modes

Visibility modes

Filter configuration

Example Request

Responses

Workspace API

Endpoint

Path parameters

Authentication

Example request

Key Takeaways