27 KiB

Raw Blame History

LetsBe Biz — API Reference

Version: 1.0 Date: February 26, 2026 Authors: Matt (Founder), Claude (Architecture) Status: Engineering Spec — Ready for Implementation Companion docs: Technical Architecture v1.2, Repo Analysis v1.0, Infrastructure Runbook v1.0

1. Purpose

This document is the complete API reference for the LetsBe Biz platform. It covers:

Hub API — The central platform's REST endpoints (admin, customer, tenant, webhooks)
Safety Wrapper API — The on-tenant endpoints for Hub ↔ VPS communication
Authentication flows — How each actor authenticates
Webhook specifications — Inbound and outbound webhook contracts

This reference is designed to serve as the implementation blueprint for Claude Code and Codex sessions.

2. API Overview

2.1 Base URLs

API	Base URL	Auth
Hub (admin)	`https://hub.letsbe.biz/api/v1/admin/`	Bearer {staffSessionToken}
Hub (customer)	`https://hub.letsbe.biz/api/v1/customer/`	Bearer {customerSessionToken}
Hub (tenant comms)	`https://hub.letsbe.biz/api/v1/tenant/`	Bearer {hubApiKey}
Hub (public)	`https://hub.letsbe.biz/api/v1/public/`	None or API key
Hub (webhooks)	`https://hub.letsbe.biz/api/v1/webhooks/`	Signature verification
Safety Wrapper (local)	`http://127.0.0.1:8100/`	Internal only
OpenClaw Gateway (local)	`http://127.0.0.1:18789/`	Token auth

2.2 Common Patterns

Response format: All Hub API responses follow this envelope:

{
  "success": true,
  "data": { ... },
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 142
  }
}

Error format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [
      { "field": "email", "message": "Must be a valid email address" }
    ]
  }
}

Pagination: Cursor-based where possible, offset-based for admin lists.

?page=1&pageSize=25 (offset)
?cursor=abc123&limit=25 (cursor)

Validation: Zod schemas on all endpoints. 400 returned with field-level errors.

Rate limiting: 60 requests/minute per authenticated session. 429 returned with Retry-After header.

3. Authentication

3.1 Staff Authentication (Admin Panel)

NextAuth.js with Credentials provider, JWT sessions.

Method	Path	Auth	Description
GET/POST	`/api/auth/[...nextauth]`	None	NextAuth handlers (login, logout, session)
POST	`/api/v1/setup`	None (one-time)	Initial owner account creation

Login flow:

1. POST /api/auth/callback/credentials
   Body: { email, password }

2. If 2FA enabled:
   Response: { requires2FA: true, pendingToken: "..." }

3. POST /api/v1/auth/2fa/verify
   Body: { token: pendingToken, code: "123456" }
   Response: Sets session cookie

4. Session token in cookie → used as Bearer token for API calls

2FA Management:

Method	Path	Auth	Description
GET	`/api/v1/auth/2fa/status`	Session	Check if 2FA is enabled
POST	`/api/v1/auth/2fa/setup`	Session	Generate TOTP secret + QR code
POST	`/api/v1/auth/2fa/verify`	Session/Pending	Verify TOTP code
POST	`/api/v1/auth/2fa/disable`	Session	Disable 2FA (requires current code)
GET	`/api/v1/auth/2fa/backup-codes`	Session	Get/regenerate backup codes

Staff Invitations:

Method	Path	Auth	Description
GET	`/api/v1/auth/invite/{token}`	None	Look up invitation details
POST	`/api/v1/auth/accept-invite`	None	Accept invitation, set password

3.2 Customer Authentication (Customer Portal)

Same NextAuth.js flow, separate user type. Customers log in via:

Email + password (created during Stripe checkout)
Future: SSO via Keycloak on their tenant VPS

3.3 Tenant Authentication (Safety Wrapper ↔ Hub)

Bearer token authentication using a Hub-generated API key.

Registration flow:

1. During provisioning, the Hub generates a registration token per order
2. Safety Wrapper boots, calls:
   POST /api/v1/tenant/register
   Body: { registrationToken: "..." }

