---
title: "Start a new build"
method: POST
path: "/api/v3/apps/{app_id}/builds"
tags: ["Builds"]
---

# Start a new build

`POST /api/v3/apps/{app_id}/builds`

## Request

- Base URL: `https://codemagic.io`
- URL: `https://codemagic.io/api/v3/apps/{app_id}/builds`
- Auth: API key in header `x-auth-token`
- TypeScript: <https://skmtc.dev/codemagic/apis/codemagic-api/docs/api/v3/apps/:app_id/builds/post.ts> (a function with typed inputs; its response is checked against the schema)

Queue a new build for the application.

The 202 response means the build request was **accepted**, not that a build has started.
For this reason `GET /builds/{build_id}` can respond 404 for a short while after this endpoint
has returned the build id.

`workflow_id` names the workflow to build. A 24-character hexadecimal id selects a workflow
defined in the Workflow Editor; any other value is the id of a workflow in the repository's
`codemagic.yaml`, as in `workflows.<workflow_id>`.

Exactly one of `branch` or `tag` is required - it is what the build is started from. Giving
neither, or both, responds 400.

## Path parameters

- `app_id` string, required

## Request body

- StartBuildSchema
  - `workflow_id` string, required: The workflow to build. A 24-character hexadecimal id selects a Workflow Editor workflow, any other value the id of a workflow in the repository's `codemagic.yaml`.
  - `branch` string, nullable: The branch to build. Exactly one of `branch` or `tag` is required.
  - `tag` string, nullable: The tag to build. Exactly one of `branch` or `tag` is required.
  - `ssh_access_enabled` boolean: Enable remote access to the build machine. Rejected when the team disallows it.
  - `labels` string[], nullable: Labels to tag the build with.
  - `instance_type` 'mac_mini_m2' | 'mac_mini_m4' | 'mac_studio_m4_max' | 'linux_x2' | 'linux_x4' | 'windows_x2': The build machine a build runs on, overriding the instance type the workflow declares.
  - `inputs` object, nullable: Values for the workflow's inputs, keyed by input name.
  - `environment` EnvironmentSchema
    - `variables` object, nullable: Environment variables for the build, keyed by variable name.
    - `groups` string[], nullable: Variable groups to make available to the build.
    - `software_versions` object, nullable: Software versions to install for the build, keyed by software.
  - `priority` integer: Build priority. The team's builds with a higher priority start first.

## Response `202`

Request accepted, processing continues off-line

- StartedBuildSchemaNoPagination
  - `data` StartedBuildSchema, required
    - `id` string, required

## Other responses

- `400`: The request could not be validated
- `401`: Authentication is missing or invalid
- `402`: The team has no subscription permitting builds and no free build time left
- `403`: The caller lacks the required permission
- `404`: The requested resource does not exist
- `429`: The rate limit has been exceeded

---

[API](https://skmtc.dev/codemagic/apis/codemagic-api.md) - [All operations](https://skmtc.dev/codemagic/apis/codemagic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/codemagic/apis/codemagic-api/revisions/be09630f65e2?raw)