Deploy API Reference

Creates a new user account with email and password. If an invitation token is provided, the user is automatically added to the inviting tenant. A personal tenant is always created for the new user. Returns access and refresh tokens plus the user profile and tenant memberships.

{"email":"user@example.com","password":"secureP@ss1","displayName":"Jane Doe","invitationToken":"(optional)"}

{"accessToken":"eyJ...","refreshToken":"eyJ...",
 "user":{"id":"...","email":"user@example.com","displayName":"Jane Doe","emailVerified":false,"isActive":true,"authMethods":[{"provider":"password"}],"createdAt":"...","updatedAt":"..."},
 "memberships":[{"tenantId":"...","tenantName":"Jane's Team","tenantSlug":"janes-team","role":"owner","isRoot":false}]}

Authenticates a user with email and password. Returns JWT access and refresh tokens. Account is locked for 15 minutes after 5 consecutive failed attempts.

{"email":"user@example.com","password":"secureP@ss1"}

{"accessToken":"eyJ...","refreshToken":"eyJ...","user":{...},"memberships":[...]}

Exchanges a valid refresh token for a new access/refresh token pair. The old refresh token is revoked (rotation). Use this when the access token expires.

{"refreshToken":"eyJ..."}

{"accessToken":"eyJ...","refreshToken":"eyJ...","user":{...},"memberships":[...]}

Confirms the user's email address using a token sent via email. The token is single-use and expires after 24 hours.

{"token":"verification-token-from-email"}

{"message":"Email verified successfully"}

Sends a new verification email to the specified address. Rate-limited to one request per 60 seconds per email. Returns a success message regardless of whether the email exists (prevents enumeration).

{"email":"user@example.com"}

{"message":"If the email exists, a verification link has been sent"}

Sends a password reset email to the specified address. Returns a success message regardless of whether the email exists (prevents enumeration). Only works for accounts with password authentication enabled.

{"email":"user@example.com"}

{"message":"If the email exists, a password reset link has been sent"}

Resets the user's password using a token from the reset email. All existing refresh tokens are revoked (logs out all sessions). The token is single-use.

{"token":"reset-token-from-email","newPassword":"newSecureP@ss1"}

{"message":"Password reset successfully"}

Redirects the user to Google's OAuth consent screen. After authorization, Google redirects back to the callback URL. Only available when Google OAuth is configured.

Handles the OAuth callback from Google. Links the Google account to an existing user (matched by email) or creates a new account. Redirects to the frontend with tokens in the URL fragment: <code>/auth/callback#access_token=...&amp;refresh_token=...</code>

Returns the authenticated user's profile and all tenant memberships. Use this to hydrate the session after login or page refresh.

{"user":{"id":"...","email":"...","displayName":"...","emailVerified":true,"isActive":true,"authMethods":[...],"createdAt":"...","updatedAt":"...","lastLoginAt":"..."},"memberships":[{"tenantId":"...","tenantName":"...","tenantSlug":"...","role":"owner","isRoot":false}]}

Revokes the current access token. If a refresh token is provided in the body, it is also revoked.

{"refreshToken":"eyJ... (optional)"}

{"message":"Logged out successfully"}

Changes the authenticated user's password. If the user already has a password, the current password must be provided. For Google-only accounts adding a password for the first time, the current password field can be omitted.

{"currentPassword":"oldP@ss (required if password exists)","newPassword":"newSecureP@ss1"}

{"message":"Password changed successfully"}

Accepts a pending invitation to join a tenant. The invitation token comes from the invitation email. The user is added to the tenant with the role specified in the invitation. Returns updated memberships.

{"token":"invitation-token-from-email"}

{"message":"Invitation accepted","memberships":[{"tenantId":"...","tenantName":"...","tenantSlug":"...","role":"user","isRoot":false}]}

Returns all members of the current tenant with their roles and join dates. Any member of the tenant can call this endpoint.

{"members":[{"userId":"...","email":"user@example.com","displayName":"Jane Doe","role":"owner","joinedAt":"2025-01-15T..."}]}

Sends an invitation email to join the tenant. If the email belongs to an existing user, they receive a join link. If not, they receive a signup-and-join link. Invitations expire after 7 days. Only owners can invite admins; admins can only invite users. Subject to the plan's user limit.

{"email":"newuser@example.com","role":"user"}

{"message":"Invitation sent"}

Removes a member from the tenant. You cannot remove the owner or yourself. Admins can only remove regular users (not other admins).

{"message":"Member removed"}

Changes a member's role to admin or user. Only the tenant owner can change roles. To transfer ownership, use the dedicated transfer endpoint instead.

