#Cloud API Reference

Most endpoints live under /api/cloud-saas; Cloud App exposure endpoints live under /api/cloud/exposures. All require Bearer token authentication.

#Templates

#List templates

Returns approved templates (official + community), sorted by category and score.

Response:

[
  {
    "slug": "web-app",
    "name": "Web Application",
    "description": "A full-stack web app...",
    "category": "web",
    "tags": ["react", "node"],
    "content": {},
    "author": { "username": "..." },
    "rating": 4.5,
    "deployCount": 123,
    "createdAt": "2025-01-01T00:00:00.000Z"
  }
]

#Get template

Returns a single approved template with full content. Supports space-rendered i18n descriptions.

#Get template env refs

Returns the template's declared environment variables, form fields, and auto-detected env references.

Response:

{
  "template": "web-app",
  "requiredEnvVars": ["OPENAI_API_KEY"],
  "fields": [{ "key": "domain", "label": "Domain", "type": "text" }],
  "autoDetectedEnvVars": ["DATABASE_URL"]
}

#My templates

List or get templates authored by the current user, including pending/rejected ones. Same response shape as public templates.

#Create template

Content is validated against the template policy allowlist. Templates are submitted for review as pending.

#Update template

Same fields as create, all optional. Only allowed for the author when the template is draft or rejected.

#Submit for review

Re-submits a draft or rejected template for review. No body required.

#Delete template

Deletes own template at any review status.

#Deployments

#List deployments

Returns the newest visible deployment per namespace. Uses a per-namespace deduplication strategy.

#Get deployment costs

Returns aggregate cost snapshots for all visible SaaS deployments.

#Create deployment

Creates a new deployment with billing. Validates the template, locks the namespace, and checks wallet balance (returns 402 if insufficient). The deployment is queued asynchronously.

This endpoint is for fresh instances only. The namespace must not have been used by the same user on the same cluster, even if the previous deployment has already been destroyed. To continue a stateful template instance, use the deployment id with POST /api/cloud-saas/deployments/:id/redeploy, resume, or restore.

#Get deployment

Returns full deployment detail including current status, blocking info, and cost summary.

#Get deployment costs

Returns cost summary for a specific deployment.

#Cancel deployment

Cancels an active deploy or destroy task. Does not wait for namespace operation locks.

#Delete deployment

Queues a Pulumi destroy for the current deployment entry. Interrupts active operations.

#Redeploy

Re-enqueues the same namespace with a new deployment history entry. Does not debit wallet. This is the stateful template path: it can reuse the namespace, Pulumi stack, PVC-backed runtime state, and Shadow provision state for the existing deployment instance.

#Deployment logs

GET /logs returns an SSE event stream (text/event-stream) with real-time events: log, status, error, close. Terminates when deployment reaches terminal status.

GET /logs/history returns a plain JSON array of log entries.

#Pod info

GET /pods lists K8s pods in the deployment namespace. GET /pod-logs streams live K8s pod logs via SSE.

#Orphan management

/claim adopts a Shadow-Cloud-managed namespace with no DB row. /cleanup force-deletes an orphan namespace (admin only).

#Cloud App Exposure

These endpoints publish runtime services from a Cloud deployment under stable Shadow-managed App hosts and keep the Space App installation, release metadata, and backup set in sync.

#Environment Variables

#Deployment-scoped env vars

Values are encrypted at rest. GET returns masked values ('****'). GET by key returns decrypted value for editing.

#Global env vars

#Global env var groups

#Provider Profiles & Catalogs

#List provider catalogs

Returns model providers discovered from installed Cloud plugins. Each entry includes plugin ID, provider details, and required secret fields.

#List provider profiles

Returns the current user's encrypted provider profiles. Values are masked.

#Upsert provider profile

Validates model list in config and applies SSRF guard on any base URL.

#Test provider profile

Tests encrypted credentials against the provider API with 8s timeout and SSRF protection.

#Refresh models

Fetches model list from the provider's native API and persists into the profile config.

#Delete provider profile

Deletes the profile and all associated encrypted values.

#Wallet

#Get balance

Returns the current user's Shrimp Coin balance.

Response:

{
  "balance": 5000,
  "currency": "shrimp_coin"
}

#Transaction history

Returns paginated wallet transaction history.

#Activity Log

Returns the user's cloud activity log (paginated), including deployment creation, pause, resume, backup, restore, and deletion events.

#Schema & Validation

GET /schema returns the primary CloudConfig JSON Schema for frontend validation and editor autocomplete.

POST /validate accepts a raw JSON config snapshot and returns a validation summary with errors.

#Client Methods

