API Reference

BuildMagic exposes a REST API for managing applications, triggering builds and integrating with your own tools. The dashboard uses this same API, so anything it can do is available to you.

Base URL

https://buildmagic.dev/api

Authentication

Every endpoint below requires authentication. Pass your session token as a bearer token:

Authorization: Bearer <your-session-token>

The browser session cookie is accepted as well, which is how the dashboard authenticates. Tokens come from signing in — through GitHub or GitLab OAuth, or with email and password at POST /api/auth/login.

Access is scoped to the teams you belong to. A request for a team, app or build you cannot reach returns 404 rather than 403, so an identifier cannot be confirmed by probing.

Teams

Applications

Application-scoped resources hang off /apps/{appId} directly — the app identifier is enough to locate the team.

Builds

Environment variables

Variables live in named groups that belong to one application. See Environment Variables.

Workflows

Code signing

Signing material belongs to the team. See Code Signing.

Integrations

Billing and usage

Triggering a build

curl -X POST \
  https://buildmagic.dev/api/apps/{appId}/builds \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'

branch defaults to the application's default branch. The response carries the new build's id, which you can poll at /builds/{buildId}.

Streaming build logs

Logs stream over a WebSocket. On connect you receive the history so far, then new lines as they are produced:

wss://buildmagic.dev/ws/builds/{buildId}/logs

Each message carries the step it belongs to, the text, a stream marker (stdout or stderr) and a sequence number. Sequence numbers restart per step, so treat the pair of step and sequence as the identity of a line when reconnecting.

Error responses

Errors return JSON with an error field:

{
  "error": "Description of what went wrong"
}