{"role":"admin"}

{"message":"Role updated"}

Transfers ownership of the tenant to another member. The current owner is demoted to admin. The target user must already be a member of the tenant. This action cannot be undone by the previous owner.

{"message":"Ownership transferred"}

Returns all messages for the authenticated user, sorted by creation date (newest first). Messages include system notifications like invitation alerts.

{"messages":[{"id":"...","userId":"...","type":"invitation","title":"...","body":"...","isRead":false,"createdAt":"..."}]}

Returns the number of unread messages for the authenticated user. Use this for notification badges.

{"count":3}

Marks a specific message as read. Only the message owner can mark it as read.

{"message":"Marked as read"}

Returns all subscription plans visible to the current user, along with the tenant's current plan, billing status, credits, and subscription interval. Requires the <code>X-Tenant-ID</code> header to determine the tenant's current state.

{"plans":[{"id":"...","name":"Pro","description":"...","monthlyPriceCents":2900,"annualDiscountPct":20,"usageCreditsPerMonth":1000,"creditResetPolicy":"reset","bonusCredits":0,"userLimit":10,"entitlements":{...}}],
 "currentPlanId":"...","billingWaived":false,"tenantSubscriptionCredits":500,"tenantPurchasedCredits":0,
 "billingStatus":"active","billingInterval":"year","currentPeriodEnd":"2026-01-15T...","canceledAt":null}

Returns all active credit bundles available for purchase, sorted by sort order.

{"bundles":[{"id":"...","name":"500 Credits","credits":500,"priceCents":4900,"isActive":true,"sortOrder":1}]}

Creates a Stripe Checkout session for a plan subscription or credit bundle purchase. For free plans or billing-waived tenants, the plan is assigned immediately without Stripe. Specify either <code>planId</code> or <code>bundleId</code>, not both.

{"planId":"ObjectID (or bundleId)","billingInterval":"year"}

{"checkoutUrl":"https://checkout.stripe.com/..."}

Creates a Stripe Billing Portal session URL where the customer can manage payment methods, view invoices, and update billing details. The tenant must have an existing Stripe customer ID.

{"portalUrl":"https://billing.stripe.com/..."}

Returns paginated billing transactions for the current tenant, sorted by date (newest first).

{"transactions":[{"id":"...","tenantId":"...","description":"Pro Plan (Annual)","type":"subscription","amountCents":29900,"currency":"usd","invoiceNumber":"INV-0001","createdAt":"..."}],
 "total":15,"page":1,"perPage":20}

Returns the full transaction record and tenant name for rendering an invoice view.

{"transaction":{...},"tenant":{"name":"Acme Corp"}}

Generates and returns a PDF invoice for the specified transaction. The response Content-Type is <code>application/pdf</code>.

Cancels the tenant's current subscription at the end of the billing period. The tenant retains access until the period ends. Returns the period end date.

{"message":"Subscription will cancel at end of billing period","currentPeriodEnd":"2026-02-15T..."}

Returns the Stripe publishable key for initializing Stripe.js on the frontend. Returns an empty string if Stripe is not configured.

{"publishableKey":"pk_live_..."}

Returns the current version and copyright information.

{"version":"1.00","copyright":"..."}

Returns high-level system metrics including total user count, tenant count, and overall health status with any active issues.

{"users":142,"tenants":38,"health":{"healthy":true,"issues":[]}}

Returns paginated system audit logs with optional filtering by severity, user, or text search. Logs record authentication events, configuration changes, billing actions, and other system activity.

{"logs":[{"id":"...","severity":"high","message":"Webhook created: Test → https://...","userId":"...","createdAt":"..."}],"total":256}

Returns all known server nodes and their current status. In a multi-machine deployment, each machine registers as a separate node.

{"nodes":[{"id":"...","hostname":"d892610f630968","region":"iad","lastSeen":"...","isHealthy":true}]}

Returns time-series performance metrics (CPU, memory, request rate, latency) for a specific node or aggregated across all nodes.

{"metrics":[{"timestamp":"...","cpu":23.5,"memoryMB":128,"requestsPerMin":45,"avgLatencyMs":12}],"from":"...","to":"..."}

Returns the latest health snapshot for each active node. Use this for real-time monitoring dashboards.

{"metrics":[{"nodeId":"...","cpu":15.2,"memoryMB":96,"requestsPerMin":30,"avgLatencyMs":8}]}

Checks the connectivity and status of all external integrations: MongoDB, Stripe, Resend (email), and Google OAuth. Returns the check status and last 24h call count for each.