3. Hub validates token, returns:
   { hubApiKey: "hk_abc123..." }

4. Safety Wrapper stores hubApiKey in encrypted secrets registry
5. All subsequent requests use:
   Authorization: Bearer hk_abc123...

3.4 Stripe Webhook Authentication

Stripe webhook signature verification using stripe.webhooks.constructEvent().

4. Hub Admin API (Staff)

4.1 Profile

Method	Path	Description
GET	`/api/v1/profile`	Get current staff profile
PATCH	`/api/v1/profile`	Update name, email
POST	`/api/v1/profile/photo`	Upload profile photo (multipart/form-data → S3/MinIO)
POST	`/api/v1/profile/password`	Change password (requires current password)

4.2 Customers

Method	Path	Description
GET	`/api/v1/admin/customers`	List customers. Query: `?page=1&pageSize=25&search=acme`
POST	`/api/v1/admin/customers`	Create customer (staff-initiated)
GET	`/api/v1/admin/customers/{id}`	Get customer detail with orders, subscription
PATCH	`/api/v1/admin/customers/{id}`	Update customer details

Customer object:

{
  "id": "cust_abc123",
  "email": "maria@acme.com",
  "name": "Maria Weber",
  "company": "Acme Marketing GmbH",
  "status": "ACTIVE",
  "subscription": {
    "plan": "PRO",
    "tier": "Build",
    "tokenLimit": 15000000,
    "tokensUsed": 8234000,
    "stripeCustomerId": "cus_xxx",
    "status": "ACTIVE"
  },
  "orders": [ ... ],
  "foundingMember": {
    "number": 42,
    "tokenMultiplier": 2,
    "expiresAt": "2027-03-15T00:00:00Z"
  },
  "createdAt": "2026-03-15T10:00:00Z"
}

4.3 Orders

Method	Path	Description
GET	`/api/v1/admin/orders`	List orders. Query: `?status=FULFILLED&tier=Build&search=acme`
POST	`/api/v1/admin/orders`	Create order (staff-initiated, MANUAL mode)
GET	`/api/v1/admin/orders/{id}`	Get order detail (full — server IP, tools, domain, status)
PATCH	`/api/v1/admin/orders/{id}`	Update order (credentials, server details)

Order lifecycle:

Method	Path	Description
POST	`/api/v1/admin/orders/{id}/provision`	Spawn Docker provisioner container
GET	`/api/v1/admin/orders/{id}/logs/stream`	SSE stream of provisioning logs
GET	`/api/v1/admin/orders/{id}/dns`	Get DNS verification status
POST	`/api/v1/admin/orders/{id}/dns/verify`	Trigger DNS A-record verification
POST	`/api/v1/admin/orders/{id}/dns/skip`	Manual DNS override
POST	`/api/v1/admin/orders/{id}/dns/create`	NEW: Auto-create DNS A records (Cloudflare/Entri)
GET	`/api/v1/admin/orders/{id}/automation`	Get automation mode (AUTO/MANUAL/PAUSED)
PATCH	`/api/v1/admin/orders/{id}/automation`	Change automation mode

Order object (key fields):

{
  "id": "ord_abc123",
  "userId": "cust_abc123",
  "status": "FULFILLED",
  "tier": "Build",
  "domain": "acme.letsbe.biz",
  "tools": ["nextcloud", "chatwoot", "ghost", "calcom", "odoo", "stalwart", "listmonk", "umami"],
  "serverIp": "88.99.xx.xx",
  "sshPort": 22022,
  "automationMode": "AUTO",
  "dashboardUrl": "https://acme.letsbe.biz",
  "portainerUrl": "https://portainer.acme.letsbe.biz",
  "createdAt": "2026-03-15T10:00:00Z",
  "fulfilledAt": "2026-03-15T12:34:56Z"
}

4.4 Container Management (via Portainer)

