Reference

API reference

Last updated 14 September 2026

Four endpoints: start a build, look at a build, list builds, cancel a build. Enough to drive MacBuildCloud from Jenkins, GitLab CI, a shell script or your own dashboard.

The base URL is https://macbuildcloud.com. Every response is JSON. Every request needs a token.

01Authentication

Create a token under Settings → API tokens. You see the value once; we only store a hash of it, so if you lose it you create a new one rather than recovering the old.

Send it as a bearer token:

curl https://macbuildcloud.com/api/v1/builds \
  -H "Authorization: Bearer mbc_your_token_here"

Tokens carry one of three scopes, and each endpoint states the scope it needs:

ScopeCan do
read Look at builds and list them
trigger Everything read can, plus start and cancel builds
admin Reserved for account-level endpoints we have not shipped yet

A token sees the repositories of your personal account plus any team where you hold the trigger role or higher. A request for a repository outside that set gets 404 not_found, not 403 — telling you a repository exists but is not yours would leak who else is a customer.

02Start a build

POST /api/v1/builds — needs trigger.

curl -X POST https://macbuildcloud.com/api/v1/builds \
  -H "Authorization: Bearer $MBC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repository": "acme/ios-app", "ref": "main"}'
FieldRequiredMeaning
repositoryyes owner/name, exactly as it appears on your Repositories page
refno Branch or tag. Defaults to that repository's default branch.
commitno A specific commit SHA to record against the run

On success you get 201 and the build object below.

03The build object

{
  "id": 4812,
  "repository": "acme/ios-app",
  "ref": "main",
  "commit": "2a6eedd1c0f3...",
  "state": "running",
  "trigger": "api",
  "queued_at": "2026-09-11T08:14:02+00:00",
  "started_at": "2026-09-11T08:14:19+00:00",
  "finished_at": null,
  "elapsed_seconds": 0,
  "billed_seconds": 0,
  "exit_code": null,
  "url": "https://macbuildcloud.com/builds/4812"
}

state moves through pending → running → one of finished, failed or cancelled. A finished build with exit_code 0 is a green build; any other value is your script's own exit code.

billed_seconds can be lower than elapsed_seconds: time we lost to our own infrastructure is not billed to you.

04Look at one build

GET /api/v1/builds/<id> — needs read. Returns the same object.

05List builds

GET /api/v1/builds — needs read. Newest first.

curl "https://macbuildcloud.com/api/v1/builds?repository=acme/ios-app&limit=5" \
  -H "Authorization: Bearer $MBC_TOKEN"

repository filters to one repository. limit defaults to 20 and caps at 100. The response is {"builds": [ ... ]}.

06Cancel a build

POST /api/v1/builds/<id>/cancel — needs trigger.

Cancelling is not instant: we stop the machine, which takes a few seconds, and you are billed for the time it actually ran. The response is the build object as it stands at that moment, so poll it if you need to know when it really stopped.

07Errors

StatuserrorWhat it means
400bad_request A field is missing or the build could not be queued. Read detail.
401unauthorised No token, a malformed header, or a token that has been revoked
402payment_required Your balance will not cover another build. Deliberately not 400 — nothing is wrong with your script, so do not go looking there.
403forbidden The token is valid but its scope is too low. The message names the scope you need.
404not_found No such build or repository that this token can see
429rate_limited Too many requests this minute. Wait the number of seconds in Retry-After, then carry on.

Every error body has an error code meant for your code, and a detail string meant for a human. Branch on error; show detail.

08Rate limits

Each token has its own allowance, counted in one-minute windows:

RequestsPer token, per minute
Reading — look at a build, list builds120
Writing — start a build, cancel a build20

Reads and writes are counted separately, so a dashboard that polls heavily never stops your pipeline from starting a build. Every response tells you where you stand:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 41

Go over and you get 429 with a Retry-After header in seconds. A request that was refused had no effect — a refused start does not queue a build, and a refused cancel does not cancel one — so it is safe to retry once the window resets.

There is also a coarse limit per IP address, well above anything a single pipeline does. It exists to absorb floods of requests with invalid tokens, and you should never meet it in normal use.

09A complete polling script

#!/bin/bash
set -euo pipefail

ID=$(curl -sS -X POST https://macbuildcloud.com/api/v1/builds \
  -H "Authorization: Bearer $MBC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repository":"acme/ios-app","ref":"main"}' \
  | python3 -c 'import json,sys; print(json.load(sys.stdin)["id"])')

echo "Build $ID queued"

while true; do
  sleep 15
  B=$(curl -sS "https://macbuildcloud.com/api/v1/builds/$ID" \
        -H "Authorization: Bearer $MBC_TOKEN")
  STATE=$(echo "$B" | python3 -c 'import json,sys; print(json.load(sys.stdin)["state"])')
  echo "  $STATE"
  case "$STATE" in
    pending|running) ;;
    finished) exit 0 ;;
    *) exit 1 ;;
  esac
done
Poll every 15 seconds or slower. Builds take minutes, not milliseconds, so a tighter loop tells you nothing a slower one would not.

10What is not here yet

No endpoint for downloading artifacts, reading logs, or managing repositories — those are dashboard-only for now. If one of them is what stands between you and automating this, say so; that is how we decide what to build next.

There is no API version other than v1, and we will not change what an existing field means. New fields may appear, so parse leniently.


Something here wrong or missing? Tell us — we read every message, and documentation fixes go out the same day.