{"integrations":[{"name":"mongodb","status":"healthy","lastCheck":"...","calls24h":1520},{"name":"stripe","status":"healthy",...},{"name":"resend","status":"not_configured",...}]}

Returns all configuration variables as a map keyed by variable name. Includes system variables (read-only name/type) and user-created variables.

{"configs":{"app.name":{"name":"app.name","type":"string","value":"Deploy","description":"Application name","isSystem":true,"options":""},...}}

Creates a new user-defined configuration variable. Variable names must be unique. Types: <code>string</code>, <code>numeric</code>, <code>enum</code> (pipe-separated options), <code>template</code> (supports placeholders).

{"name":"feature.max_uploads","description":"Maximum uploads per user","type":"numeric","value":"100","options":""}

{"name":"feature.max_uploads","type":"numeric","value":"100","description":"Maximum uploads per user","isSystem":false,"options":""}

Returns a single configuration variable by name.

{"name":"app.name","type":"string","value":"Deploy","description":"Application name","isSystem":true,"options":""}

Updates the value (and optionally description/options) of a configuration variable. System variables only allow value changes. Enum variables validate against the options list.

{"value":"200","description":"Updated description (optional)"}

{"name":"feature.max_uploads","type":"numeric","value":"200",...}

Deletes a user-created configuration variable. System variables cannot be deleted.

{"message":"Config variable deleted"}

Returns all tenants with member counts and billing information. Includes the plan name, billing waived status, and credit balances.

{"tenants":[{"id":"...","name":"Acme Corp","slug":"acme-corp","isRoot":false,"isActive":true,"memberCount":5,"planName":"Pro","billingWaived":false,"subscriptionCredits":1000,"purchasedCredits":200,"createdAt":"..."}]}

Returns full tenant details including all members with roles and join dates.

{"tenant":{"id":"...","name":"Acme Corp","slug":"acme-corp","isRoot":false,"isActive":true,"planId":"...","billingWaived":false,"subscriptionCredits":1000,"purchasedCredits":200,"stripeCustomerId":"cus_...","billingStatus":"active","billingInterval":"year","currentPeriodEnd":"...","createdAt":"...","updatedAt":"..."},
 "members":[{"userId":"...","email":"jane@acme.com","displayName":"Jane Doe","role":"owner","joinedAt":"..."}]}

Updates tenant properties. All fields are optional — only provided fields are changed. Can modify name, billing waived status, and credit balances.

{"name":"New Name (optional)","billingWaived":true,"subscriptionCredits":5000,"purchasedCredits":100}

{"message":"Tenant updated"}

Sets a tenant's active status. Deactivated tenants cannot access the application. The root tenant cannot be deactivated.

{"isActive":false}

{"message":"Tenant deactivated"}

Directly assigns a plan to a tenant (bypasses Stripe). Can also toggle billing waived status. Send an empty <code>planId</code> or omit it to remove the plan.

{"planId":"ObjectID (optional)","billingWaived":true}

{"status":"updated"}

Cancels a tenant's Stripe subscription. Set <code>immediate</code> to true to cancel now; otherwise cancels at the end of the billing period.

{"immediate":false}

{"message":"Subscription canceled"}

Manually updates subscription metadata such as the current period end date. Use this for correcting billing records.

{"currentPeriodEnd":"2026-03-15T00:00:00Z"}

{"message":"Subscription updated"}

Returns all users with summary information including tenant count and last login time.

{"users":[{"id":"...","email":"jane@example.com","displayName":"Jane Doe","emailVerified":true,"isActive":true,"tenantCount":2,"createdAt":"...","lastLoginAt":"..."}]}

Returns full user profile including authentication methods and all tenant memberships with billing details for each tenant.

{"user":{"id":"...","email":"jane@example.com","displayName":"Jane Doe","emailVerified":true,"isActive":true,"authMethods":[{"provider":"password"},{"provider":"google"}],"createdAt":"...","lastLoginAt":"..."},
 "memberships":[{"tenantId":"...","tenantName":"Acme Corp","tenantSlug":"acme-corp","isRoot":false,"role":"owner","joinedAt":"...","planId":"...","planName":"Pro","billingWaived":false,"subscriptionCredits":1000,"purchasedCredits":200}]}

Updates a user's email or display name. Both fields are optional — only provided fields are changed.

{"email":"new@example.com","displayName":"New Name"}

{"message":"User updated"}

Sets a user's active status. Deactivated users cannot log in. Active sessions are not immediately terminated but will fail on the next API call.

{"isActive":false}

{"message":"User deactivated"}

