REST API overview | FlightStack

REST API overview

FlightStack exposes a REST API for every feature in the dashboard, plus a SignalR streaming surface for live runs and agent updates. This page covers the cross-cutting concerns — base URL, authentication, headers, pagination, errors, real-time.

Base URL

https://api.flightstack.voostack.com

For self-hosted deployments, set this to your own domain. The CLI stores it in ~/.flightstack/config.json under apiUrl; see CLI configuration.

Authentication

The API supports two distinct token types:

Token	Header	Used by
User access	`Authorization: Bearer <token>`	The app, CLI, and any user-facing automation.
Agent token	`Agent-Token: <token>`	Build agents polling for jobs.

User tokens are issued by the GitHub OAuth flow at POST /authentication/github-login. Agent tokens are issued when a machine registers via POST /buildagent. See Authentication for the full flows.

Organization scoping

Most user-facing list endpoints respect an X-Organization-Id header. When present, the response is restricted to that organization’s resources. When absent, you get every resource you have permission to see, across all your orgs.

curl https://api.flightstack.voostack.com/repository \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Organization-Id: 7d2a8c84-..."

Pagination

Paginated endpoints accept skip and take query parameters:

GET /pipeline/runs?skip=0&take=20

Param	Default	Notes
`skip`	`0`	Number of records to skip.
`take`	`20`	Page size. Server max is usually 100.

Some endpoints accept additional filters (status=, branch=, search=) — see the per-resource pages.

Response envelope

Most responses return the resource directly:

{
  "id": "7d2a8c84-...",
  "name": "build-ios",
  "createdAt": "2026-06-14T12:00:00Z"
}

Errors use a standard problem-detail style with an HTTP status code:

{
  "statusCode": 404,
  "message": "Pipeline not found",
  "code": "PIPELINE_NOT_FOUND"
}

HTTP status codes

Status	Meaning
`200`	OK — payload returned.
`201`	Created — resource created, returned in body.
`204`	No Content — successful, no body (e.g. DELETE).
`400`	Bad Request — payload validation failed.
`401`	Unauthorized — missing or expired token.
`403`	Forbidden — token valid, action not permitted.
`404`	Not Found.
`409`	Conflict — e.g. trying to connect an already-connected repo.
`422`	Unprocessable — payload parsed but business-logic invalid.
`429`	Too Many Requests — see rate limiting below.
`5xx`	Server error. Retry with exponential backoff.

Rate limits

Default cloud rate limits:

300 requests / minute per authenticated user
3,000 requests / minute per agent (polling endpoints have separate, looser caps)
30 requests / minute for unauthenticated callers (login, OAuth, etc.)

Limits are advertised on every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 274
X-RateLimit-Reset: 1718373600

On a 429, back off until the X-RateLimit-Reset time.

Real-time (SignalR)

Live run output, agent heartbeats, and pipeline status updates stream over SignalR at:

{baseUrl}/hub/

The Dart client passes the user access token via accessTokenFactory. See Realtime (SignalR) for hub names, message shapes, and reconnect behavior.

Reference

Resource	Path prefix	Doc
Authentication	`/authentication`	Authentication
Agents	`/buildagent`	Agents
Repositories	`/repository`	Repositories
Pipelines & runs	`/pipeline`	Pipelines
Builds	`/build`	Builds
Organizations	`/organization`	Organizations
Code signing	`/codesigning`	Code signing
Secrets	`/secrets`	Secrets
Cloud runners	`/organizations/{orgId}/cloud-runners`	Cloud runners
Realtime	`/hub/*`	Realtime (SignalR)
Webhooks (inbound)	`/webhook/*`	Webhooks

SDKs

Language	Package
Dart, Flutter	`flightstack_core` — model + API client.
CLI	`flightstack` — the same authentication and resource calls, wrapped for the terminal.

Third-party SDKs are welcome. The API surface is stable enough to generate from the OpenAPI schema (available on request — hello@voostack.com).