Build API

Build endpoints require the builds scope. Your machine or CI system runs Metro and produces the bundle. The API only stores that bundle and registers a hosted build result. It never starts a build or dispatches a GitHub workflow.

#Reserve upload slots

POST https://contrast.dev/api/v1/builds

{
  "owner": "acme",
  "repo": "mobile",
  "branch": "main",
  "platform": "ios",
  "commitSha": "0123456789abcdef0123456789abcdef01234567",
  "contentHash": "<sha256 of the uncompressed bundle>",
  "bundleSizeBytes": 182430,
  "bundleContentType": "application/javascript",
  "bundleOrigin": "http://localhost:8081",
  "entry": "index",
  "isTransformed": true,
  "deviceSpec": { "width": 393, "height": 852 },
  "files": []
}

The linked repository must belong to the authenticated account. The response contains a short-lived reservation token, presigned PUT slots for the bundle and declared files, and the stable hosted build url.

PUT the exact declared bytes to each returned putUrl, using its returned contentType header.

#Finalize and register

Call the same endpoint after every upload completes:

{
  "operation": "finalize",
  "token": "<reservation token>"
}

The response returns 201 with the ready build row, its stable url, and its bundle previewUrl. The finalizing credential must resolve to the same account that reserved the upload. Repeating a build upload for the same repository, branch, platform, and commit updates the same build identity.

#Read the latest branch build

GET /api/v1/builds?owner=acme&repo=mobile&branch=main&platform=ios

platform is ios or android and defaults to ios. The response includes the build status fields, its stable hosted build url, and previewUrl after the replay bundle is ready.

#Read by build ID

GET https://contrast.dev/api/v1/builds/{id} returns the same shape for one build row. Both read forms return 404 not_found when the repository is not linked to the authenticated account.