Changes a user's role within a specific tenant. Can set to owner, admin, or user. When changing to owner, the current owner is demoted to admin.

{"role":"admin"}

{"message":"Role updated"}

Returns a preview of what would happen if the user were deleted. Shows all tenants where the user is the owner and lists other members who could take ownership. Returns <code>canDelete: false</code> if the user is the sole owner of the root tenant.

{"canDelete":true,"ownerships":[{"tenantId":"...","tenantName":"Acme Corp","isRoot":false,"otherMembers":[{"userId":"...","email":"bob@acme.com","displayName":"Bob","role":"admin","joinedAt":"..."}]}]}

Permanently deletes a user account. For tenants where the user is the owner, specify a replacement owner or confirm tenant deletion. The request body must resolve all ownership conflicts identified by the preflight endpoint.

{"replacementOwners":{"tenantId":"newOwnerUserId"},"confirmTenantDeletions":["tenantId"]}

{"message":"User deleted"}

Returns all subscription plans with subscriber counts.

{"plans":[{"id":"...","name":"Pro","description":"...","monthlyPriceCents":2900,"annualDiscountPct":20,"usageCreditsPerMonth":1000,"creditResetPolicy":"reset","bonusCredits":0,"userLimit":10,"entitlements":{"feature_x":{"type":"bool","boolValue":true,"description":"..."}},"isSystem":false,"createdAt":"..."}]}

Returns full details for a single plan.

{"id":"...","name":"Pro","description":"...","monthlyPriceCents":2900,...}

Returns all unique entitlement keys currently in use across all plans, with their types and descriptions.

{"keys":[{"key":"feature_x","type":"bool","description":"Enable feature X"}]}

Creates a new subscription plan. Plan names must be unique. Credit reset policy can be <code>reset</code> (credits reset each month) or <code>accrue</code> (unused credits roll over). Set <code>userLimit</code> to 0 for unlimited users.

{"name":"Enterprise","description":"For large teams","monthlyPriceCents":9900,"annualDiscountPct":25,"usageCreditsPerMonth":5000,"creditResetPolicy":"accrue","bonusCredits":1000,"userLimit":0,"entitlements":{"feature_x":{"type":"bool","boolValue":true,"description":"Enable feature X"}}}

{"id":"...","name":"Enterprise",...}

Updates an existing plan. System plans (Free) cannot be renamed. All fields from the create endpoint are accepted.

{"name":"Enterprise Plus","monthlyPriceCents":14900,...}

{"id":"...","name":"Enterprise Plus",...}

Deletes a plan. System plans and plans with active subscribers cannot be deleted. Reassign subscribers first.

{"status":"deleted"}

Returns all credit bundles (active and inactive), sorted by sort order.

{"bundles":[{"id":"...","name":"500 Credits","credits":500,"priceCents":4900,"isActive":true,"sortOrder":1,"createdAt":"..."}]}

Creates a new credit bundle for purchase. Bundle names must be unique. Credits and price must be positive values.

{"name":"1000 Credits","credits":1000,"priceCents":8900,"isActive":true,"sortOrder":2}

{"id":"...","name":"1000 Credits","credits":1000,...}

Updates an existing credit bundle.

{"name":"1000 Credits","credits":1000,"priceCents":7900,...}

{"id":"...","name":"1000 Credits",...}

Permanently deletes a credit bundle.

{"status":"deleted"}

Returns paginated billing transactions across all tenants. Supports filtering by tenant and text search across description, invoice number, plan name, and bundle name.

{"transactions":[{"id":"...","tenantId":"...","description":"Pro Plan (Annual)","type":"subscription","amountCents":29900,"currency":"usd","invoiceNumber":"INV-0001","planName":"Pro","createdAt":"..."}],
 "total":150,"page":1,"perPage":50}

Returns time-series financial data for charting. Supported metrics: <code>revenue</code> (daily revenue), <code>arr</code> (annualized recurring revenue), <code>dau</code> (daily active users), <code>mau</code> (monthly active users).

{"data":[{"date":"2026-02-01","value":15000},{"date":"2026-02-02","value":18500},...]}

Returns all active API keys with metadata. The key hash is never returned — only the preview (last 8 characters) is shown.

{"apiKeys":[{"id":"...","name":"CI/CD Pipeline","keyPreview":"x7k9m2pq","authority":"admin","createdBy":"...","createdAt":"...","lastUsedAt":"...","isActive":true}]}

Creates a new API key and returns the raw key value. <strong>The raw key is only returned once</strong> — it is stored as a SHA-256 hash and cannot be retrieved later. Authority levels: <code>admin</code> keys auto-resolve the root tenant and get admin-level access; <code>user</code> keys require an <code>X-Tenant-ID</code> header.

