Build Agents API | FlightStack

Build Agents API

The build-agent surface has two audiences:

• User-facing (Bearer auth): list, register, update, delete agents from a dashboard or CLI.
• Agent-facing (Agent-Token header): polling for jobs, sending heartbeats, posting build status, uploading artifacts and logs.

All endpoints under /buildagent.

User-facing endpoints

Method	Path	Purpose
GET	/buildagent	List agents. Respects X-Organization-Id.
POST	/buildagent	Register a new agent. Returns { agentId, token, ... }.
GET	/buildagent/{id}	Get agent details.
PUT	/buildagent/{id}	Update agent (name, organization, public flag).
DELETE	/buildagent/{id}	Delete / unregister an agent.
GET	/buildagent/scripts	List install scripts available for each platform.
POST	/buildagent/{id}/commands	Queue a command for an agent (admin only — pause, resume, …).
GET	/buildagent/{id}/commands	List queued commands for an agent.

Register

curl -X POST https://api.flightstack.voostack.com/buildagent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "macbook-pro",
    "platform": "macOS",
    "organizationId": null,
    "canBuildIOS": true,
    "canBuildAndroid": true,
    "canBuildWeb": true,
    "operatingSystemVersion": "14.5",
    "xcodeVersion": "16.0",
    "flutterVersion": "3.27.0",
    "dartVersion": "3.5.0"
  }'

Response:

{
  "agentId": "a1b2c3d4-...",
  "token": "eyJhbG…",
  "organizationName": null
}

Persist the token — it’s used for every agent-side call below.

Agent-side endpoints

These are called by the build-agent binary itself. Authentication is Agent-Token: <token>.

Method	Path	Purpose
GET	/buildagent/{id}/poll	Long-poll for the next build job. Returns null if idle.
POST	/buildagent/{id}/heartbeat	Send a heartbeat. Response signals pause/throttle.
POST	/buildagent/{id}/jobs/{jobId}/status	Update build status (running, succeeded, failed).
POST	/buildagent/{id}/jobs/{jobId}/logs	Stream a chunk of build log entries.
POST	/buildagent/{id}/jobs/{jobId}/artifacts	Upload an artifact (multipart, small files).
POST	/buildagent/{id}/jobs/{jobId}/artifacts/upload-url	Get a signed URL for a large artifact.
POST	/buildagent/{id}/jobs/{jobId}/artifacts/confirm	Confirm a large artifact uploaded via signed URL.
GET	/buildagent/{id}/jobs/{jobId}/credentials	Fetch signing credentials for the current job.
POST	/buildagent/{id}/cancel-builds	Cancel listed jobs (used during graceful shutdown).
GET	/buildagent/{id}/deployments/poll	Poll for the next deployment task.
GET	/buildagent/{id}/deployments/{deploymentId}	Get deployment details (credentials, artifact URLs).
POST	/buildagent/{id}/deployments/{deploymentId}/status	Update deployment status.
GET	/buildagent/{id}/commands/poll	Poll for pending commands (pause, resume, …).
POST	/buildagent/{id}/commands/{commandId}/status	Update command status / result.
POST	/buildagent/{id}/logs/stream	Stream agent console logs.
POST	/buildagent/{id}/screenstack/upload	Upload ScreenStack screenshot (multipart).
POST	/buildagent/{id}/screenstack/upload-by-target	Upload ScreenStack screenshot keyed by canvas/view target.

Polling for a job

curl https://api.flightstack.voostack.com/buildagent/$AGENT_ID/poll \
  -H "Agent-Token: $AGENT_TOKEN"

Returns either null (nothing pending) or a BuildJob payload. The agent runs the job and posts back through the /jobs/{jobId}/... endpoints above.

Heartbeat

curl -X POST https://api.flightstack.voostack.com/buildagent/$AGENT_ID/heartbeat \
  -H "Agent-Token: $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queueDepth": 0, "cpuLoad": 0.42}'

Response includes canAcceptJobs (and an optional constraintReason if the server has paused the agent). The agent should stop polling for jobs when canAcceptJobs is false.

Artifact upload (large files)

For artifacts over a few MB, request a signed URL and upload directly to object storage:

1. POST /buildagent/{id}/jobs/{jobId}/artifacts/upload-url → { uploadUrl, objectKey }
2. PUT $uploadUrl with the file bytes.
3. POST /buildagent/{id}/jobs/{jobId}/artifacts/confirm with { objectKey, sizeBytes, sha256 }.

Live status

Per-agent and per-job state is broadcast on the SignalR hub — see Realtime.

See also

• CLI: agent commands — registration, install, upgrade, doctor
• Self-hosting — running agents against a self-hosted control plane