REST endpoints

All endpoints below live under https://app.vonz.io (prod) or http://vonz.localhost (dev). Versioned routes (/v1/*) require authentication; unversioned routes are either public or use bespoke auth (Telegram signing, Slack signature, OAuth callbacks).

This page is hand-written, focused on the concepts and shapes you need to know. For machine-readable schemas and an interactive request-builder, jump to:

OpenAPI explorer (Swagger UI) ↗ Interactive playground — paste a token, fill in parameters, hit Try it out. Auto-generated from the same Zod schemas the server uses at runtime, so it's always accurate.

OpenAPI JSON ↗ Raw spec for client-generators (openapi-typescript, openapi-generator, etc.). The source of truth — this prose page is a guided summary.

When this page and the OpenAPI spec disagree, the spec wins — it’s generated from the live Zod schemas while this page is hand-edited and can lag.

Health

`GET /health`

Public. Returns { ok: true, version, pool: { … } }. Liveness check for orchestrators / load balancers.

Tasks

`POST /v1/tasks`

Submit a task. Returns { task_id, status, created_at }.

{
  "mode": "session",                  // or "batch"
  "profile_id": "prof_…",
  "prompt": "Summarize my unread emails",
  "session_id": "sess_… (optional)",  // continue an existing session
  "allowed_tools": ["Bash"],          // override profile's defaults
  "max_turns": 10,
  "max_budget_usd": 1.0,
  "priority": "normal"
}

`mode`	Meaning
`batch`	Fire-and-forget. Result polled via `GET /v1/tasks/:id`. Container is reaped on completion.
`session`	Interactive. Bound to a workspace; container stays warm for follow-ups.

`GET /v1/tasks`

List tasks. Query: status, mode, page, limit.

`GET /v1/tasks/:id`

One task. Includes result.text, result.tool_calls[], result.input_tokens, result.output_tokens, result.cost_usd, result.turns once complete.

`DELETE /v1/tasks/:id`

Cancel a running task. Idempotent: if already done, no-op.

Workspaces (sessions)

`GET /v1/workspaces`

List your workspaces. Query: status (filter), page, limit.

Response: { workspaces: WorkspaceSummary[], total: number }. Playbook-only workspaces (session_id prefix pb-) are excluded unless they’ve been thread-claimed via Telegram — see Telegram integration.

`GET /v1/workspaces/:id`

One workspace.

`PATCH /v1/workspaces/:id`

Update mutable fields: name, starred, pinned, archived, tags, public_preview, model_override.

`DELETE /v1/workspaces/:id`

Permanent delete. Removes the container, volume (if any), and DB row.

`GET /v1/workspaces/:id/events`

The full event-log transcript: every token, tool call, tool result, user message, turn boundary. Use for debugging, replay, audit.

`GET /v1/workspaces/:id/files?path=…`

Browse the workspace’s filesystem inside the container.

`POST /v1/workspaces/:id/upload`

Multipart upload to /workspace/<path> in the container.

`GET /v1/workspaces/:id/archive?paths=…`

Tarball download of selected paths.

Profiles

`GET /v1/profiles`

List your profiles.

`POST /v1/profiles`

Create. Required: name, slug, api_key_id. Optional: model, default_tools, mcp_servers, claude_md, memory_enabled, persistent_sessions, etc.

`GET /v1/profiles/:id`

Full profile (including claude_md).

`PATCH /v1/profiles/:id`

Update.

`DELETE /v1/profiles/:id`

Delete. Existing workspaces remain.

`GET /v1/profiles/:id/models`

Models available to this profile (filtered by linked api_key_id capabilities).

Playbooks

`GET /v1/playbooks?profile_id=…`

List playbooks for a profile.

`POST /v1/playbooks`

Create. See Playbooks concept for field semantics.

`GET /v1/playbooks/:id`

One playbook.

`PATCH /v1/playbooks/:id`

Update.

`DELETE /v1/playbooks/:id`

Delete.

`POST /v1/playbooks/:id/run`

Fire immediately. Returns 202 Accepted with { status: "started", playbook_id }. Poll /v1/playbooks/:id/runs for status.

`GET /v1/playbooks/:id/runs`

Historical runs.

`POST /webhook/playbooks/:secret`

Webhook trigger (no auth — secret in URL). For trigger_type=webhook playbooks.

Integrations

`GET /v1/integrations`

List your integrations. Sensitive config fields (bot_token, refresh_token, access_token, api_key, secret) are redacted to ••••••••.

`POST /v1/integrations`

Create an email or webhook integration. (Slack uses OAuth, Gmail uses OAuth, Telegram uses BotFather + claim, Teller uses Connect — see per-integration docs.)

{ "type": "webhook", "config": { "url": "https://hooks.zapier.com/…", "secret": "optional-hmac" } }

`PATCH /v1/integrations/:id`

Update config, enabled, is_default, scope, profile_ids. Cross-user profile_ids are rejected with 400.

`DELETE /v1/integrations/:id`

Disconnect.

`POST /v1/integrations/:id/test`

Send a test notification through this integration.

Integration-specific OAuth callbacks

GET /api/slack/callback — Slack OAuth return
GET /api/gmail/callback — Gmail OAuth return
POST /v1/integrations/teller/callback — Teller Connect’s onSuccess payload sink
POST /v1/integrations/teller/config — application_id, environment, etc. (configures the dashboard widget)
GET /v1/integrations/telegram/config + various /v1/integrations/telegram/* for bot setup

Memory

`GET /v1/memories`

List your memory rows (across all profiles).

`POST /v1/memories`

Create. Required: type, name, body. Optional: profile_id, description, importance.

`GET /v1/memories/:id`

One memory row.

`PATCH /v1/memories/:id`

Update.

`DELETE /v1/memories/:id`

Delete.

Secrets

`GET /v1/secrets`

List secret names (values redacted).

`POST /v1/secrets`

Create. Body: { name, value, scope?, profile_ids? }. Name must match ^[A-Z_][A-Z0-9_]*$. Cross-user profile_ids rejected with 400.

`PATCH /v1/secrets/:id`

Update name, value, scope, profile_ids.

`DELETE /v1/secrets/:id`

Delete.

Tools / Skills / Subagents

Identical surface for all three types:

List	Create	Get	Update	Delete
`GET /v1/tools`	`POST /v1/tools`	`GET /v1/tools/:id`	`PATCH /v1/tools/:id`	`DELETE /v1/tools/:id`
`GET /v1/skills`	`POST /v1/skills`	`GET /v1/skills/:id`	`PATCH /v1/skills/:id`	`DELETE /v1/skills/:id`
`GET /v1/agents`	`POST /v1/agents`	`GET /v1/agents/:id`	`PATCH /v1/agents/:id`	`DELETE /v1/agents/:id`

Git providers

`GET /v1/git-providers`

List your connected Git provider accounts (GitHub / GitLab / Bitbucket OAuth).

`GET /v1/integrations/git/:provider/authorize?returnPath=…`

Begin OAuth.

`GET /v1/integrations/git/:provider/callback`

OAuth return URL.

`DELETE /v1/git-providers/:id`

Disconnect.

Pool (admin-ish)

`GET /v1/pool`

Container-pool stats (min/max/in-use/idle).

`GET /v1/pool/containers`

List managed containers.

`DELETE /v1/pool/containers/:id`

Force-remove a container. Requires admin.

Admin endpoints

Under /admin/*. Operator-only; not documented here. See Authentication → Admin endpoints.