{"name":"CI/CD Pipeline","authority":"admin"}

{"apiKey":{"id":"...","name":"CI/CD Pipeline","keyPreview":"x7k9m2pq","authority":"admin",...},"rawKey":"lsk_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmno"}

Soft-deletes an API key. The key immediately stops working for authentication. This cannot be undone.

{"status":"deleted"}

Returns all active webhook configurations sorted by creation date (newest first).

{"webhooks":[{"id":"...","name":"Provisioning","description":"...","url":"https://example.com/webhook","secretPreview":"k9m2pqx7","events":["tenant.created"],"isActive":true,"createdBy":"...","createdAt":"..."}]}

Returns all webhook event types that can be subscribed to, with descriptions.

{"eventTypes":[{"type":"tenant.created","description":"Fired when a new tenant is created..."}]}

Creates a new webhook with an auto-generated signing secret (prefixed <code>whsec_</code>). The full secret is returned in the response — you can also retrieve it later from the detail endpoint. All deliveries include an <code>X-Webhook-Signature</code> header containing the HMAC-SHA256 signature of the payload.

{"name":"Provisioning","description":"Provision new tenants","url":"https://example.com/webhook","events":["tenant.created"]}

{"webhook":{"id":"...","name":"Provisioning",...},"secret":"whsec_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef"}

Returns full webhook configuration including the signing secret and the 20 most recent delivery attempts with their payloads and response details.

{"webhook":{"id":"...","name":"Provisioning",...},"secret":"whsec_...","deliveries":[{"id":"...","eventType":"tenant.created","payload":"{...}","responseCode":200,"responseBody":"ok","success":true,"durationMs":120,"createdAt":"..."}]}

Updates the webhook's name, description, URL, or subscribed events. The signing secret is not affected.

{"name":"Updated Name","description":"...","url":"https://new-url.com/webhook","events":["tenant.created"]}

{"webhook":{"id":"...","name":"Updated Name",...}}

Soft-deletes a webhook. It immediately stops receiving event deliveries.

{"status":"deleted"}

Delivers a test <code>tenant.created</code> event with sample data to the webhook URL. The delivery includes an <code>X-Webhook-Test: true</code> header so your handler can distinguish test deliveries. Returns the delivery result.

{"delivery":{"id":"...","eventType":"tenant.created","success":true,"responseCode":200,"durationMs":85,"createdAt":"..."}}

Generates a new signing secret for the webhook. The old secret immediately stops working. Returns the new secret and preview.

{"secret":"whsec_NEWsecretABCDEFGHIJKLMNOPQRSTUV","secretPreview":"QRSTUV12"}

Validate a short-lived Domain Connect callback state and resume domain lifecycle polling.

Receive GitHub webhooks.

Receive GitLab push and merge request webhooks (X-Gitlab-Token pre-shared secret).

Receive Bitbucket Cloud push and pull-request webhooks (X-Hub-Signature HMAC-SHA256).

Handle the GitHub App setup callback after installation.

Trigger a deploy hook by token.

Receive a server heartbeat from the agent.

Serves the shell script that installs the permanu-agent on a server.

Called by the install script to register the server and receive agent credentials.

Issues a fresh install token when presented with an HMAC-signed predecessor token (expired or not). Rate-limited to 10 refreshes per 24 h per operator. Enables G-A3 install retry without operator re-minting.

Rotates the agent refresh token. Replayed tokens trigger chain revocation.

Issues fresh credentials (server_id, agent_secret, tokens) for an agent that has lost its identity. Bootstrap key is one-shot rotated on use. Rate-limited to 5/hour/machine_id.

Merges DB-side heartbeat state with a live AGENT_STATUS gRPC probe — agent version, uptime, docker reachable, disk/memory free, clock skew. Tolerates an unreachable agent: DB view is still returned with live_probe_error populated.

Returns the last N command dispatches (pending/inflight/failed/completed). Currently 501 — control plane does not yet persist per-server command history; follow-up migration pending.

Returns the last ?lines=N (default 200, capped at 2000) lines from the permanu-agent systemd unit via journalctl.

Issues a COMMAND_TYPE_AGENT_PING round-trip and returns RTT in milliseconds plus computed clock skew.

Ingest error events using the Sentry envelope wire protocol. Authenticates via DSN public key.

Accept OpenTelemetry OTLP exports (protobuf or JSON). Exception span events are translated to permanu.error/v1 and stored in the error-tracking pipeline. Auth: Authorization: Bearer <dsn-key>. Rate-limited: 1000/s per token.

