Build with GoodOS.
Use the GoodOS Public API, JavaScript SDK, TypeScript definitions, OpenAPI spec, and Postman collection to connect GoodFleet, GoodQR, GoodAds, GoodBoost, GoodTrust, and future apps to the same enterprise backend.
API Key Auth
Use X-GoodOS-API-Key or Authorization: Bearer. Keys are scoped by permissions and app restrictions.
Scoped Access
Supported scopes include read:health, read:apps, read:storage, and execute:functions.
Project Ready
GoodOS is organized by organization, project, and environment for enterprise-style backend isolation.
Install the SDK
<script src="https://base.goodos.app/sdk/goodos.js"></script>
JavaScript Example
const goodos = GoodOS.createClient({
apiKey: "gak_your_key_here"
});
const health = await goodos.health();
const apps = await goodos.apps();
const result = await goodos.callFunction("health-check", {
source: "developer-docs",
message: "Hello from GoodOS"
});
Node / Bundler Example
const { createClient } = require("./goodos.js");
const goodos = createClient({
apiKey: process.env.GOODOS_API_KEY
});
const response = await goodos.apps();
console.log(response);
Public API Endpoints
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/health | read:health | Check public API health and key context. |
| GET | /api/v1/apps | read:apps | List apps allowed by the API key. |
| GET | /api/v1/storage/buckets | read:storage | List storage buckets. |
| GET | /api/v1/storage/files | read:storage | List storage files. |
| GET/POST | /api/v1/functions/:slug | execute:functions | Call active HTTP Edge Functions. |
Background Jobs V2
Background Jobs V2 adds job definitions, interval schedules, job run logs, worker locks, PM2 worker heartbeats, and controlled queue processing.
| Admin Route | Purpose |
|---|---|
GET /api/admin/jobs-page-data | View jobs, schedules, runs, worker locks, heartbeats, and queue items. |
POST /api/admin/jobs/run-due-safe | Manually run jobs that are currently due. |
POST /api/admin/jobs/:id/run-safe | Manually run one job. |
pm2 status goodapp-worker
npm run jobs:run-once -- job_email_queue_process
Notifications V2
Notifications V2 adds notification templates, in-app message center, email queue, notification preferences, alert rules, and alert events.
| Route | Scope | Purpose |
|---|---|---|
GET /api/v1/notifications | read:notifications | List notifications and message center records. |
POST /api/v1/notifications | write:notifications | Create an in-app or queued email notification. |
await goodos.notifications();
await goodos.createNotification({
title: "System notice",
message: "Hello from Notifications V2"
});
Usage V2 / Billing Meter
Usage V2 adds billing plans, customer/subscription records, usage event logging, meter events, API key usage logs, daily rollups, and quota counters.
| Route | Scope | Purpose |
|---|---|---|
GET /api/v1/billing/plans | Public | List billing plans. |
GET /api/v1/usage | read:usage | Read current usage and quota state. |
const plans = await goodos.billingPlans();
const usage = await goodos.usage();
Auth V2
Auth V2 adds session metadata, role and permission tables, MFA/TOTP setup, password reset tokens, refresh-token foundation, and auth audit events.
| Route | Purpose |
|---|---|
GET /api/auth/session | Return current user, session, roles, and MFA status. |
GET /api/auth/roles | Return role matrix and current user roles. |
POST /api/auth/mfa/setup | Create pending TOTP factor and QR code. |
POST /api/auth/mfa/verify | Verify TOTP code and activate MFA. |
POST /api/auth/password-reset/request | Create reset token for active account. |
POST /api/auth/password-reset/complete | Use token to set a new password. |
const session = await goodos.authSession();
const setup = await goodos.setupMfa();
await goodos.verifyMfa(setup.data.factorId, "123456");
Realtime V2
Realtime V2 adds WebSocket channels, SSE subscriptions, REST publishing, message logs, connection records, and presence tracking.
| Route | Scope | Purpose |
|---|---|---|
GET /api/v1/realtime/channels | read:realtime | List realtime channels. |
GET /api/v1/realtime/events | read:realtime | List realtime messages. |
POST /api/v1/realtime/events | publish:realtime | Publish a message. |
GET /api/v1/realtime/stream | subscribe:realtime | Subscribe over SSE. |
wss://base.goodos.app/api/v1/realtime/ws | subscribe:realtime | Subscribe over WebSocket. |
await goodos.publishRealtimeEvent("system", {
eventType: "demo.message",
message: "Hello Realtime V2",
payload: { ok: true }
});
const ws = goodos.connectRealtimeWebSocket("system", {
apiKey: "YOUR_KEY"
});
Edge Functions V2
Edge Functions V2 adds versioning, deployment records, runtime limits, secret references, and structured execution metadata. Public calls still use /api/v1/functions/:slug with the execute:functions scope.
const result = await goodos.callFunctionV2("health-check", {
source: "sdk",
message: "Testing Edge Functions V2"
});
console.log(result.data.output._runtime);
Storage V2 / CDN
Storage V2 adds provider metadata, local/S3-compatible planning fields, object keys, checksums, version records, public object URLs, and CDN URL mapping.
| Route | Scope | Purpose |
|---|---|---|
GET /api/v1/storage/buckets | read:storage | List buckets with provider/CDN metadata. |
GET /api/v1/storage/files | read:storage | List files with object keys, checksums, and public/CDN URLs. |
GET /storage/public/:bucketName/:objectKey | Public bucket only | Serve a public object through the GoodOS storage gateway. |
const buckets = await goodos.storageBuckets();
const files = await goodos.storageFiles();
const url = goodos.storagePublicUrl("storage-v2-public", "v2-public-health.txt");
Generated Database API
GoodOS can publish selected Postgres tables as scoped REST endpoints. Use read:db for reads and write:db for write-enabled tables.
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /api/v1/db/tables | read:db | List published tables. |
| GET | /api/v1/db/:tableSlug/rows | read:db | List rows from a published table. |
| GET | /api/v1/db/:tableSlug/rows/:id | read:db | Read one published row. |
| POST | /api/v1/db/:tableSlug/rows | write:db | Create a row in a write-enabled table. |
| PATCH | /api/v1/db/:tableSlug/rows/:id | write:db | Update a row in a write-enabled table. |
| DELETE | /api/v1/db/:tableSlug/rows/:id | write:db | Delete or soft-delete a write-enabled row. |
const tables = await goodos.dbTables();
const rows = await goodos.dbRows("apps", { limit: 10 });
const created = await goodos.createDbRow("demo-items", {
title: "Created from SDK",
status: "active"
});
cURL Example
curl https://base.goodos.app/api/v1/health \
-H "X-GoodOS-API-Key: $GOODOS_API_KEY"
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. |