Builds API

Codemagic REST API Builds API

API for starting and managing app builds

APIs for managing builds are currently available for developers to preview. During the preview period, the API may change without advance notice.

Note: Using REST API will not fetch information about workflows when configuring with codemagic.yaml. It is because only workflows from the Workflow Editor are defaulted as no accessible data is present from codemagic.yaml until a repository is cloned, which means that there is no way to retrieve workflow IDs from codemagic.yaml before triggering a build.

Start a new build

POST /builds

Note: The workflow and branch information is passed with the curl request when starting builds from an API request. Any configuration related to triggers or branches in Flutter workflow editor or codemagic.yaml is ignored.

Parameters

NameTypeDescription
appIdstringRequired. The application identifier.
workflowIdstringRequired. The workflow identifier as specified in YAML file.
branchstringOptional. The branch name. Either branch or tag is required.
tagstringOptional. The tag name. Either branch or tag is required.
environmentobjectOptional. Specify environment variables, variable groups, and software versions to override or define in workflow settings.
labelslistOptional. Specify labels to be included for the build in addition to existing labels.

Example

  curl -H "Content-Type: application/json" \
       -H "x-auth-token: <API Token>" \
       --data '{
         "appId": "<app_id>",
         "workflowId": "<workflow_id>",
         "branch": "<git_branch_name>"
       }' \
       https://api.codemagic.io/builds

Pass custom build parameters

{
  "appId": "5c9c064185dd2310123b8e96",
  "workflowId": "release",
  "branch": "master",
  "labels": ["foo", "bar"],
  "environment": {
    "variables": {
      "ENVIRONMENT_VARIABLE_1": "...",
      "ENVIRONMENT_VARIABLE_2": "..."
    },
    "groups": [
      "variable_group_1",
      "variable_group_2"
    ],
    "softwareVersions": {
      "xcode": "11.4.1",
      "flutter": "v1.12.13+hotfix.9"
    }
  },
  "instanceType": "mac_mini_m1"
}

Response

  {
    "buildId":"5fabc6414c483700143f4f92"
  }

Get a list of builds

GET /builds

Returns information about builds from the Codemagic build history. Filters are applicable.

Parameters

NameTypeDescription
appIdstringOptional. The application identifier.
workflowIdstringOptional. The workflow identifier as specified in YAML file.
branchstringOptional. The branch name.
tagstringOptional. The tag name.

Example

  curl -H "Content-Type: application/json" \
       -H "x-auth-token: <API Token>" \
       --request GET "https://api.codemagic.io/builds?appId=<app_id>&workflowId=<workflow_id>&branch=<branch_name>&tag=<tag_name>"

Response

{
  "applications": [
    {
      "_id": "5d85eaa0e941e00019e81bc2",
      "appName": "counter_flutter",
      ...
    }
  ],
  "builds": [
    {
      "_id": "5ec8eea2261f342603f4d0bc",
      "appId": "5d85eaa0e941e00019e81bc2",
      "workflowId": "5d85f242e941e00019e81bd2",
      "branch": "develop",
      "tag": null,
      "status": "finished",
      "startedAt": "2020-09-08T07:18:02.203+0000",
      "finishedAt": "2020-09-08T07:20:13.040+0000",
      "artefacts": [
        {
          "md5": "81298e2f39a0e2d401b583f4f32d88d1",
          "name": "app-debug.apk",
          "packageName": "io.codemagic.counter-flutter",
          "size": 59325441,
          "type": "apk",
          "url": "https://api.codemagic.io/artifacts/2667d83f-a05b-44a5-8839-51fd4b05e7ce/d44b59f6-ebe9-4ca5-80ee-86ce372790ee/app-debug.apk",
          "versionName": "1.0.2"
        },
        {
          "md5": "d34bf9732ef125bd761d76b2cf3017bc",
          "name": "Runner.app",
          "size": 96849493,
          "type": "app",
          "url": "https://api.codemagic.io/artifacts/5020d900-14c2-4e96-9c95-93869e1e2d2f/0ec3367c-704e-4d36-895b-6b3944e43113/Runner.app"
        }
      ],
      ...
    },
    ...
  ]
}

Get build status

GET /builds/:id

Returns the build information of an already running build on Codemagic. Status will be one of:

building, canceled, finishing, finished, failed, fetching, preparing, publishing, queued, skipped, testing, timeout, warning

Example

  curl -H "Content-Type: application/json" \
       -H "x-auth-token: <API Token>" \
       --request GET https://api.codemagic.io/builds/<build_id>

Response

{
  "application": {
    "_id": "5d85eaa0e941e00019e81bc2",
    "appName": "counter_flutter"
  },
  "build": {
    "_id": "5ec8eea2261f342603f4d0bc",
    "startedAt": "2020-05-23T09:36:39.028+0000",
    "status": "building",
    "workflowId": "5d85f242e941e00019e81bd2"
  }
}

Cancel build

POST /builds/:id/cancel

Example

  curl -H "Content-Type: application/json" \
       -H "x-auth-token: <API Token>" \
       --request POST https://api.codemagic.io/builds/<build_id>/cancel

The request will return 208 Already Reported if the build has already finished.

Note: If you have multiple similar workflows for the same project, you can configure your workflows dynamically using API calls, read more about it here.