List container lifecycle events for an app.

List container lifecycle events for a server.

Create a notification channel.

List notification channels.

Get a notification channel by ID.

Update a notification channel.

Delete a notification channel.

Send a test notification through a channel.

Create an uptime monitor.

List uptime monitors.

Get an uptime monitor by ID.

Update an uptime monitor.

Delete an uptime monitor.

List recent checks for an uptime monitor.

Get uptime percentage for a monitor.

Create a custom monitoring dashboard.

List dashboards for the org.

Get a dashboard by ID.

Update a dashboard.

Delete a dashboard.

Clone a dashboard.

Issue a signed share link for a dashboard (HMAC-SHA256, TTL-based).

Revoke the public share token for a dashboard.

Revoke all HMAC share links for a dashboard by bumping the revocation serial. Returns { revoked: true, serial: N }.

List embed origins allowlisted for this dashboard.

Add an https origin to the dashboard embed allowlist.

Remove an origin from the dashboard embed allowlist. Pass origin as ?origin= query param.

Retrieve a dashboard by its HMAC-signed share token. Returns 401 if token is invalid or expired.

Retrieve a dashboard by its public share token.

Run a PromQL instant query for a shared dashboard. Metric names must match the dashboard's panel allowlist.

Run a PromQL range query for a shared dashboard. Metric names must match the dashboard's panel allowlist.

Create a metric-based alert rule.

List alert rules for the org.

Get an alert rule by ID.

Update an alert rule.

Delete an alert rule.

List alert firing history for the org.

Acknowledge an alert firing.

List predefined alert templates for database services.

Create an alert rule from a predefined template.

Create an alert silence (suppresses notifications for a rule or all rules).

List alert silences for the org.

Delete an alert silence.

Ingest an error event using the Deploy-native JSON format.

List error groups for the org.

Get an error group by ID.

Update the status of an error group.

Mark an error group as resolved (PM-020).

Mark an error group as ignored (PM-020).

List recent events for an error group.

Create an error DSN.

List error DSNs.

Delete an error DSN.

Upload a source map for stack trace deobfuscation. Rate-limited: 1000/s per token.

List source maps for an app.

Delete a source map.

Filter + paginate VL logs for an app. Params: app_id, time_range, level_filter, regex, limit, cursor.

Pre-canned VL stats aggregations. type=count_by_level|count_over_time|top_recurring_errors.

Two-pass orchestration: query anchor events then return all logs within ±window_seconds.

Pre-canned PromQL panel. name=error_rate|latency_p95|rss_per_container|cpu_per_container|request_rate.

List per-user saved query configurations.

Persist a QueryBuilder configuration as a named bookmark.

One-shot context bundle for the named app/host/incident (AI agent entry point).

Diff two deployments: env keys, config, domains, image.

Returns a unified, newest-first slice of mutations across deployments, apps, env_vars, env_var_leases, domain_assignments, and server state transitions. Accepts ?app=<idOrSlugOrName>, ?since=<dur> (default 24h, max 30d), ?limit=<n> (default 100, max 500), ?types=<csv> (deploy|app.update|env.set|env.rotate|env.remove|domain.add|domain.remove|server.state). Tenant-scoped; never emits env var values.

Ingest analytics events (PostHog-compatible). Accepts single-event or batch bodies. Rate-limited to 1000 events/sec per token.

Get deployment analytics.

Get deployment analytics summary.

Get historical server metrics.

Get resource cost analytics.

List verified domains owned by the authenticated user. Used by the /measure domain picker dropdown.

List tenant-scoped analytics events. Filters: name, appId, from, to (RFC3339), limit (1..1000, default 100).

Returns the top-20 event names by count over the requested window. Defaults: last 7 days.

SSE stream of new tenant-scoped events. Filters: name, appId. Cursor: ?since=<RFC3339> or Last-Event-ID. Polls events table on a 1s tick (no LISTEN/NOTIFY).

Compute a multi-step funnel with strict-next ordering. Body: { steps:[2..10], from, to, step_window_hours }. Limit 30 req/min per tenant.

Bucket users by first cohort_event occurrence (day|week|month) and compute retention-per-period. Body: { cohort_event, cohort_period, return_event, periods:[1..52] }.

Return D1/D7/D30 retention % for users who did ANY event in the window. Body: { from, to, periods:[d1,d7,d30] }.

Push per-service measurements from any tool (not just the agent). Accepts single or batch bodies with an optional RFC3339 timestamp. Rate-limited to 1000 req/sec per service_instance.

