Developers

One API, described up front.

Everything the dashboard does, you can do over HTTPS. The API is described in OpenAPI 3.1, validated with zod on every request, and rendered as an interactive reference.

Open the API reference openapi.json

Authentication

Sessions, not API keys.

Sign in with Google, GitHub, or Microsoft. The browser gets an httpOnly session cookie; every API call carries it. Endpoints under /api/auth/* are the sign-in flow itself.

Auth endpoints

POST /api/auth/sign-in/social
GET /api/auth/get-session
POST /api/auth/sign-out

Admin operations (roles, bans) are exposed under /api/admin/* with the same session and an admin role check.

# Sign in in the browser first; the session cookie is httpOnly.
curl -s https://try.starlight.build/api/me \
  -H "cookie: $STARLIGHT_SESSION"

# Create a workspace that points at your Stargate
curl -s -X POST https://try.starlight.build/api/workspaces \
  -H "cookie: $STARLIGHT_SESSION" \
  -H "content-type: application/json" \
  -d '{"name":"Edge sites","target":"edge","stargateEndpoint":"stargate.example.net"}'

Resources

What the API covers.

Session
Who you are and what role you hold.
Workspaces
Create and manage workspaces; each maps to one Stargate endpoint.
Servers
Starlight servers in a workspace, with live status through Stargate.
Dashboards
Saved dashboard layouts per workspace.
Licenses
Your Starlight, Desktop, and Stargate licenses from the Mainsail portal.
Downloads
Software images and installers from the Mainsail portal.
Admin
List users, change roles, ban, and invite. Admin role required.
Portal
The proposed contract between this site and portal.mainsailindustries.com.

Errors

One error shape.

Every failure returns application/problem+json. Validation errors list the offending fields. Nothing else to parse.

{
  "type": "https://try.starlight.build/problems/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "errors": { "name": ["Too small: expected string to have >=2 characters"] }
}

401: No session. Sign in.
403: Signed in, but this needs another role.
404: Not yours, or not there. Same answer either way.
422: Request shape is wrong; see errors.

Stargate environments

Server status comes through the Stargate client. With no gateway configured, the API serves deterministic fixtures so you can build against the shapes before your gateway is up. Configure STARGATE_URL and STARGATE_TOKEN to go live.

Portal environments

Licenses and downloads are read from portal.mainsailindustries.com. The contract is recorded under the Portal tag as a proposal; without PORTAL_API_KEY the site returns fixtures and labels them as such.

Read the portal contract