GoodOS Developer Center
Goodbase Public API
Production Ready

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/healthread:healthCheck public API health and key context.
GET/api/v1/appsread:appsList apps allowed by the API key.
GET/api/v1/storage/bucketsread:storageList storage buckets.
GET/api/v1/storage/filesread:storageList storage files.
GET/POST/api/v1/functions/:slugexecute:functionsCall active HTTP Edge Functions.
Keep raw API keys private. Use separate keys for development, staging, production, and each app when possible.

Background Jobs V2

Background Jobs V2 adds job definitions, interval schedules, job run logs, worker locks, PM2 worker heartbeats, and controlled queue processing.

Admin RoutePurpose
GET /api/admin/jobs-page-dataView jobs, schedules, runs, worker locks, heartbeats, and queue items.
POST /api/admin/jobs/run-due-safeManually run jobs that are currently due.
POST /api/admin/jobs/:id/run-safeManually 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.

RouteScopePurpose
GET /api/v1/notificationsread:notificationsList notifications and message center records.
POST /api/v1/notificationswrite:notificationsCreate 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.

RouteScopePurpose
GET /api/v1/billing/plansPublicList billing plans.
GET /api/v1/usageread:usageRead 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.

RoutePurpose
GET /api/auth/sessionReturn current user, session, roles, and MFA status.
GET /api/auth/rolesReturn role matrix and current user roles.
POST /api/auth/mfa/setupCreate pending TOTP factor and QR code.
POST /api/auth/mfa/verifyVerify TOTP code and activate MFA.
POST /api/auth/password-reset/requestCreate reset token for active account.
POST /api/auth/password-reset/completeUse 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.

RouteScopePurpose
GET /api/v1/realtime/channelsread:realtimeList realtime channels.
GET /api/v1/realtime/eventsread:realtimeList realtime messages.
POST /api/v1/realtime/eventspublish:realtimePublish a message.
GET /api/v1/realtime/streamsubscribe:realtimeSubscribe over SSE.
wss://base.goodos.app/api/v1/realtime/wssubscribe:realtimeSubscribe 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/bucketsread:storageList buckets with provider/CDN metadata.
GET /api/v1/storage/filesread:storageList files with object keys, checksums, and public/CDN URLs.
GET /storage/public/:bucketName/:objectKeyPublic bucket onlyServe 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/tablesread:dbList published tables.
GET/api/v1/db/:tableSlug/rowsread:dbList rows from a published table.
GET/api/v1/db/:tableSlug/rows/:idread:dbRead one published row.
POST/api/v1/db/:tableSlug/rowswrite:dbCreate a row in a write-enabled table.
PATCH/api/v1/db/:tableSlug/rows/:idwrite:dbUpdate a row in a write-enabled table.
DELETE/api/v1/db/:tableSlug/rows/:idwrite:dbDelete 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.

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.