Method	Path	Description
GET	`/api/v1/admin/orders/{id}/containers`	List all containers on the tenant VPS
GET	`/api/v1/admin/orders/{id}/containers/stats`	All container stats (CPU, RAM)
GET	`/api/v1/admin/orders/{id}/containers/{cId}`	Container detail
POST	`/api/v1/admin/orders/{id}/containers/{cId}/start`	Start container
POST	`/api/v1/admin/orders/{id}/containers/{cId}/stop`	Stop container
POST	`/api/v1/admin/orders/{id}/containers/{cId}/restart`	Restart container
GET	`/api/v1/admin/orders/{id}/containers/{cId}/logs`	Container logs. Query: `?tail=100&since=1h`
GET	`/api/v1/admin/orders/{id}/containers/{cId}/stats`	Container resource stats
GET	`/api/v1/admin/orders/{id}/portainer`	Get Portainer credentials
POST	`/api/v1/admin/orders/{id}/portainer/init`	Initialize Portainer endpoint
POST	`/api/v1/admin/orders/{id}/test-ssh`	Test SSH connectivity

4.5 Servers

Method	Path	Description
GET	`/api/v1/admin/servers`	List active servers (from fulfilled orders)
GET	`/api/v1/admin/servers/{id}/health`	Server health (heartbeat status, Safety Wrapper version)
POST	`/api/v1/admin/servers/{id}/command`	Queue remote command for Safety Wrapper
POST	`/api/v1/admin/portainer/ping`	Test Portainer connectivity

4.6 Netcup Integration

Method	Path	Description
GET	`/api/v1/admin/netcup/auth`	Get Netcup OAuth2 connection status
POST	`/api/v1/admin/netcup/auth`	Initiate OAuth2 Device Flow
DELETE	`/api/v1/admin/netcup/auth`	Disconnect Netcup
GET	`/api/v1/admin/netcup/servers`	List Netcup servers
GET	`/api/v1/admin/netcup/servers/{id}`	Server detail (IP, status, plan)
PATCH	`/api/v1/admin/netcup/servers/{id}`	Power action (start/stop/restart), hostname, nickname
GET	`/api/v1/admin/netcup/servers/{id}/metrics`	CPU, disk, network metrics
GET	`/api/v1/admin/netcup/servers/{id}/snapshots`	List snapshots
POST	`/api/v1/admin/netcup/servers/{id}/snapshots`	Create snapshot
DELETE	`/api/v1/admin/netcup/servers/{id}/snapshots/{snapId}`	Delete snapshot
POST	`/api/v1/admin/netcup/servers/{id}/snapshots/{snapId}/revert`	Revert to snapshot

4.7 Staff Management

Method	Path	Description
GET	`/api/v1/admin/staff`	List staff members
POST	`/api/v1/admin/staff/invite`	Send staff invitation email
GET	`/api/v1/admin/staff/invitations`	List pending invitations
PATCH	`/api/v1/admin/staff/{id}`	Update staff role/status
DELETE	`/api/v1/admin/staff/{id}`	Deactivate staff member

Roles and permissions:

Role	Level	Key Permissions
OWNER	Full	All permissions, manage staff, delete account
ADMIN	High	Manage customers, orders, servers, billing
MANAGER	Medium	View/manage customers and orders, no billing
SUPPORT	Low	View customers, view orders, manage containers

4.8 Agent Management (NEW)

Method	Path	Description
GET	`/api/v1/admin/agents/templates`	List available agent role templates
POST	`/api/v1/admin/orders/{id}/agents`	Deploy new agent to tenant server
GET	`/api/v1/admin/orders/{id}/agents`	List agents on tenant server
PATCH	`/api/v1/admin/orders/{id}/agents/{agentId}`	Update agent config (SOUL.md, tools, autonomy)
DELETE	`/api/v1/admin/orders/{id}/agents/{agentId}`	Remove agent from tenant

AgentConfig object:

{
  "id": "agcfg_abc123",
  "orderId": "ord_abc123",
  "agentId": "it-admin",
  "name": "IT Admin",
  "role": "it-admin",
  "soulMd": "# IT Admin\n\n## Identity\n...",
  "toolsAllowed": ["shell", "docker", "file_read", "file_write", "env_read", "env_update"],
  "toolsDenied": [],
  "toolProfile": "coding",
  "autonomyLevel": 3,
  "externalCommsUnlocks": null,
  "isActive": true
}

