API Reference

The SkyState REST API provides programmatic access to all platform features: reading and writing remote configuration, managing projects, controlling billing, and administering account settings.

---

Base URL

All API endpoints are served under the /api prefix:

https://app.skystate.io/api

When running locally with Docker, the Nginx proxy exposes the API at:

http://localhost:8080/api

The API server itself listens on port 5148 and can be reached directly during local development.

---

Content Type

All request and response bodies use JSON. Include the Content-Type: application/json header on any request that sends a body.

---

Endpoint Groups

The API is organized into several route groups:

Group	Path prefix	Auth required	Description
Health	/ and /health	No	Liveness and readiness probes
Auth	/auth/...	No	GitHub OAuth flow
Public Config	/public/...	No	Anonymous config reads (SDK-facing)
Dev Config	/dev/...	DevKey	SDK writes to development environment
Admin	/admin/...	Bearer JWT	Account, project, config, and billing management
Webhooks	/webhooks/...	Stripe signature	Stripe event receiver

---

Authentication Methods

SkyState supports three authentication methods. See Authentication for details.

Method	Header format	Used for
GitHub OAuth JWT	Authorization: Bearer <token>	Dashboard and CLI (admin endpoints)
Dev API Key	Authorization: DevKey <key>	SDK writes to development environment
Test mode	X-Test-GitHub-Id: <github_id>	Integration testing only (non-production)

---

Response Format

Successful responses return the resource directly as a JSON object or array. There is no outer envelope wrapper.

{
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-app",
  "slug": "my-app",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Error responses use a consistent { error, message } shape. See Errors for details.

---

Sections

• Authentication — how to authenticate and obtain tokens
• Accounts — account profile and slug management
• Projects — project CRUD operations
• Config — versioned remote configuration
• Dev API Keys — project-scoped development keys
• Billing — subscription management and invoices
• Rate Limiting — monthly quotas and response headers
• Errors — error response format and common codes