API reference
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:
| Scope | Can 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"}'
| Field | Required | Meaning |
|---|---|---|
| repository | yes | owner/name, exactly as it appears on your Repositories page |
| ref | no | Branch or tag. Defaults to that repository's default branch. |
| commit | no | 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
| Status | error | What it means |
|---|---|---|
| 400 | bad_request | A field is missing or the build could not be queued. Read detail. |
| 401 | unauthorised | No token, a malformed header, or a token that has been revoked |
| 402 | payment_required | Your balance will not cover another build. Deliberately not 400 — nothing is wrong with your script, so do not go looking there. |
| 403 | forbidden | The token is valid but its scope is too low. The message names the scope you need. |
| 404 | not_found | No such build or repository that this token can see |
| 429 | rate_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:
| Requests | Per token, per minute |
|---|---|
| Reading — look at a build, list builds | 120 |
| Writing — start a build, cancel a build | 20 |
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
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.