API Reference

The orchestrator exposes REST endpoints for workspace management, billing, and admin operations.

Authentication

User endpoints require a session cookie from GitHub OAuth login. Admin endpoints require the ARC_ADMIN_TOKEN as a Bearer token.

Authorization: Bearer your-admin-token

Workspace

POST/api/workspace/start

Start the current user's workspace. Creates a Docker container if none exists.

POST/api/workspace/stop

Stop (hibernate) the current user's workspace.

POST/api/workspace/keepalive

Touch workspace activity timestamp. Called by the IDE every 30 seconds.

Billing

GET/api/billing

Get current user's billing info: tier, Stripe customer ID, next billing date.

POST/api/billing/portal

Generate a Stripe Customer Portal URL for managing subscription.

// Response
{ "url": "https://billing.stripe.com/..." }

Webhooks

POST/webhooks/github

GitHub webhook for push, PR, and issue events. Requires GITHUB_WEBHOOK_SECRET.

POST/webhooks/stripe

Stripe webhook for subscription and payment events. Requires STRIPE_WEBHOOK_SECRET.

Admin (requires admin token)

GET/api/admin/users

List all users with status, tier, and workspace info.

POST/api/admin/users/:username/start

Start a specific user's workspace.

POST/api/admin/users/:username/stop

Stop a specific user's workspace.

DELETE/api/admin/users/:username

Delete a user and their workspace.

GET/api/admin/billing

List all subscribers with tier and Stripe info.

GET/api/invites

List invite codes with usage stats.

POST/api/invites

Create a new invite code.

// Request
{ "max_uses": 10, "expires_days": 30 }

Internal (service-to-service)

GET/auth/verify

Traefik ForwardAuth endpoint. Returns 200 with user headers or 401.

GET/metrics

Prometheus metrics. Requires internal or admin token.

GET/health

Health check endpoint.