Get app metrics.

Resolve an app UUID or slug to tenant-scoped route and container metric matchers.

Resolve an app UUID or slug to app-scoped metric families, query templates, availability diagnostics, and concrete route/container matchers.

Resolve an app UUID or slug to tenant/domain labels and return route metric headlines, series, freshness, and empty-state reasons.

Get server metrics.

Resolve a scope_kind/scope_id/range entity into graph neighbors, deployments, incidents, logs, traces, and diagnostic empty reasons.

Return SLO/error-budget state for a scoped app, service, or repo. Missing configuration is returned as a scoped diagnostic empty state.

Returns per service_instance measurements (connections, ops/sec, heap, ...). range=1h|6h|24h|7d (default 24h).

Mint a new api_key for the authenticated tenant. The key authenticates pushes to POST /api/services/:id/metrics.

List push api_keys for the authenticated tenant.

Revoke a push api_key. The deletion is hard — subsequent ingest requests with the key return 401.

Return the declared MetricExposed entries for the service's template with per-instance overrides merged on top.

Upsert a sparse per-instance override (display/unit/thresholds/...) for a template-declared or custom metric.

Remove a per-instance override so the response falls back to the template-declared values.

Proxy a PromQL instant query to VictoriaMetrics with mandatory tenant isolation.

Proxy a PromQL range query to VictoriaMetrics with mandatory tenant isolation.

Proxy a PromQL instant query to VictoriaMetrics with mandatory tenant isolation and app route/container scoping.

Proxy a PromQL range query to VictoriaMetrics with mandatory tenant isolation and app route/container scoping.

List metric names matching a prefix, scoped to the tenant.

List distinct values for a label on a metric, scoped to the tenant.

Returns scoped public reliability checks for global, server, route, DNS, Dwaar, agent, Docker, and version drift surfaces.

Create a project within the current tenant.

List projects for the current tenant.

Get a single project by ID.

Update mutable project fields.

Delete a project and its associations.

List apps that belong to a project.

Create an app inside a project.

Link an existing app to a project.

Link an existing service to a project.

List services attached to a project.

List service-instance connections within a project (canvas edges).

List project outputs and generated endpoints.

Create a project-level environment variable.

List project-level environment variables.

Update value, is_secret, or stage_bindings for a project env var.

Reveal plaintext value of a project env var (emits audit log).

Delete a project-level environment variable.

Get the project's backup storage configuration.

Set the project's backup storage configuration.

Test the custom S3 connection.

Create an app in the current tenant.

List apps in the current tenant.

Get app details and status.

Update app configuration.

Delete an app.

List domains assigned to an app.

Open an interactive exec session in the app container.

List placement rules for an app.

Create a placement rule for an app.

Delete a placement rule for an app.

Cordon a server — prevent new deployments from targeting it.

Uncordon a server — allow deployments to target it again.

Drain a server — cordon it and mark it as draining.

Undrain a server — clear draining state and allow deployments to target it again.

Get server operational status including cordon and drain flags.

Create a server pool with label selectors and cost tracking.

List server pools for the current tenant.

Delete a server pool.

Assign a server to a pool.

Get a linear capacity forecast (days-to-exhaustion) for CPU, memory, and disk.

Get edge config for an app.

Update edge config for an app (path routing, redirects, IP allowlist, rate limits).

Purge all Dwaar cache entries for a host (PM-034).

Purge a single path from Dwaar cache (PM-034).

Get the rollout policy for an app.

Create a rollout policy for an app.

Update the rollout policy for an app.

Delete the rollout policy for an app.

Get the latest health score for a deployment.

Create an environment for an app.

List environments for an app.

Update an app environment.

Assign a public hostname to an environment.

Delete an app environment.

Tenant-wide environment DAG: nodes + promotion edges with health overlay and 1h/24h/7d metrics.

List deployments visible to the current tenant.

Get a single deployment by ID, deriving app ownership from the deployment row.

Create a deployment for an app.

List deployments for an app.

Get a deployment by ID.

List queued deployment intents for an app.

Get a queued deployment intent.

Cancel a queued deployment intent.

Approve a queued deployment intent.

Reject a queued deployment intent.

Get app deployment readiness checks.

Get app deployment defaults and auto-deploy policy.

Update app deployment defaults and auto-deploy policy.

Rollback an app to a previous deployment.

Restart an app.

Stop an app.

Start an app.

Stream deployment progress over SSE (auto-resolves to latest in-progress deployment).

Stream progress for a specific deployment over SSE.

