GoodOS API Reference
Base URL: https://base.goodos.app/api/v1
Download OpenAPI JSON · Download Postman Collection
GET /health
Scope: read:health
curl https://base.goodos.app/api/v1/health \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
GET /apps
Scope: read:apps
curl https://base.goodos.app/api/v1/apps \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
GET /storage/buckets
Scope: read:storage
curl https://base.goodos.app/api/v1/storage/buckets \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
GET /storage/files
Scope: read:storage
curl https://base.goodos.app/api/v1/storage/files \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
POST /functions/:slug
Scope: execute:functions
curl -X POST https://base.goodos.app/api/v1/functions/health-check \
-H "Content-Type: application/json" \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY" \
--data '{"source":"api-docs","message":"Testing function call"}'
GET /db/tables
Scope: read:db
curl https://base.goodos.app/api/v1/db/tables \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
GET /db/:tableSlug/rows
Scope: read:db
curl "https://base.goodos.app/api/v1/db/apps/rows?limit=10" \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
POST /db/:tableSlug/rows
Scope: write:db
curl -X POST https://base.goodos.app/api/v1/db/demo-items/rows \
-H "Content-Type: application/json" \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY" \
--data '{"title":"Created from API Docs","status":"active"}'
GET /storage/public/:bucketName/:objectKey
Public object route for Storage V2 buckets with public reads enabled.
curl https://base.goodos.app/storage/public/storage-v2-public/v2-public-health.txt
POST /functions/:slug — Edge Functions V2 runtime
Scope: execute:functions. Response includes output._runtime with version, deployment, timeout, memory, and sandbox metadata.
curl -X POST https://base.goodos.app/api/v1/functions/health-check \
-H "Content-Type: application/json" \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY" \
--data '{"source":"docs","message":"Edge Functions V2"}'
POST /realtime/events
Scope: publish:realtime
curl -X POST https://base.goodos.app/api/v1/realtime/events \
-H "Content-Type: application/json" \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY" \
--data '{"channel":"system","eventType":"demo.message","message":"Hello Realtime V2","payload":{"ok":true}}'
WS Realtime V2 WebSocket
Connect to wss://base.goodos.app/api/v1/realtime/ws?api_key=YOUR_KEY&channel=system.
GET /auth/session
Auth V2 session endpoint. Requires cookie or bearer token.
curl https://base.goodos.app/api/auth/session \
-H "Cookie: goodos_session=YOUR_SESSION"
POST /auth/mfa/setup
Start TOTP MFA setup for the current signed-in user.
GET /billing/plans
Public billing plan catalog.
curl https://base.goodos.app/api/v1/billing/plans
GET /usage — Usage V2 / Billing Meter
Scope: read:usage
curl https://base.goodos.app/api/v1/usage \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
GET /notifications — Notifications V2
Scope: read:notifications
curl https://base.goodos.app/api/v1/notifications \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
POST /notifications
Scope: write:notifications
curl -X POST https://base.goodos.app/api/v1/notifications \
-H "Content-Type: application/json" \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY" \
--data '{"title":"System notice","message":"Hello from Notifications V2"}'
ADMIN Background Jobs V2
Admin-only job scheduler and PM2 worker controls.
curl https://base.goodos.app/api/admin/jobs-page-data \
-H "Cookie: goodos_session=YOUR_SESSION"
Secrets V2 / Provider Credentials
Secrets V2 adds encrypted secret references, version history, provider credential mappings, safe rotation, and metadata-only admin visibility. Raw values are encrypted and are not returned through the console.
| Endpoint | Description |
|---|---|
GET /api/admin/secrets-v2-page-data | View secret vaults, secret metadata, provider credential mappings, and counts. |
POST /api/admin/secrets/create-safe | Create or rotate an encrypted secret reference. |
POST /api/admin/secrets/{key}/rotate-safe | Rotate an existing secret by key. |
POST /api/admin/secrets/{key}/resolve-test-safe | Confirm a secret can resolve without returning the raw value. |