Deploy

POST /api/deploy

Provisions a deployment of a catalog tool into the calling user's tenant. This is what the deploy wizard calls when the user clicks "Launch". It is session-authenticated only — deployed tools and external SDKs cannot deploy on a tenant's behalf.

Auth

Session cookie (vendo.run dashboard). No Bearer token form.

Pre-flight checks

Before provisioning, the endpoint enforces:

• The session belongs to an authenticated user (401 otherwise).
• The user owns the target tenant (tenants.owner_id) — 403 otherwise.
• The user has already chosen a workspace slug (slug_chosen).
• The billing gate is satisfied (skipped for test tenants and Vendo admins).
• The tool is enabled in the catalog and has an active release (enabled = false rejects with 403 { "error": "tool_unreleased" } for non-admin callers).
• The desired deploymentSlug is unique within the tenant and the rendered {tenant_slug}-{deployment_slug}.vendo.run subdomain doesn't collide with another live deployment.
• Every provider in bindings[] matches an enabled row in the integrations catalog.
• Every required integration in the tool's release manifest has a caller-supplied connection or a vendo_managed_pool fallback profile.

Request body

{
  "toolSlug": "hermes",                    // required, max 100 chars
  "tenantSlug": "acme",                    // required, max 100 chars
  "deploymentSlug": "support-bot",         // optional, max 63 chars; defaults to defaultDeploymentSlugForTool(toolSlug)
  "deploymentName": "Support Bot",         // optional, max 100 chars; blanks collapse to undefined
  "adminPassword": "…",                    // optional, max 200 chars — only for tools that seed an admin user
  "userVariables": {                       // optional — wizard inputs declared in the tool's manifest
    "TIMEZONE": "America/Los_Angeles"      // values: string (max 10000 chars), number, or boolean
  },
  "bindings": ["openrouter", "telegram"],  // optional — provider slugs the integration picker opted into
  "selectedBindings": {                    // optional — provider_slug → connection UUID
    "openrouter": "00000000-0000-0000-0000-000000000000"
  },
  "pendingBindings": {                     // optional — provider_slug → inline-BYOK payload
    "telegram": { "bot_token": "…" }       // forwarded to the integration's inlineConnect() to validate + persist
  },
  "userInput": { }                         // optional — values referenced as ${userInput.<field>} in afterDeploy hooks
}

Only toolSlug and tenantSlug are required. bindings, selectedBindings, userVariables are zod-validated. pendingBindings and userInput are passed through without schema validation — only the provider's inlineConnect() and the hook engine sees them.

Idempotency-Key HTTP header is honored: repeat calls with the same key replay the cached response. The idempotency scope is keyed on {tenant_id}:/api/deploy plus the request body.

Response: 201 Created

{ "deploymentId": "dpl_…" }

Use the returned id with /api/deployments/{id}/… endpoints to poll status, restart, suspend, or destroy.

Errors

Bodies are flat — no error wrapper. Each row below is { "message": "…", "code": "…", … } at the listed HTTP status.

Example error body:

{
  "message": "A deployment already exists at acme-support-bot.vendo.run. Pick a different slug.",
  "code": "SLUG_TAKEN"
}

Rate limit

deployLimiter: 5 requests per hour per IP. Bursts beyond return 429 with body { "message": "Rate limit exceeded" }.

POST /api/connections/bind-deployment

Called by the connect-portal pages after a connection lands when the originating URL carried ?deployment_id=<id>. Writes the app_connection_bindings row that links a new connection to the deployment that asked for it. Idempotent on (app_id, provider_slug).

Auth

Session cookie. The caller's tenant must own both the deployment and the connection.

Request body

{
  "deploymentId": "dpl_…",
  "providerSlug": "openrouter",
  "connectionId": "00000000-0000-0000-0000-000000000000"
}

All three fields are required strings.

Response

Success:

{ "ok": true }

Telegram bindings that have a webhook setup failure return 200 with a soft warning:

{ "ok": true, "webhook_warning": "..." }

Conflict on an "exclusive" provider (e.g. Telegram bot tokens) — 409:

{
  "ok": false,
  "reason": "connection_in_use",
  "bound_to": { "deployment_slug": "other", "deployment_name": "Other" }
}

Errors

Error bodies use the { ok: false, reason: "..." } shape:

Owner-only deployment management

The rest of the per-deployment surface lives under /api/deployments/{id}/… and is session-authenticated (owner only). These are dashboard-only — not part of the SDK or CLI contract — and beyond the scope of this page. Notable ones:

Related

• Apps — manage keys and bindings on a deployed app
• Connections — runtime read of bound integrations
• Build a tool > Deploy and publish