← Developer Docs

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.

EndpointDescription
GET /api/admin/secrets-v2-page-dataView secret vaults, secret metadata, provider credential mappings, and counts.
POST /api/admin/secrets/create-safeCreate or rotate an encrypted secret reference.
POST /api/admin/secrets/{key}/rotate-safeRotate an existing secret by key.
POST /api/admin/secrets/{key}/resolve-test-safeConfirm a secret can resolve without returning the raw value.