4.9 Command Approval Queue (NEW)

Method	Path	Description
GET	`/api/v1/admin/approvals`	List all pending approvals across tenants
GET	`/api/v1/admin/approvals/{id}`	Approval detail with full command context
POST	`/api/v1/admin/approvals/{id}`	Approve or deny. Body: `{ "action": "approve" \| "deny", "reason": "..." }`

CommandApproval object:

{
  "id": "appr_abc123",
  "orderId": "ord_abc123",
  "agentId": "it-admin",
  "commandClass": "red",
  "toolName": "file_delete",
  "toolArgs": { "path": "/opt/letsbe/stacks/nextcloud/data/tmp/*", "recursive": true },
  "humanReadable": "IT Admin wants to delete /nextcloud/data/tmp/* (47 files, 2.3GB)",
  "status": "PENDING",
  "requestedAt": "2026-03-15T14:22:00Z",
  "expiresAt": "2026-03-16T14:22:00Z"
}

4.10 Billing & Token Metering (NEW)

Method	Path	Description
POST	`/api/v1/admin/billing/usage`	Ingest token usage report from Safety Wrapper
GET	`/api/v1/admin/billing/{customerId}`	Customer billing summary
GET	`/api/v1/admin/billing/{customerId}/history`	Historical usage data
POST	`/api/v1/admin/billing/overages`	Trigger overage billing via Stripe

TokenUsageBucket object (reported by Safety Wrapper):

{
  "agentId": "marketing",
  "model": "deepseek/deepseek-v3.2",
  "bucketHour": "2026-03-15T14:00:00Z",
  "tokensInput": 45000,
  "tokensOutput": 12000,
  "tokensCacheRead": 28000,
  "tokensCacheWrite": 0,
  "webSearchCount": 2,
  "webFetchCount": 1,
  "costCents": 3
}

4.11 Analytics

Method	Path	Description
GET	`/api/v1/admin/analytics/tokens`	Global token usage overview (all tenants)
GET	`/api/v1/admin/analytics/tokens/{orderId}`	Per-tenant token usage
GET	`/api/v1/admin/analytics/costs`	Cost breakdown by customer/model/agent
GET	`/api/v1/admin/stats`	Platform statistics (total customers, orders, revenue)
GET	`/api/v1/admin/analytics`	Dashboard analytics (growth, churn, usage trends)

4.12 Settings

Method	Path	Description
GET	`/api/v1/admin/settings`	Get all settings by category
PATCH	`/api/v1/admin/settings`	Update settings (bulk). Body: `{ "category.key": "value" }`
POST	`/api/v1/admin/settings/test-email`	Send test email
POST	`/api/v1/admin/settings/test-storage`	Test S3/MinIO connection

Settings categories: docker, dockerhub, gitea, hub, provisioning, netcup, email, notifications, storage (50+ settings total).

4.13 Enterprise Client Management

Method	Path	Description
GET	`/api/v1/admin/enterprise-clients`	List enterprise clients
POST	`/api/v1/admin/enterprise-clients`	Create enterprise client
GET	`/api/v1/admin/enterprise-clients/{id}`	Client detail with servers
PATCH	`/api/v1/admin/enterprise-clients/{id}`	Update client
DELETE	`/api/v1/admin/enterprise-clients/{id}`	Deactivate client
GET	`/api/v1/admin/enterprise-clients/{id}/servers`	List client's servers
POST	`/api/v1/admin/enterprise-clients/{id}/servers`	Add server to client
GET	`/api/v1/admin/enterprise-clients/{id}/servers/{sId}/stats`	Server stats
GET	`/api/v1/admin/enterprise-clients/{id}/servers/{sId}/events`	Container events
GET	`/api/v1/admin/enterprise-clients/{id}/error-rules`	Error detection rules
POST	`/api/v1/admin/enterprise-clients/{id}/error-rules`	Create error rule
PATCH	`/api/v1/admin/enterprise-clients/{id}/error-rules/{rId}`	Update error rule
DELETE	`/api/v1/admin/enterprise-clients/{id}/error-rules/{rId}`	Delete error rule
GET	`/api/v1/admin/enterprise-clients/{id}/errors`	Detected errors
POST	`/api/v1/admin/enterprise-clients/{id}/errors/{eId}/acknowledge`	Acknowledge error
GET	`/api/v1/admin/enterprise-clients/{id}/notifications`	Notification settings
PATCH	`/api/v1/admin/enterprise-clients/{id}/notifications`	Update notification settings
POST	`/api/v1/admin/enterprise-clients/{id}/security/verify`	Request security verification code
POST	`/api/v1/admin/enterprise-clients/{id}/security/confirm`	Confirm verification code