Replay buffered deploy-progress events from the NATS event log. Use after SSE reconnect to recover missed events. Query params: from_ts (Unix ms, required, max 24h lookback), limit (1–2000, default 500).

Stop the preview process for a deployment.

Approve a deployment that is waiting for review.

Reject a deployment that is waiting for review.

Cancel a pending deployment.

Update approval policy for an app.

Update resource limits for an app.

Create a deployment for an environment.

List deployments for an environment.

Update reverse-proxy route for an app to a different server.

Trigger SSL re-provisioning for a domain assignment.

Run a live DNS resolution check for a domain assignment.

Approve a deployment that was gated by an approval policy.

Reject a deployment that was gated by an approval policy. A comment is required.

Get the configured preview domain.

Update the configured preview domain.

Create a deploy hook for an app.

List deploy hooks for an app.

Delete a deploy hook.

Create a volume snapshot backup for an app.

List backups for an app.

Create a restore operation from a backup.

List restore operations for an app.

Update backup status (agent callback).

Create a service backup.

List service backups.

Restore a service backup.

Generate a pre-signed download URL for a backup.

Delete a backup.

List restore operations for a service.

Get backup configuration for a service.

Update backup configuration for a service.

Test S3 connectivity for BYO-S3 backup storage.

List preview environments for an app.

Close a preview environment.

Create a reusable secret variable template.

List secret templates for the current tenant.

Get a secret template by ID.

Delete a secret template.

List the caller's app-scoped deploy tokens.

Mint a deploy token bound to a single app.

Revoke an app-scoped deploy token.

Create an app-level environment variable.

List app-level environment variables.

Update an app-level environment variable.

Delete an app-level environment variable by ID.

Create multiple environment variables at once.

Reveal the plaintext value of an env var (audited).

List recent secret_read audit entries for an env var (admin-only).

List app-level env vars for an app.

Get resolved environment variables for an environment.

Upsert environment-level variable overrides.

Delete an environment-level override.

Clone environment variables from another environment.

Create an auto-remediation policy for an app.

List all remediation policies for an app.

Get a single remediation policy.

Partially update a remediation policy.

Delete a remediation policy.

Trigger immediate execution of a remediation policy. Add ?dry_run=true for dry-run mode.

List remediation execution history for an app.

Get a single remediation execution.

Approve a pending remediation execution.

Reject a pending remediation execution.

Generate a stateless HMAC install token for agent-based server registration.

Register a new server with the control plane.

List servers visible to the current tenant.

Get server details.

Update mutable server metadata.

Replace mutable server labels used for fleet placement and CI runner opt-in.

Delete a server from the tenant.

Reinstall the server agent and bootstrap state.

Reconnect an existing server to the control plane.

Retry cleanup for a server that failed to deprovision.

Force delete a server that cannot be removed cleanly.

Relink all apps and services from one server to another. Used when a new agent replaces a stale one on the same VPS.

List pending orphan cleanup records for a server.

Dismiss an orphan cleanup item — removes it from the sweeper queue.

Get latest top processes snapshot for a server.

Get command queue depth for a server.

Drain all queued commands for a server.

Force-disconnect a stale gRPC CommandStream.

Get install progress steps for a server.

Stream server events over SSE.

Get container health alerts for a server.

Get uptime stats (24h/7d/30d) for a server.

Returns the deploy-net Docker network membership table from the target server's agent: every container with its IP, MAC, mapped app (if any), and unexpected_on_deploy_net flag. Polls every 10 s in the UI. Returns 422 when the agent is offline.

Revokes all active agent tokens for the server and force-disconnects the live gRPC stream. Use after a credential leak. After revocation, click Re-enroll to issue fresh credentials.

List per-server ACL grants. Requires admin access on the server.

Grant or update a user's role on the server. Body: {user_id, role}. Requires admin access on the server.

Revoke a user's ACL grant on the server. Requires admin access on the server.

Issues COMMAND_TYPE_RESTART_SELF to the agent. Agent acks then exits after 1 s; systemd Restart=always reconnects it within ~5 s. Returns {queued:true, command_id, estimated_reconnect_seconds:5}. 409 if a restart was already issued within 30 s (double-click guard). 422 if the agent is offline.

Mints a one-shot install token and issues COMMAND_TYPE_REENROLL. Online path: agent downloads and runs the idempotent installer, rotates credentials, and restarts — returns {queued:true, online:true, command_id, install_url, expires_at}. Offline path: returns {online:false, paste_command, install_url} so the operator can copy-paste into a recovery shell. 409 if a re-enrollment is already in-flight (5-min guard). EX-004.