{"openapi":"3.0.3","info":{"title":"Vonzio API","description":"The Vonzio HTTP API lets you create and manage Claude agent profiles, store\nper-agent secrets, schedule autonomous playbook runs, and inspect long-lived\nworkspaces. Everything you can do in the dashboard is reachable here.\n\n## Authentication\n\nAll routes require a bearer token. Mint one in the dashboard:\n**Settings → API tokens → Create token**, then pass it in the\n`Authorization` header on every request:\n\n```\nAuthorization: Bearer rc_<your-token>\n```\n\nThe token bypasses interactive auth and acts on behalf of the user who\ncreated it. Tokens never expire — rotate them in Settings if exposed.\n\n## Conventions\n\n- **Versioning**: every business endpoint sits under `/v1/`. Breaking\n  changes get a new prefix; non-breaking additions land in-place.\n- **Errors**: `4xx`/`5xx` responses return a structured body\n  (`{ error: { code, message } }`) — see the `Error` component.\n- **Timestamps**: ISO-8601 strings in UTC unless noted.\n- **IDs**: UUIDs except for typed prefixes (`prof_*`, `pb_*`,\n  `sec_*`, `rc_*`).\n\n## Getting started\n\nThe fastest path from zero to a working agent:\n\n1. `POST /v1/api-keys` — store an Anthropic API key (or link an Ollama\n   endpoint).\n2. `POST /v1/profiles` — create an agent profile referencing the key.\n3. `POST /v1/secrets` — add any per-agent secrets the agent needs (DB\n   URLs, third-party tokens). Scope them to the profile.\n4. `POST /v1/playbooks` — optional: schedule the agent on a cron.\n5. `POST /v1/tasks` — kick off a one-shot run, or chat with the\n   profile in the dashboard.\n\nEach section below documents the endpoints in detail.","version":"1.0.0","contact":{"name":"Vonzio","url":"https://vonz.io"}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Vonzio API token (prefix `rc_`). Create one in the dashboard under Settings → API tokens."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"VALIDATION_FAILED"},"message":{"type":"string","example":"name is required"}}}}},"Profile":{"type":"object","required":["id","name","slug","provider","created_at","updated_at"],"additionalProperties":true,"properties":{"id":{"type":"string","example":"prof_4XgS61A_vp7lfWXopdIMV"},"user_id":{"type":"string","nullable":true,"description":"Owning user. `null` for shared/system profiles visible to everyone."},"name":{"type":"string","example":"VZFinance"},"slug":{"type":"string","description":"URL- and mention-safe identifier (`@vzfinance` in Slack).","example":"vzfinance"},"provider":{"type":"string","enum":["api_key","ollama"],"description":"How the agent talks to the model."},"api_key_id":{"type":"string","nullable":true},"model":{"type":"string","nullable":true,"description":"Family alias resolved at runtime: `sonnet` / `opus` / `haiku`, or empty for default.","example":"opus"},"effort":{"type":"string","enum":["low","medium","high","max"],"nullable":true},"claude_md":{"type":"string","nullable":true,"description":"Agent system prompt."},"default_tools":{"type":"array","items":{"type":"string"}},"default_egress_domains":{"type":"array","items":{"type":"string"}},"mcp_servers":{"type":"array","items":{"type":"object","additionalProperties":true}},"agent_ids":{"type":"array","items":{"type":"string"}},"skill_ids":{"type":"array","items":{"type":"string"}},"git_provider_ids":{"type":"array","items":{"type":"string"}},"persistent_sessions":{"type":"boolean"},"memory_enabled":{"type":"boolean"},"max_turns":{"type":"integer","nullable":true,"minimum":1},"auto_continue":{"type":"boolean"},"max_continuations":{"type":"integer","minimum":1,"maximum":200},"continuation_budget_usd":{"type":"number","nullable":true,"minimum":0},"concurrency_limit":{"type":"integer","minimum":1},"setup_commands":{"type":"array","items":{"type":"string"}},"container_image":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true}}},"CreateProfileInput":{"type":"object","required":["name"],"additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"maxLength":64},"slug":{"type":"string"},"provider":{"type":"string","enum":["api_key","ollama"],"default":"api_key"},"api_key_id":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"effort":{"type":"string","enum":["low","medium","high","max"],"nullable":true},"claude_md":{"type":"string","nullable":true},"default_tools":{"type":"array","items":{"type":"string"}},"default_egress_domains":{"type":"array","items":{"type":"string"}},"persistent_sessions":{"type":"boolean"},"memory_enabled":{"type":"boolean"},"max_turns":{"type":"integer","nullable":true,"minimum":1},"auto_continue":{"type":"boolean"},"max_continuations":{"type":"integer","minimum":1,"maximum":200},"continuation_budget_usd":{"type":"number","nullable":true,"minimum":0},"concurrency_limit":{"type":"integer","minimum":1},"setup_commands":{"type":"array","items":{"type":"string"}}}},"UpdateProfileInput":{"type":"object","description":"All fields optional — only provided fields are updated.","additionalProperties":true,"properties":{"name":{"type":"string","minLength":1,"maxLength":64},"slug":{"type":"string"},"api_key_id":{"type":"string","nullable":true},"model":{"type":"string","nullable":true},"effort":{"type":"string","enum":["low","medium","high","max"],"nullable":true},"claude_md":{"type":"string","nullable":true},"default_tools":{"type":"array","items":{"type":"string"}},"default_egress_domains":{"type":"array","items":{"type":"string"}},"persistent_sessions":{"type":"boolean"},"memory_enabled":{"type":"boolean"},"max_turns":{"type":"integer","nullable":true,"minimum":1},"auto_continue":{"type":"boolean"},"max_continuations":{"type":"integer","minimum":1,"maximum":200},"continuation_budget_usd":{"type":"number","nullable":true,"minimum":0},"concurrency_limit":{"type":"integer","minimum":1},"setup_commands":{"type":"array","items":{"type":"string"}}}},"Secret":{"type":"object","required":["id","user_id","name","value","scope","profile_ids","created_at","updated_at"],"additionalProperties":true,"properties":{"id":{"type":"string","example":"sec_xQ8...e0"},"user_id":{"type":"string"},"name":{"type":"string","description":"Env-var-shaped: `^[A-Z_][A-Z0-9_]*$`.","example":"DATABASE_URL"},"value":{"type":"string","description":"Always redacted to `••••••••` over the API.","example":"••••••••"},"scope":{"type":"string","enum":["all","agents"]},"profile_ids":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreateSecretInput":{"type":"object","required":["name","value"],"additionalProperties":true,"properties":{"name":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]*$"},"value":{"type":"string"},"scope":{"type":"string","enum":["all","agents"],"default":"all"},"profile_ids":{"type":"array","items":{"type":"string"}}}},"UpdateSecretInput":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","pattern":"^[A-Z_][A-Z0-9_]*$"},"value":{"type":"string"},"scope":{"type":"string","enum":["all","agents"]},"profile_ids":{"type":"array","items":{"type":"string"}}}},"PlaybookChainConfig":{"type":"object","required":["max_chains","budget_cap_usd","chain_delay_ms"],"additionalProperties":true,"properties":{"max_chains":{"type":"integer","minimum":1,"maximum":20},"budget_cap_usd":{"type":"number","minimum":0.1,"maximum":100},"chain_delay_ms":{"type":"integer","minimum":1000,"maximum":60000},"max_turns_per_chain":{"type":"integer","minimum":5,"maximum":200},"allowed_tools":{"type":"array","items":{"type":"string"}},"timeout_per_chain_seconds":{"type":"integer","minimum":60}}},"Playbook":{"type":"object","required":["id","user_id","profile_id","name","prompt","schedule","chain_config","enabled","notify_on","trigger_type","created_at","updated_at"],"additionalProperties":true,"properties":{"id":{"type":"string","example":"pb_Hg0Q2OvYGi7SiBZ7usVVJ"},"user_id":{"type":"string"},"profile_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"prompt":{"type":"string"},"schedule":{"type":"string","example":"0 23 * * *"},"chain_config":{"$ref":"#/components/schemas/PlaybookChainConfig"},"enabled":{"type":"boolean"},"notify_on":{"type":"string","enum":["completion","failure","both","none"]},"notification_channels":{"type":"array","items":{"type":"string"}},"trigger_type":{"type":"string","enum":["cron","interval","manual","webhook"]},"interval_seconds":{"type":"integer","nullable":true,"minimum":60},"webhook_token":{"type":"string","nullable":true},"success_criteria":{"type":"array","items":{"type":"object","additionalProperties":true},"nullable":true},"last_run_at":{"type":"string","format":"date-time","nullable":true},"next_run_at":{"type":"string","format":"date-time","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreatePlaybookInput":{"type":"object","required":["name","profile_id","prompt","schedule"],"additionalProperties":true,"properties":{"name":{"type":"string"},"description":{"type":"string"},"profile_id":{"type":"string"},"prompt":{"type":"string"},"schedule":{"type":"string"},"chain_config":{"$ref":"#/components/schemas/PlaybookChainConfig"},"enabled":{"type":"boolean","default":false},"trigger_type":{"type":"string","enum":["cron","interval","manual","webhook"],"default":"cron"},"interval_seconds":{"type":"integer","minimum":60},"notify_on":{"type":"string","enum":["completion","failure","both","none"],"default":"none"},"notification_channels":{"type":"array","items":{"type":"string"}},"success_criteria":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"PlaybookRun":{"type":"object","required":["id","playbook_id","status","started_at"],"additionalProperties":true,"properties":{"id":{"type":"string"},"playbook_id":{"type":"string"},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"decision":{"type":"string","nullable":true,"enum":["pass","fail","skipped"]},"chains_used":{"type":"integer"},"turns_used":{"type":"integer"},"cost_usd":{"type":"number"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time","nullable":true},"error":{"type":"string","nullable":true},"result_summary":{"type":"string","nullable":true}}},"Workspace":{"type":"object","required":["session_id","profile_id","status","created_at"],"additionalProperties":true,"properties":{"session_id":{"type":"string"},"profile_id":{"type":"string"},"name":{"type":"string","nullable":true},"status":{"type":"string","enum":["active","idle","paused","resumable","expired"]},"container_status":{"type":"string","nullable":true},"container_id":{"type":"string","nullable":true},"last_active_at":{"type":"string","format":"date-time"},"last_run_model":{"type":"string","nullable":true},"model_override":{"type":"string","nullable":true},"starred":{"type":"boolean"},"archived":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"WorkspaceEvent":{"type":"object","required":["seq","type","created_at"],"additionalProperties":true,"properties":{"seq":{"type":"integer"},"type":{"type":"string"},"payload":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"Task":{"type":"object","required":["id","status","mode","profile_id","prompt","created_at"],"additionalProperties":true,"properties":{"id":{"type":"string"},"mode":{"type":"string","enum":["batch","session","stream"]},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"profile_id":{"type":"string"},"session_id":{"type":"string","nullable":true},"prompt":{"type":"string"},"model":{"type":"string","nullable":true},"allowed_tools":{"type":"array","items":{"type":"string"},"nullable":true},"max_turns":{"type":"integer","nullable":true},"max_budget_usd":{"type":"number","nullable":true},"result":{"type":"object","nullable":true,"additionalProperties":true},"error":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":"string","format":"date-time","nullable":true},"finished_at":{"type":"string","format":"date-time","nullable":true}}},"SubmitTaskInput":{"type":"object","required":["profile_id","prompt"],"additionalProperties":true,"properties":{"profile_id":{"type":"string"},"prompt":{"type":"string"},"mode":{"type":"string","enum":["batch","session","stream"],"default":"batch"},"session_id":{"type":"string"},"model":{"type":"string"},"allowed_tools":{"type":"array","items":{"type":"string"}},"max_turns":{"type":"integer","minimum":1},"max_budget_usd":{"type":"number","minimum":0},"effort":{"type":"string","enum":["low","medium","high","max"]},"output_schema":{"type":"object","additionalProperties":true}}}}},"paths":{"/health":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/config":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/invite/validate":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/invite/accept":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/auth/error":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/auth/{*}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/events":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/tasks":{"post":{"summary":"Submit a one-shot task","tags":["Tasks"],"description":"Fires an agent run against a profile. Returns immediately with the `Task` row; for `mode='batch'` the run continues in the background — poll `/v1/tasks/:id` for status. For `mode='session'`, the task becomes a long-lived workspace and is reachable via `/v1/workspaces/:session_id`. For `mode='stream'`, open the WebSocket at `/ws` to follow output live. Body validated by `SubmitTaskInput`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitTaskInput"}}}},"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List tasks","tags":["Tasks"],"description":"Returns tasks visible to the caller. Scoped to the user's profiles unless the caller is admin. Supports filtering by `status` and `mode`, plus `page`/`limit` pagination.","parameters":[{"schema":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["batch","session","stream"]},"in":"query","name":"mode","required":false},{"schema":{"type":"string"},"in":"query","name":"page","required":false},{"schema":{"type":"string"},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/tasks/{id}":{"get":{"summary":"Get a task","tags":["Tasks"],"description":"Returns the task by id. 404 when missing or not in any of the caller's profile IDs.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Cancel a task","tags":["Tasks"],"description":"Cancels a queued or running task. Returns 404 if already completed/missing.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/workspaces":{"get":{"summary":"List workspaces","tags":["Workspaces"],"description":"Returns the user's workspaces. Supports filtering by `status` and pagination via `page` + `limit`. Admin users see all workspaces.","parameters":[{"schema":{"type":"string","enum":["active","idle","paused","resumable","expired"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"in":"query","name":"page","required":false,"description":"1-based page number. Default 1."},{"schema":{"type":"string"},"in":"query","name":"limit","required":false,"description":"Page size. Default 50, max 200."}],"responses":{"200":{"description":"Default Response"}}}},"/v1/workspaces/{id}":{"get":{"summary":"Get a workspace","tags":["Workspaces"],"description":"Returns a single `Workspace` by `session_id`. 404 if missing or not accessible.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true,"description":"Workspace session_id (UUID)."}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Terminate a workspace","tags":["Workspaces"],"description":"Stops and removes the underlying container. The workspace row remains for history.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Update a workspace","tags":["Workspaces"],"description":"Patches user-mutable fields. Notable: `model_override` (per-workspace model picker — pass `null` to clear), `starred`/`pinned`/`archived` for organization, `public_preview` to expose the preview iframe.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string"},"starred":{"type":"boolean"},"pinned":{"type":"boolean"},"archived":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"public_preview":{"type":"boolean"},"model_override":{"type":"string","nullable":true}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/workspaces/{id}/events":{"get":{"summary":"Get the workspace event log","tags":["Workspaces"],"description":"Returns the structured event timeline for this workspace — every token, tool call, tool result, and message in order. Each item is a `WorkspaceEvent`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/workspaces/{id}/generate-title":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/workspaces/{id}/files":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/workspaces/{id}/upload":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/workspaces/{id}/archive":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/profiles":{"post":{"summary":"Create a profile","tags":["Profiles"],"description":"Creates a new agent profile owned by the authenticated user. `slug` is auto-derived from `name` if omitted and collision-resolved against the user's existing profiles. Returns the full `Profile` (see schemas).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProfileInput"}}}},"responses":{"200":{"description":"Default Response"}}},"get":{"summary":"List profiles","tags":["Profiles"],"description":"Returns the authenticated user's profiles plus any shared/system profiles visible to everyone. Each item is a `Profile`.","responses":{"200":{"description":"Default Response"}}}},"/v1/profiles/{id}":{"get":{"summary":"Get a profile","tags":["Profiles"],"description":"Returns a single `Profile`. 404 if the id is unknown or the user can't access it.","parameters":[{"schema":{"type":"string","example":"prof_4XgS61A_vp7lfWXopdIMV"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"summary":"Update a profile","tags":["Profiles"],"description":"Patches the profile. Only provided fields are touched. Returns the updated `Profile`. Useful endpoints to call here: `claude_md` (sync the agent's system prompt from a repo), `model` (switch family), `memory_enabled`, `default_tools`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileInput"}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a profile","tags":["Profiles"],"description":"Soft-blocks if the profile has live dependencies (workspaces, playbooks). Returns `{ status: 'deleted', profile_id }` on success.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/profiles/{id}/models":{"get":{"summary":"List models available to this profile","tags":["Profiles"],"description":"Returns the model list the profile's API key has access to. Anthropic profiles return `claude-*` IDs; Ollama profiles return their installed-locally set. Cached server-side by `api_key_id` (5-minute TTL), so repeated calls don't hammer the provider.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/tools":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/tools/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/skills":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/skills/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/agents":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/agents/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/git-providers":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/git-providers/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/anthropic-keys":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/anthropic-keys/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/api-tokens":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/api-tokens/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/secrets":{"get":{"summary":"List secrets","tags":["Secrets"],"description":"Returns the user's vault entries. **Values are always redacted** to `••••••••` — they're never returned in plaintext over the API. The agent decrypts them in the container at runtime. Each item is a `Secret`.","responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a secret","tags":["Secrets"],"description":"Stores an encrypted secret (AES-256-GCM) in the user's vault. `name` becomes the env-var name in agent containers — must match `^[A-Z_][A-Z0-9_]*$`. Scope determines which agents see it: `all` (default) injects into every container the user runs; `agents` restricts to the listed `profile_ids` (must all belong to the user).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSecretInput"}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/secrets/{id}":{"patch":{"summary":"Update a secret","tags":["Secrets"],"description":"Patches `name`, `value`, `scope`, or `profile_ids`. Omitted fields are untouched. To clear a per-agent grant entirely, set `scope: 'all'` (clears `profile_ids` automatically) or set `profile_ids` to a new non-empty list.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSecretInput"}}}},"parameters":[{"schema":{"type":"string","example":"sec_xQ8...e0"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a secret","tags":["Secrets"],"description":"Removes the secret. Returns `{ status: 'deleted', secret_id }`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/git-providers/oauth/config":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/git-providers/oauth/{provider}/authorize":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"provider","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/slack/config":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/slack/authorize":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/config":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/connect":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/connect-platform":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/bots":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/bots/for-workspace/{sessionId}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"sessionId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/status":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/bots/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/regenerate-link-code":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/telegram/disconnect":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/gmail/config":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/gmail/authorize":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/teller/config":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/teller/callback":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/integrations/{id}/test":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/memories":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}},"delete":{"responses":{"200":{"description":"Default Response"}}}},"/v1/memories/search":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/memories/{id}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/playbooks":{"get":{"summary":"List playbooks","tags":["Playbooks"],"description":"Returns the authenticated user's playbooks. Each item is a `Playbook`.","responses":{"200":{"description":"Default Response"}}},"post":{"summary":"Create a playbook","tags":["Playbooks"],"description":"Schedules a new playbook against a profile. `prompt` is the input the agent receives on each run. For `trigger_type='cron'`, `schedule` is a 5-field cron expression (UTC). For `interval`, see `interval_seconds`. Set `enabled: true` to make the scheduler pick it up immediately. Server clamps `chain_config` to safe bounds (see PlaybookChainConfig schema). Returns the full `Playbook`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePlaybookInput"}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/playbooks/{id}":{"patch":{"summary":"Update a playbook","tags":["Playbooks"],"description":"Patches any field on the playbook. Cron `schedule` changes are re-validated. The scheduler's next-run time is recomputed automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"Any subset of CreatePlaybookInput fields."}}},"description":"Any subset of CreatePlaybookInput fields."},"parameters":[{"schema":{"type":"string","example":"pb_Hg0Q2OvYGi7SiBZ7usVVJ"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"summary":"Delete a playbook","tags":["Playbooks"],"description":"Removes the playbook (and stops it from being scheduled). Returns `{ status: 'deleted', playbook_id }`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/playbooks/{id}/run":{"post":{"summary":"Manually fire a playbook","tags":["Playbooks"],"description":"Triggers an immediate run (out-of-schedule). Returns `202 Accepted` and runs in the background — poll `/v1/playbooks/:id/runs` for status. Useful for one-off testing or backfills.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/playbooks/{id}/runs":{"get":{"summary":"List runs for a specific playbook","tags":["Playbooks"],"description":"Returns the per-playbook run history in reverse-chronological order. Each item is a `PlaybookRun`.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/playbook-runs":{"get":{"summary":"List all playbook runs (cross-playbook)","tags":["Playbooks"],"description":"Returns recent runs across every playbook the user owns. Each item is a `PlaybookRun`.","responses":{"200":{"description":"Default Response"}}}},"/v1/playbook-runs/{id}":{"get":{"summary":"Get a single playbook run","tags":["Playbooks"],"description":"Returns the run detail including status, chains/turns/cost, decision result, and any error.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/playbook-runs/{id}/cancel":{"post":{"summary":"Cancel an in-flight playbook run","tags":["Playbooks"],"description":"Signals the chain runner to stop. Returns `400` if the run isn't active.","parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/playbooks/scheduler/status":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/playbooks/scheduler/pause":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/playbooks/scheduler/resume":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/v1/pool":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/pool/containers":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/pool/containers/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/ollama/models":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/git/callback/{provider}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"provider","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/api/slack/callback":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/gmail/callback":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/v1/webhook/playbook/{token}":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"token","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/mcp/memory":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/mcp/notify":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/mcp/gmail":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/mcp/teller":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/mcp/platform":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/slack/events":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/slack/commands":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/slack/interactions":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/api/telegram/webhook/{botId}":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"botId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/bootstrap":{"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/keys":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/keys/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/api-keys":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/api-keys/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/api-keys/{id}/validate":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/profiles":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/profiles/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/tools":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/tools/{id}/code":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/tools/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/skills":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/skills/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/agents":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/agents/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/git-providers":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/git-providers/{id}":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/profiles/{id}/validate":{"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/images":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/admin/invites":{"get":{"responses":{"200":{"description":"Default Response"}}},"post":{"responses":{"200":{"description":"Default Response"}}}},"/admin/invites/{id}":{"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/users/{userId}/flags":{"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"userId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/admin/events":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/admin/events/funnel":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/api/preview-auth":{"get":{"responses":{"200":{"description":"Default Response"}}}},"/preview/{containerId}/{port}/{*}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"head":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"trace":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"options":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/preview/{containerId}/{port}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}},"head":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}},"trace":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}},"options":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}},"patch":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}},"post":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"port","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/preview/{containerId}/files/{*}":{"get":{"parameters":[{"schema":{"type":"string"},"in":"path","name":"containerId","required":true},{"schema":{"type":"string"},"in":"path","name":"*","required":true}],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://app.vonz.io","description":"Production"},{"url":"http://vonz.localhost","description":"Local dev"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Profiles","description":"Agent profile management"},{"name":"Secrets","description":"Per-agent encrypted environment variables"},{"name":"Playbooks","description":"Scheduled and autonomous agent runs"},{"name":"Workspaces","description":"Long-running chat sessions backed by Docker containers"},{"name":"Tasks","description":"One-shot agent runs"}]}