5. Hub Customer API (NEW)

Self-service portal for customers. All endpoints require customer session authentication.

Method	Path	Description
GET	`/api/v1/customer/dashboard`	Customer overview (server status, agent status, recent activity)
GET	`/api/v1/customer/agents`	List customer's agents with status
GET	`/api/v1/customer/agents/{id}`	Get agent detail (SOUL.md, tools, autonomy)
PATCH	`/api/v1/customer/agents/{id}`	Update agent config (personality, tools, autonomy level)
PATCH	`/api/v1/customer/agents/{id}/external-comms`	Update external comms gate per tool
GET	`/api/v1/customer/agents/{id}/activity`	Agent activity feed
GET	`/api/v1/customer/agents/{id}/conversations`	Conversation history
GET	`/api/v1/customer/usage`	Token usage summary (per agent, per model, daily/weekly/monthly)
GET	`/api/v1/customer/usage/breakdown`	Detailed usage breakdown for billing transparency
GET	`/api/v1/customer/approvals`	Pending command approval queue
POST	`/api/v1/customer/approvals/{id}`	Approve or deny a pending command
GET	`/api/v1/customer/tools`	List deployed tools with status
GET	`/api/v1/customer/billing`	Current billing period, usage, overages
GET	`/api/v1/customer/billing/history`	Billing history
GET	`/api/v1/customer/backups`	Backup status and history
PATCH	`/api/v1/customer/settings`	Update customer preferences (timezone, locale, notifications)

6. Hub Tenant Communication API (NEW)

Endpoints called by the Safety Wrapper on each tenant VPS. All require Bearer {hubApiKey} authentication.

Method	Path	Description
POST	`/api/v1/tenant/register`	Safety Wrapper registers post-deploy. Body: `{ registrationToken }`. Returns: `{ hubApiKey }`
POST	`/api/v1/tenant/heartbeat`	Status heartbeat. Sent every 5 minutes.
GET	`/api/v1/tenant/config`	Pull full config (agent configs, autonomy levels, model routing)
POST	`/api/v1/tenant/approval-request`	Push command approval request to Hub
GET	`/api/v1/tenant/approval-response/{id}`	Poll for approval/denial (or via webhook)
POST	`/api/v1/tenant/usage`	Report token usage buckets (hourly)
POST	`/api/v1/tenant/backup-status`	Report backup execution status

Heartbeat request body:

{
  "status": "healthy",
  "openclawVersion": "v2026.2.1",
  "safetyWrapperVersion": "v1.0.3",
  "configVersion": 7,
  "agents": {
    "dispatcher": { "status": "active", "lastActiveAt": "2026-03-15T14:20:00Z" },
    "it-admin": { "status": "active", "lastActiveAt": "2026-03-15T14:18:00Z" },
    "marketing": { "status": "idle", "lastActiveAt": "2026-03-14T09:00:00Z" },
    "secretary": { "status": "active", "lastActiveAt": "2026-03-15T14:22:00Z" },
    "sales": { "status": "idle", "lastActiveAt": "2026-03-13T16:00:00Z" }
  },
  "resources": {
    "cpuPercent": 23,
    "memoryUsedMb": 6144,
    "memoryTotalMb": 16384,
    "diskUsedGb": 45,
    "diskTotalGb": 320,
    "containersRunning": 18,
    "containersStopped": 2
  },
  "tokenUsage": {
    "periodStart": "2026-03-01T00:00:00Z",
    "tokensUsed": 8234000,
    "tokenAllotment": 15000000,
    "premiumTokensUsed": 125000,
    "premiumCostCents": 1250
  },
  "backupStatus": {
    "lastBackup": "2026-03-15T02:15:00Z",
    "status": "success",
    "sizeGb": 4.2
  }
}

