Creating an app version

An app version moves through the release process — from the release candidate stage through approvals, store submission, and production release.

The Store Releases sub-API base URL: https://api.bitrise.io/release-management/v2/store-releases/v1. See the Store Releases API reference for the full list of endpoints, parameters, and schemas.

Creating an app versionClick to copy link

Endpoint	Function	Required role
`POST /app-versions`	Create a new app version.	Release manager
`GET /app-versions`	List app versions for an app.	Any
`GET /app-versions/{id}`	Get details of an app version.	Any
`PATCH /app-versions/{id}`	Update an app version.	Release manager
`DELETE /app-versions/{id}`	Delete an app version.	Release manager

To create an app version:

Call POST /app-versions with the required fields:

name: The version name for this app version.
app_id: The ID of the app in Release Management (returned when you added the app).

Version format for iOS

For iOS apps, name is used as the App Store Connect version string and must follow the X.Y.Z format (e.g., 1.2.0).

curl -X POST "https://api.bitrise.io/release-management/v2/store-releases/v1/app-versions" \
  -H "Authorization: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "1.5.0",
    "app_id": "APP_ID",
    "description": "Spring feature release",
    "artifact_source": "ci"
  }'

The response includes the app version's id, which you'll use in subsequent calls.

{
  "id": "YOUR_APP_VERSION_ID",
  "name": "1.5.0",
  "status": "scheduled",
  "description": "Spring feature release",
  "connected_app_id": "YOUR_APP_ID",
  "artifact_source": "ci",
  "platform": "android",
  "store_app_id": "com.example.myapp",
  "created_at": "2026-01-01T00:00:00.000Z",
  "released_at": null,
  "release_candidate_id": null,
  "stages": [
    { "name": "release-candidate", "status": "pending" },
    { "name": "approvals", "status": "pending" },
    { "name": "app-store-review", "status": "pending" },
    { "name": "release", "status": "pending" }
  ]
}

Configuring release automationClick to copy link

You can define automation rules that trigger CI builds automatically when an app version reaches a certain stage. For a full overview of how automation works, see Release automation.

Set the automation field when creating or updating an app version:

curl -X POST "https://api.bitrise.io/release-management/v2/store-releases/v1/app-versions" \
  -H "Authorization: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "1.5.0",
    "app_id": "APP_ID",
    "artifact_source": "ci",
    "release_branch": "release/1.5.0",
    "workflow": "release",
    "automation": [
      {
        "event_name": "release_candidate_set",
        "workflow_name": "run-tests"
      },
      {
        "event_name": "approvals_completed",
        "workflow_name": "upload-to-store"
      }
    ]
  }'

Available automation event_name values depend on the platform. For the full, up-to-date list and what triggers each event, see Automation events.

iOS
Android

release_candidate_set: A new release candidate is selected.
testflight_upload_finished: TestFlight processing finishes for an uploaded build.
beta_review_approved: Apple approves the beta app review.
beta_review_rejected: Apple rejects the beta app review.
release_for_apple_app_store_testing_group: The build is released to a TestFlight testing group.
approvals_completed: All approval tasks are marked complete.
submitted_for_review: The app version is submitted for App Store review.
review_status_changed / review_cancelled: The review submission status changes.
release_started: The rollout to the App Store starts.
release_completed: The app version is fully rolled out.

release_candidate_set: A new release candidate is selected.
google_play_store_upload_finished: The build finishes uploading to the Google Play console.
release_on_google_play_store_testing_track: The release candidate is released on a Google Play testing track.
approvals_completed: All approval tasks are marked complete.
release_started: The rollout starts (full release or the first stage of a staged rollout).
release_completed: The app version is fully rolled out.
release_percentage_changed: The staged rollout percentage changes (not triggered on the first rollout).

Adding approval tasks to an app versionClick to copy link

Endpoint	Function	Required role
`POST /app-versions/{id}/approvals`	Create an approval task.	Release manager
`GET /app-versions/{id}/approvals`	List approval tasks.	Any
`PATCH /app-versions/{id}/approvals/{task_id}`	Update or complete an approval task.	Assigned user

You can create approval tasks that team members must complete before the app version proceeds.

curl -X POST "https://api.bitrise.io/release-management/v2/store-releases/v1/app-versions/APP_VERSION_ID/approvals" \
  -H "Authorization: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "QA sign-off",
    "description": "Verify all test cases pass on the release build",
    "assigned_user_slug": "USER_SLUG",
    "due_date": "2026-07-10"
  }'

To mark an approval task as complete:

curl -X PATCH "https://api.bitrise.io/release-management/v2/store-releases/v1/app-versions/APP_VERSION_ID/approvals/TASK_ID" \
  -H "Authorization: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "completed": true
  }'

Applying a preset to an app versionClick to copy link

If you have release presets configured, apply one when creating the app version to inherit its automation, approvals, and notification settings:

curl -X POST "https://api.bitrise.io/release-management/v2/store-releases/v1/app-versions" \
  -H "Authorization: YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "1.5.0",
    "app_id": "APP_ID",
    "presets_id": "PRESET_ID"
  }'

Deleting an app versionClick to copy link

Deletion is permanent

Deleting an app version removes it and all associated data. This cannot be undone.

curl -X DELETE "https://api.bitrise.io/release-management/v2/store-releases/v1/app-versions/APP_VERSION_ID" \
  -H "Authorization: YOUR_ACCESS_TOKEN"

A successful response returns 204 No Content with an empty body.