Workspace Apps

What Workspace Apps are

Workspace Apps are live software you run on your workspace’s tenant runtime: a visitor-facing site, an optional API, and—on paid plans—a private Postgres-compatible database (PGlite) stored on your workspace volume.

Use them when you need more than a static publish link: form submissions that land in SQL, custom API handlers, or a Build project that should stay online after you close the editor.

Artifacts remain the right choice for simple marketing pages on every plan. Workspace Apps add database-backed apps and programmable APIs on Core plans and above.

Plans and where to start

• Starter workspaces can publish marketing pages with Artifacts on any plan; Workspace Apps and SQL require Core or Pro.
• Core and Pro include live app deploy, API routes, and the Database tab for private SQL on the workspace VM.
• Pro adds scheduled SQL backups and higher storage and query limits—check Usage in your workspace for current caps.

Two doors into the same app

Every live app can expose up to two public surfaces on your workspace origin. Most people only need the first.

• Visitor link — https://YOUR_WORKSPACE/apps/<slug>/ — opens in a browser like any normal website. No password or connection key for visitors.
• API — https://YOUR_WORKSPACE/api/apps/<slug>/… — for programmatic calls. By default this is private and requires a per-app connection key unless you set access to open (still rate-limited).
• Agents, workflows, and pulses inside Smart AI Team call your app internally—they never need the connection key.

Go live from the product

• Build — open a project under build/, then click Deploy live app. You get a success panel with Copy link, optional Copy key, and Open app.
• Workspace Apps — open Context → Capabilities → Workspace Apps (or /apps), name your app, and click Go live. The same success panel appears after the first deploy.
• Agents can also register apps through workspace tooling; humans usually prefer Build or Workspace Apps for the clearest share link.

Connection keys (outside integrations only)

When API access is private, Smart AI Team issues a per-app connection key (sat_app_…) once at deploy—or when you choose Create new key in Workspace Apps. Copy it immediately; the product shows the full secret only that one time unless you rotate.

Paste the key into external tools (Zapier, Make, custom scripts) as an API secret. Send it as header X-SAT-App-Key or as Authorization: Bearer.

Lost the key? Open Workspace Apps, find the app, and choose Create new key. The previous key stops working.

Do not confuse these with Workspace API keys (sat_wk_live_…), which authenticate the separate /api/ext/v1 REST and MCP surfaces documented under Workspace API and MCP.

curl -sS -H "X-SAT-App-Key: sat_app_YOUR_SECRET" \
  "https://YOUR_WORKSPACE/api/apps/YOUR_SLUG/health"

Open API versus private API

• Private (default) — only callers with a valid connection key can reach /api/apps/<slug>/…. Best for apps that store customer data or power internal automations.
• Open — anyone on the internet can call the API subject to rate limits. Use only when the endpoint is intentionally public (for example a read-only health check or anonymous lead capture you accept being scraped).
• Change access anytime from Workspace Apps under Share & access. Visitor links are unchanged either way.

Private database

The Database tab on Workspace Apps runs SQL against PGlite on your workspace VM—not a third-party hosted database. Tables you create stay inside your tenant boundary.

Write access is limited to workspace owners and admins; members can read depending on your rollout. Storage and queries per hour are metered against your plan.

Pro workspaces can take on-demand backups and restore from the same page.

Custom API handlers

Advanced teams add a handler module under workspace/apps/<slug>/handler.mjs to serve dynamic routes at /api/apps/<slug>/…. Build deploy can scaffold this when you ship from a build/ project.

Handlers run in an isolated worker on the tenant runtime with timeouts and resource limits. Keep secrets in workspace secret surfaces—not in published handler source.

Operational notes

• Redeploying from Build updates the live app in place; visitor URLs stay stable when the slug is unchanged.
• Rate limits apply to open APIs and SQL queries—watch Usage if integrations spike traffic.
• For static landing pages without SQL or custom APIs, Artifacts may be simpler and available on Starter.