Heartbeat response body:

{
  "configVersion": 8,
  "configChanged": true,
  "pendingCommands": [
    { "id": "cmd_123", "type": "RESTART_SERVICE", "payload": { "service": "ghost" } }
  ],
  "pendingApprovals": [
    { "id": "appr_456", "action": "approve" }
  ]
}

If configChanged: true, the Safety Wrapper follows up with GET /api/v1/tenant/config to pull the updated configuration.

7. Public API

Method	Path	Auth	Description
POST	`/api/v1/public/orders`	API key	Create order from external source (Stripe checkout redirect)
GET	`/api/v1/public/orders/{id}`	API key	Get order status (for progress page)
GET	`/api/v1/public/founding-members/count`	None	Get founding member spots remaining

8. Webhooks

8.1 Inbound Webhooks (Hub Receives)

Stripe Checkout:

Method	Path	Source	Description
POST	`/api/v1/webhooks/stripe`	Stripe	`checkout.session.completed` → Creates User + Subscription + Order

Stripe webhook payload handling:

Event: checkout.session.completed
→ Verify signature (stripe.webhooks.constructEvent)
→ Extract: customer email, plan, payment amount
→ Create User (status: ACTIVE)
→ Create Subscription (plan mapping: STARTER/PRO/ENTERPRISE)
→ Create Order (status: PAYMENT_CONFIRMED, mode: AUTO)
→ Automation worker picks up the order and begins provisioning

8.2 Outbound Webhooks (Hub Sends)

The Hub can push events to tenant VPS Safety Wrappers and to configured external endpoints.

To Safety Wrapper:

Event	Method	Path (on tenant)	Payload
Config updated	POST	`{safetyWrapperUrl}/webhooks/config-update`	`{ configVersion, changedFields }`
Approval response	POST	`{safetyWrapperUrl}/webhooks/approval-response`	`{ approvalId, action, respondedBy }`
Remote command	POST	`{safetyWrapperUrl}/webhooks/command`	`{ commandId, type, payload }`

Webhook security: All outbound webhooks include:

X-LetsBe-Signature: HMAC-SHA256 of the request body using the shared Hub API key
X-LetsBe-Timestamp: Unix timestamp (for replay protection)
X-LetsBe-Event: Event type string

8.3 Safety Wrapper Webhook Endpoints

Endpoints exposed by the Safety Wrapper for Hub communication:

Method	Path	Description
POST	`/webhooks/config-update`	Hub notifies of config changes
POST	`/webhooks/approval-response`	Hub delivers approval/denial for gated commands
POST	`/webhooks/command`	Hub pushes remote commands
POST	`/webhooks/diun`	Diun container update notifications
GET	`/health`	Health check (returns Safety Wrapper + OpenClaw status)

9. Cron Endpoints (Hub Internal)

Method	Path	Description	Schedule
POST	`/api/v1/cron/stats-collection`	Collect stats from all tenant Portainer instances	Every 15 min
POST	`/api/v1/cron/stats-cleanup`	Delete stats older than 90 days	Daily at 03:00
POST	`/api/v1/cron/billing-cycle`	Process monthly billing cycles	Daily at 00:00
POST	`/api/v1/cron/pool-alerts`	Check token pools and send usage alerts	Every hour
POST	`/api/v1/cron/approval-expiry`	Expire pending approvals older than 24h	Every hour

10. Data Models (Prisma)

10.1 Existing Models

