API Introduction
Base URLs, authentication, error format, and route groups for the Control Plane REST API.
The Control Plane exposes a REST API for programmatic access to accounts, workspaces, and all customer pillars.
Base URLs
| Environment | URL |
|---|---|
| Production | https://platform.groundfloor.cloud |
| Development | https://dev-platform.groundfloor.cloud |
| Local | http://localhost:8088 |
Route groups
| Prefix | Audience | Description |
|---|---|---|
/v1/* | Customer | Account- and workspace-scoped endpoints (documented here) |
/v1/public/* | Unauthenticated | Bootstrap, routing, TLS, branding (rate-limited) |
/v1/admin/* | Groundfloor staff | Operator-only — not part of the public docs |
Authentication
All customer endpoints require a Bearer JWT from IdPlane (auth.groundfloor.cloud):
curl -H "Authorization: Bearer $TOKEN" \
"$CP_URL/v1/workspaces"The JWT sub claim maps to a Portal user. SpiceDB checks permissions per request. See Authentication and Developers for tokens and gf.
Error format
{
"detail": "Human-readable message",
"code": "machine_readable_code"
}| Status | Meaning |
|---|---|
| 401 | Missing or expired JWT |
| 403 | SpiceDB denied the action |
| 404 | Resource not found or no read permission |
| 422 | Validation error |
Workspace-scoped endpoints
Most pillar APIs are scoped under a workspace:
/v1/workspaces/{workspace_id}/apps/…
/v1/workspaces/{workspace_id}/coderunners/…
/v1/workspaces/{workspace_id}/secrets/…
/v1/workspaces/{workspace_id}/flags/…
/v1/workspaces/{workspace_id}/managed-databases/…Documentation index
| Guide | Topics |
|---|---|
| Authentication | JWT, permissions, public routes |
| Accounts | List, create, audit, quota |
| Workspaces | CRUD, export |
| Environments | Env CRUD and promote entry points |
| Memberships | Platform roles on account/workspace |
| Apps | Shell / standalone apps, releases, promote |
| Coderunners | Upload, deploy, run, git-source, promote |
| Feature flags | Typed flags + promote |
| LLM Gateway | Models, usage, virtual key |
| Data Vault | Collections, query, DDL |
| Files | Presigned upload/download |
| Secrets | List, reveal, upsert, delete |
| Managed databases | Provision, backup, restore |
| Audit | Activity log query + export |
| Process log | Runtime log tail |
| Quotas | Account tier and ceilings |
| Workspace auth | App end-user IdP, roles, SSO |
OpenAPI
FastAPI serves an OpenAPI spec at /openapi.json. Interactive auto-docs may be added later; these pages are the curated public reference.