// Templates
const templates = await client.listCloudTemplates({ q: 'web' })
const template = await client.getCloudTemplate('web-app')
const envRefs = await client.getCloudTemplateEnvRefs('web-app')

// Deployments
const deployments = await client.listCloudDeployments()
const deployment = await client.createCloudDeployment({
  namespace: 'my-app',
  name: 'My App',
  templateSlug: 'web-app',
  resourceTier: 'standard',
  configSnapshot: {},
})
await client.redeployCloudDeployment(deployment.id, { mode: 'template' })
await client.cancelCloudDeployment(deployment.id)

// Deployment lifecycle
await client.pauseCloudDeployment('dep-id', { agentId: 'agent-name' })
await client.resumeCloudDeployment('dep-id')

// Backups
const { backups } = await client.listCloudDeploymentBackups('dep-id')
const { backup } = await client.createCloudDeploymentBackup('dep-id', { driver: 'volumeSnapshot' })
await client.restoreCloudDeploymentBackup('dep-id', { backupId: 'backup-id' })

// Manifest & template sync
const manifest = await client.getCloudDeploymentManifest('dep-id')
await client.syncCloudDeploymentTemplate('dep-id', { name: 'My Fork' })

// Cloud App exposure and backups
await client.reconcileCloudRuntimeExposures({
  deploymentId: 'dep-id',
  agentId: 'agent-name',
  exposures: [{ id: 'desk', port: 4216, kind: 'space_app', appKey: 'demo-desk' }],
})
await client.publishCloudApp({ appKey: 'demo-desk', deploymentId: 'dep-id', port: 4216 })
await client.getCloudAppStatus('demo-desk', { deploymentId: 'dep-id' })
await client.backupCloudApp('demo-desk', { deploymentId: 'dep-id' })
await client.unpublishCloudApp('demo-desk', { deploymentId: 'dep-id', uninstall: true })

// Provider profiles
const catalogs = await client.listCloudProviderCatalogs()
const profiles = await client.listCloudProviderProfiles()
await client.upsertCloudProviderProfile({ providerId: 'openai', name: 'My Key', config: {} })
await client.testCloudProviderProfile('profile-id')
await client.deleteCloudProviderProfile('profile-id')

// Wallet
const wallet = await client.getWallet()
const transactions = await client.getWalletTransactions()

# Templates
result = client.list_cloud_templates(q="web")
template = client.get_cloud_template("web-app")
env_refs = client.get_cloud_template_env_refs("web-app")

# Deployments
result = client.list_cloud_deployments()
deployment = client.create_cloud_deployment(
    namespace="my-app",
    name="My App",
    template_slug="web-app",
    resource_tier="standard",
    config_snapshot={},
)
client.redeploy_cloud_deployment(deployment["id"], mode="template")
client.cancel_cloud_deployment(deployment["id"])

# Deployment lifecycle
client.pause_cloud_deployment("dep-id", agent_id="agent-name")
client.resume_cloud_deployment("dep-id")

# Backups
result = client.list_cloud_deployment_backups("dep-id")
result = client.create_cloud_deployment_backup("dep-id", driver="volumeSnapshot")
client.restore_cloud_deployment_backup("dep-id", backup_id="backup-id")

# Manifest & template sync
manifest = client.get_cloud_deployment_manifest("dep-id")
client.sync_cloud_deployment_template("dep-id", name="My Fork")

# Cloud App exposure and backups
client.reconcile_cloud_runtime_exposures(
    deployment_id="dep-id",
    agent_id="agent-name",
    exposures=[{"id": "desk", "port": 4216, "kind": "space_app", "appKey": "demo-desk"}],
)
client.publish_cloud_app(app_key="demo-desk", deployment_id="dep-id", port=4216)
client.get_cloud_app_status("demo-desk", deployment_id="dep-id")
client.backup_cloud_app("demo-desk", deployment_id="dep-id")
client.unpublish_cloud_app("demo-desk", deployment_id="dep-id", uninstall=True)

# Provider profiles
catalogs = client.list_cloud_provider_catalogs()
profiles = client.list_cloud_provider_profiles()
client.upsert_cloud_provider_profile(provider_id="openai", name="My Key", config={})
client.test_cloud_provider_profile("profile-id")
client.delete_cloud_provider_profile("profile-id")

# Wallet
wallet = client.get_wallet()
result = client.get_wallet_transactions()

#Next Steps

• Cloud SaaS Runtime for pause/resume/backup/restore operations.
• Cloud CLI for the standalone deployment CLI.
• Templates for the template catalog and authoring guide.
• Plugins for the plugin ecosystem.
• SDKs for all SDK client methods.