Model	Table	Primary Key	Key Relations
User	users	id (UUID)	→ Subscription, Order[], FoundingMember?
Staff	staff	id (UUID)	—
StaffInvitation	staff_invitations	id (UUID)	—
Subscription	subscriptions	id (UUID)	→ User
Order	orders	id (UUID)	→ User, DnsVerification?, ProvisioningJob[], ServerConnection?
DnsVerification	dns_verifications	id (UUID)	→ Order, DnsRecord[]
DnsRecord	dns_records	id (UUID)	→ DnsVerification
ProvisioningJob	provisioning_jobs	id (UUID)	→ Order, JobLog[]
JobLog	job_logs	id (UUID)	→ ProvisioningJob
ProvisioningLog	provisioning_logs	id (UUID)	→ Order
TokenUsage (legacy)	token_usage	id (UUID)	→ User
RunnerToken	runner_tokens	id (UUID)	—
ServerConnection	server_connections	id (UUID)	→ Order
RemoteCommand	remote_commands	id (UUID)	→ ServerConnection
SystemSetting	system_settings	id (UUID)	—

10.2 New Models (v1.2 Architecture)

Model	Table	Primary Key	Key Relations
TokenUsageBucket	token_usage_buckets	id (UUID)	→ User, Order
BillingPeriod	billing_periods	id (UUID)	→ User, Subscription
FoundingMember	founding_members	id (UUID)	→ User
AgentConfig	agent_configs	id (UUID)	→ Order
CommandApproval	command_approvals	id (UUID)	→ Order

10.3 Enterprise/Monitoring Models

Model	Table	Primary Key	Key Relations
EnterpriseClient	enterprise_clients	id (UUID)	→ EnterpriseServer[]
EnterpriseServer	enterprise_servers	id (UUID)	→ EnterpriseClient
ServerStatsSnapshot	server_stats_snapshots	id (UUID)	→ EnterpriseServer, EnterpriseClient
ErrorDetectionRule	error_detection_rules	id (UUID)	→ EnterpriseClient
DetectedError	detected_errors	id (UUID)	→ EnterpriseServer, ErrorDetectionRule
SecurityVerificationCode	security_verification_codes	id (UUID)	→ EnterpriseClient
LogScanPosition	log_scan_positions	id (UUID)	—
ContainerStateSnapshot	container_state_snapshots	id (UUID)	—
ContainerEvent	container_events	id (UUID)	—
NotificationSetting	notification_settings	id (UUID)	→ EnterpriseClient
NotificationCooldown	notification_cooldowns	id (UUID)	—
Pending2FASession	pending_2fa_sessions	id (UUID)	—

11. Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request body failed Zod validation
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Authenticated but insufficient permissions
`NOT_FOUND`	404	Resource does not exist
`CONFLICT`	409	Duplicate resource (e.g., duplicate email)
`RATE_LIMITED`	429	Too many requests. Check `Retry-After` header
`PROVISIONING_FAILED`	500	Server provisioning pipeline failed
`PORTAINER_UNAVAILABLE`	502	Cannot reach tenant Portainer instance
`NETCUP_ERROR`	502	Netcup API returned an error
`STRIPE_ERROR`	502	Stripe API returned an error
`TENANT_OFFLINE`	503	Tenant VPS Safety Wrapper is not responding
`INTERNAL_ERROR`	500	Unhandled server error

12. Implementation Priority

Phase	Endpoints	Effort
Phase 1: Core	Auth, Customers, Orders, Provisioning, DNS, Containers, Settings	Existing (retool)
Phase 2: Tenant Comms	/tenant/register, /heartbeat, /config, /usage, /approval-request	3 weeks
Phase 3: Customer Portal	/customer/* endpoints	3 weeks
Phase 4: Agent Management	/admin/agents/, /customer/agents/	2 weeks
Phase 5: Billing	/admin/billing/*, cron jobs, Stripe integration	3 weeks
Phase 6: Analytics	/admin/analytics/*, customer usage dashboards	2 weeks

13. Changelog

Version	Date	Changes
1.0	2026-02-26	Initial API reference. 80+ existing endpoints documented. New endpoint groups: Tenant Communication (7), Customer Portal (16), Agent Management (5), Billing (4), Approvals (3), Analytics (3). Authentication flows. Webhook specs. Data models. Error codes. Implementation priorities.

27 KiB Raw Blame History