Apps

The /api/apps/* surface manages apps — the rows that back each deployment in the apps table (renamed from tool_authorizations in migration 130; Drizzle still exports the symbol as toolAuthorizations). One app per deployment, one or more keys per app, one binding per provider per app. All endpoints are session-authenticated and scoped to the caller's tenant.

GET /api/apps

List every active app in the caller's tenant.

Auth

Session cookie.

Response: 200 OK

{
  "apps": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "kind": "deployment",
      "display_name": null,
      "key_prefix": "vendo_sk_a1b2",
      "connected_at": "2026-05-01T12:00:00Z",
      "tool_id": "00000000-0000-0000-0000-000000000001",
      "tool_slug": "hermes",
      "tool_name": "Hermes"
    }
  ]
}

Only active apps (disconnected_at IS NULL) are returned, ordered by connected_at DESC.

Errors

PATCH /api/apps/{id}

Update an app's spend caps or display name. All fields are optional — send only the keys you want to change.

Auth

Session cookie. Caller must own the tenant that owns the app.

Request body

{
  "spend_cap_daily": 5.00,              // USD; converted to micros server-side. Set to null to clear.
  "spend_cap_monthly": 100.00,          // USD; converted to micros. Set to null to clear.
  "display_name": "Support Bot"          // 1–80 chars after trim
}

Caps accept numbers or numeric strings in the range [0, 1_000_000] USD. Server converts to integer micros.

Response: 200 OK

{
  "app": {
    "id": "00000000-0000-0000-0000-000000000000",
    "display_name": "Support Bot",
    "spend_cap_micros_daily": "5000000",
    "spend_cap_micros_monthly": "100000000"
  }
}

Errors

POST /api/apps/{id}/keys

Mint an additional App Key on an existing app. The plaintext is returned exactly once; persist it client-side.

Auth

Session cookie. Caller must own the tenant that owns the app.

Response: 200 OK

{
  "key": "vendo_sk_…",                       // plaintext, returned exactly once
  "keyId": "00000000-0000-0000-0000-000000000000",
  "prefix": "vendo_sk_a1b2"
}

The new key is bound to the same app (scope: { mode: "app", appId }) as the original deploy-time key. Adding a key doesn't change which deployment the app backs, and the proxy resolves attribution on-demand.

Errors

GET /api/apps/{id}/bindings

List the connection bindings for an app (app_connection_bindings). One row per (app_id, provider_slug).

Auth

Session cookie. Caller must own the tenant that owns the app.

Response: 200 OK

{
  "bindings": [
    {
      "provider_slug": "openrouter",
      "connection": {
        "id": "00000000-0000-0000-0000-000000000000",
        "profile": "vendo_managed_pool",
        "status": "active",
        "display_name": "OpenRouter (Vendo managed)",
        "metadata": { }
      },
      "cardKind": null
    }
  ]
}

If the caller doesn't own the app, the response is 200 { bindings: [] } (silently empty) — not an error.

POST /api/apps/{id}/bindings

Create a binding from an app to a connection. Two modes:

1. Managed-pool fast path — body { "provider_slug": "openrouter" }. Lazy-creates (or re-uses) a vendo_managed_pool connections row for the tenant. Only valid for providers whose default_profile = "vendo_managed_pool".
2. Explicit binding — body { "provider_slug": "telegram", "connection_id": "00000000-…" }. Binds an existing connection the tenant already owns.

Idempotent on (app_id, provider_slug): if a binding already exists, returns { ok: true, already_connected: true }.

Auth

Session cookie. Caller must own the tenant that owns both the app and the connection.

Response: 200 OK

{
  "ok": true,
  "connection_id": "00000000-0000-0000-0000-000000000000",
  "already_connected": false,            // true if the binding pre-existed
  "restartRequired": true                  // present when a new binding was written; tells the dashboard to prompt a restart
}

Errors

PUT /api/apps/{id}/bindings

Swap which connection an app uses for a given provider. Same validation, same error shapes — but always operates on an existing binding (won't create a missing one).

Request body

{
  "provider_slug": "openrouter",
  "connection_id": "00000000-0000-0000-0000-000000000000"
}

Both fields required.

Response: 200 OK

{ "ok": true, "restartRequired": true }

The deploy's deployment_env_vars rows (kind=integration) are upserted with the new connection's credentials so the proxy resolves the new connection on the next call.

Errors

Same as POST — invalid_body, provider_mismatch, connection_inactive, connection_not_found, not_found, connection_in_use (409), and 500.

Related

• Connections (runtime) — what the deployed app sees after a binding lands
• Keys — mint and revoke vendo_sk_* keys
• Concepts > Connections