# Auto-generated by scripts/generate-openapi.ts — DO NOT EDIT # Regenerate: cd assistant && bun run generate:openapi openapi: 3.1.0 info: title: Vellum Assistant API version: 0.11.5 description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server. servers: - url: http://127.0.0.1:7821 description: Local assistant (default port) paths: /healthz: get: operationId: healthz_get summary: Liveness probe description: Trivial liveness/startup probe. Returns { status, version } the instant the HTTP server is up, with zero DB/CES/lifecycle access. responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string version: type: string required: - status - version additionalProperties: false /pages/{id}: get: operationId: pages__id__get parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response /readyz: get: operationId: readyz_get summary: Readiness probe description: "Readiness probe. Returns 200 while DB migrations are running (body { status: 'migrating', ready: false, dbMigrations }) so orchestrators keep the pod in service, then a stable 200 { status: 'ok', ready: true } once migrations complete. Returns 503 only when migrations failed. CES is informational and never gates readiness." responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string ready: type: boolean reason: type: string dbMigrations: type: object properties: ready: type: boolean state: type: string enum: - not_started - running - failed - ready reason: type: string error: type: string required: - ready - state additionalProperties: false required: - status - ready additionalProperties: false "503": description: DB migrations failed — daemon requires a restart. content: application/json: schema: type: object properties: status: type: string ready: type: boolean reason: type: string dbMigrations: type: object properties: ready: type: boolean state: type: string enum: - not_started - running - failed - ready reason: type: string error: type: string required: - ready - state additionalProperties: false required: - status - ready additionalProperties: false /v1/acp/{id}/cancel: post: operationId: acp_by_id_cancel_post summary: Cancel ACP session description: Cancel an active ACP session. tags: - acp parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: acpSessionId: type: string cancelled: type: boolean required: - acpSessionId - cancelled additionalProperties: false /v1/acp/{id}/close: post: operationId: acp_by_id_close_post summary: Close ACP session description: Close a completed ACP session. tags: - acp parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: acpSessionId: type: string closed: type: boolean required: - acpSessionId - closed additionalProperties: false /v1/acp/{id}/steer: post: operationId: acp_by_id_steer_post summary: Steer ACP session description: "Send a steering instruction to an ACP session. Sessions no longer in memory (completed, or lost to a daemon restart) are transparently resumed from persisted history first, when the agent supports ACP session loading. Resuming a terminal session re-spawns the host agent, so it requires guardian approval: the route acks immediately with approvalPending=true and performs the resume in the background once approved, streaming results over SSE." tags: - acp parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: instruction: type: string required: - instruction responses: "200": description: Successful response content: application/json: schema: type: object properties: acpSessionId: type: string steered: type: boolean resumed: description: True when the session was resumed from persisted history before steering. type: boolean approvalPending: description: True when the steer triggered a guardian-approval-gated resume that will run asynchronously; watch SSE for the outcome. type: boolean required: - acpSessionId - steered additionalProperties: false /v1/acp/claude/auth/connected: get: operationId: acp_claude_auth_connected_get summary: Report whether Claude is connected description: Returns whether a Claude OAuth token is present in the workspace vault so the web client can self-heal the inline Connect Claude affordance when the account is already connected. Never returns the token value. tags: - acp responses: "200": description: Successful response content: application/json: schema: type: object properties: connected: type: boolean required: - connected additionalProperties: false /v1/acp/claude/auth/exchange: post: operationId: acp_claude_auth_exchange_post summary: Exchange a manual Connect Claude authorization code description: "Complete a containerized/manual Connect Claude flow: accept the pasted `code#state` (or a raw code plus state), exchange it against Claude's manual redirect URI, and store the Claude OAuth token." tags: - acp requestBody: required: true content: application/json: schema: type: object properties: code: type: string state: type: string required: - code - state responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/acp/claude/auth/start: post: operationId: acp_claude_auth_start_post summary: Start Connect Claude OAuth flow description: "Return a PKCE authorize URL plus a state token. On a local host (`mode: loopback`) the daemon binds a loopback callback and captures the redirect itself; on a containerized host — or when the client sets `preferManual` because its browser can't reach the daemon's loopback (`mode: manual`) — it targets Claude's manual redirect page and the web client posts the pasted `code#state` back to `.../auth/exchange`." tags: - acp requestBody: required: true content: application/json: schema: type: object properties: preferManual: type: boolean responses: "200": description: Successful response content: application/json: schema: type: object properties: mode: type: string enum: - loopback - manual authorize_url: type: string state: type: string required: - mode - authorize_url - state additionalProperties: false /v1/acp/claude/auth/status/{state}: get: operationId: acp_claude_auth_status_by_state_get summary: Poll Connect Claude OAuth flow status description: Returns the current status of an in-flight Connect Claude OAuth flow (pending/connected/error) so the web client can react once the token has landed. tags: - acp parameters: - name: state in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - pending - connected - error error: type: string required: - status additionalProperties: false "404": description: No active OAuth flow for the given state /v1/acp/sessions: delete: operationId: acp_sessions_delete summary: Bulk-clear terminal ACP sessions description: Remove every terminal-state row (completed/failed/cancelled) from the persisted acp_session_history table. Rows whose session is currently active in memory (e.g. resumed) or has a resume in flight are excluded. tags: - acp parameters: - name: status in: query required: true schema: type: string description: Must be 'completed'. Shorthand for all terminal statuses (completed/failed/cancelled). responses: "200": description: Successful response content: application/json: schema: type: object properties: deleted: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - deleted additionalProperties: false get: operationId: acp_sessions_get summary: List ACP sessions description: Return the merged set of in-memory and persisted ACP sessions, newest first. In-memory sessions take precedence on id collision. tags: - acp parameters: - name: limit in: query required: false schema: type: integer description: Maximum number of sessions to return (default 50, max 500). - name: conversationId in: query required: false schema: type: string description: Filter to sessions whose parentConversationId matches this value. responses: "200": description: Successful response content: application/json: schema: type: object properties: sessions: type: array items: type: object properties: id: type: string agentId: type: string acpSessionId: type: string parentConversationId: type: string status: type: string startedAt: type: number completedAt: anyOf: - type: number - type: "null" error: anyOf: - type: string - type: "null" stopReason: anyOf: - type: string - type: "null" task: type: string parentToolUseId: type: string usedTokens: type: number contextSize: type: number costAmount: type: number costCurrency: type: string inputTokens: type: number outputTokens: type: number eventLog: type: array items: {} required: - id - agentId - acpSessionId - status - startedAt additionalProperties: false description: Merged in-memory and persisted ACP sessions. required: - sessions additionalProperties: false /v1/acp/sessions/{id}: delete: operationId: acp_sessions_by_id_delete summary: Delete ACP session from history description: Remove a persisted ACP session row. Rejects with 409 when the session is still active in memory or has a resume in flight; idempotent for unknown ids. tags: - acp parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: deleted: type: boolean required: - deleted additionalProperties: false /v1/acp/spawn: post: operationId: acp_spawn_post summary: Spawn ACP session description: Start a new Agent Communication Protocol session. tags: - acp requestBody: required: true content: application/json: schema: type: object properties: agent: type: string description: Agent name task: type: string description: Task description conversationId: type: string cwd: type: string description: Working directory required: - agent - task - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: acpSessionId: type: string protocolSessionId: type: string agent: type: string required: - acpSessionId - protocolSessionId - agent additionalProperties: false /v1/admin/rollback-migrations: post: operationId: admin_rollbackmigrations_post summary: Rollback migrations description: Roll back DB and/or workspace migrations to a specified target version. Restricted to gateway service principals. tags: - admin requestBody: required: true content: application/json: schema: type: object properties: targetDbVersion: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Target DB migration version targetWorkspaceMigrationId: type: string description: Target workspace migration ID rollbackToRegistryCeiling: type: boolean description: Auto-determine targets from daemon registry ceilings required: - targetDbVersion - targetWorkspaceMigrationId - rollbackToRegistryCeiling responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean rolledBack: type: object properties: {} additionalProperties: {} description: Lists of rolled-back DB and workspace migrations required: - ok - rolledBack additionalProperties: false /v1/admin/upgrade-broadcast: post: operationId: admin_upgradebroadcast_post summary: Broadcast upgrade lifecycle event description: Publish a service group update lifecycle event (starting, progress, or complete) to all connected SSE clients. tags: - admin requestBody: required: true content: application/json: schema: type: object properties: type: type: string description: 'Event type: "starting", "progress", or "complete"' targetVersion: type: string description: Target version (required for starting) expectedDowntimeSeconds: type: number description: Expected downtime in seconds (starting, default 60) statusMessage: type: string description: Status message (required for progress) installedVersion: type: string description: Installed version (required for complete) success: type: boolean description: Whether upgrade succeeded (required for complete) rolledBackToVersion: type: string description: Version rolled back to, if any (complete) required: - type responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/admin/workspace-commit: post: operationId: admin_workspacecommit_post summary: Commit workspace changes description: Create a git commit in the workspace directory with all pending changes. tags: - admin requestBody: required: true content: application/json: schema: type: object properties: message: type: string description: Commit message required: - message responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/admin/workspace-compact-history: post: operationId: admin_workspacecompacthistory_post summary: Compact workspace git history description: Squash workspace git history older than the retention window into a single base commit and prune reclaimed objects. By default acts only when an oversized blob is reclaimable; with force, the squash runs unconditionally. tags: - admin requestBody: required: true content: application/json: schema: type: object properties: force: description: Squash aged history even when no oversized blob is reclaimable type: boolean retentionDays: description: Retention window override in days (default 7) type: integer exclusiveMinimum: 0 maximum: 9007199254740991 responses: "200": description: Successful response content: application/json: schema: type: object properties: rewrote: type: boolean squashedCommits: type: number keptCommits: type: number retryAfterMs: type: number required: - rewrote - squashedCommits - keptCommits additionalProperties: false /v1/apps: get: operationId: apps_get summary: List apps description: Return all locally installed apps. tags: - apps parameters: - name: conversationId in: query required: false schema: type: string description: Filter apps by conversation ID responses: "200": description: Successful response content: application/json: schema: type: object properties: apps: type: array items: type: object properties: id: type: string name: type: string description: type: string icon: type: string createdAt: type: number updatedAt: type: number version: type: string contentId: type: string origin: type: string required: - id - name - createdAt - updatedAt - version - contentId - origin additionalProperties: false required: - apps additionalProperties: false /v1/apps/{appId}/asset/{path}: get: operationId: apps_by_appId_asset_by_path_get summary: Serve app asset description: Serve a bundled binary asset (image, audio, video, font) from anywhere in an app's directory. tags: - apps parameters: - name: appId in: path required: true schema: type: string - name: path in: path required: true schema: type: string responses: "200": description: Successful response /v1/apps/{appId}/dist/{filename}: get: operationId: apps_by_appId_dist_by_filename_get summary: Serve app dist file description: Serve a static asset from an app's compiled dist/ directory. tags: - apps parameters: - name: appId in: path required: true schema: type: string - name: filename in: path required: true schema: type: string responses: "200": description: Successful response /v1/apps/{id}/bundle: post: operationId: apps_by_id_bundle_post summary: Bundle an app description: Package an app into a distributable .vbundle archive. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: type: type: string bundlePath: type: string iconImageBase64: type: string manifest: type: object properties: {} additionalProperties: {} required: - type - bundlePath - iconImageBase64 - manifest additionalProperties: false /v1/apps/{id}/data: get: operationId: apps_by_id_data_get summary: Query app data description: Read records from an app's local data store. tags: - apps parameters: - name: id in: path required: true schema: type: string - name: method in: query required: false schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean result: {} required: - success - result additionalProperties: false post: operationId: apps_by_id_data_post summary: Mutate app data description: Create, update, or delete records in an app's local data store. tags: - apps parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: method: type: string description: "'create', 'update', or 'delete'" recordId: type: string data: type: object properties: {} additionalProperties: {} required: - method - recordId - data responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean result: {} required: - success - result additionalProperties: false /v1/apps/{id}/delete: post: operationId: apps_by_id_delete_post summary: Delete an app description: Permanently remove an app and its data. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false /v1/apps/{id}/open: post: operationId: apps_by_id_open_post summary: Open an app description: Compile (if needed) and return the app's HTML for rendering. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: appId: type: string dirName: type: string name: type: string html: type: string origin: type: string required: - appId - dirName - name - html - origin additionalProperties: false /v1/apps/{id}/preview: get: operationId: apps_by_id_preview_get summary: Get app preview description: Return the preview image or HTML for an app. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: appId: type: string preview: anyOf: - type: string - type: "null" required: - appId - preview additionalProperties: false put: operationId: apps_by_id_preview_put summary: Update app preview description: Set a new preview image or HTML for an app. tags: - apps parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: preview: type: string description: Base64-encoded image or HTML string required: - preview responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean appId: type: string required: - success - appId additionalProperties: false /v1/apps/{id}/publish: post: operationId: apps_by_id_publish_post summary: Publish app to Vercel description: Deploy the app's HTML to Vercel and store the deployment record. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean publicUrl: type: string deploymentId: type: string errorCode: type: string error: type: string required: - success additionalProperties: false /v1/apps/{id}/publish-status: get: operationId: apps_by_id_publishstatus_get summary: Get app publish status description: Return the current Vercel deployment state for an app. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: published: type: boolean publicUrl: type: string deploymentId: type: string publishedAt: type: number required: - published additionalProperties: false /v1/apps/{id}/share-cloud: post: operationId: apps_by_id_sharecloud_post summary: Share app to cloud description: Package and upload an app to the cloud share service. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean shareToken: type: string shareUrl: type: string required: - success - shareToken - shareUrl additionalProperties: false /v1/apps/{id}/unpublish: post: operationId: apps_by_id_unpublish_post summary: Unpublish app from Vercel description: Mark the active Vercel deployment as inactive. tags: - apps parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean error: type: string required: - success additionalProperties: false /v1/apps/fork: post: operationId: apps_fork_post summary: Fork a shared app description: Create a local copy of a shared app by its UUID. tags: - apps requestBody: required: true content: application/json: schema: type: object properties: uuid: type: string description: UUID of the shared app to fork required: - uuid responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean const: true appId: type: string name: type: string required: - success - appId - name additionalProperties: false /v1/apps/import-bundle: post: operationId: apps_importbundle_post summary: Import a .vbundle file description: Upload, validate, and install a .vbundle archive as a new local app. tags: - apps requestBody: required: true content: application/octet-stream: schema: type: string format: binary responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean appId: type: string name: type: string scanResult: type: object properties: passed: type: boolean blocked: type: array items: type: string warnings: type: array items: type: string required: - passed - blocked - warnings additionalProperties: false signatureResult: type: object properties: trustTier: type: string signerKeyId: type: string signerDisplayName: type: string signerAccount: type: string required: - trustTier additionalProperties: false required: - success - appId - name - scanResult - signatureResult additionalProperties: false /v1/apps/open-bundle: post: operationId: apps_openbundle_post summary: Open a .vbundle file description: Scan and validate a .vbundle file from disk and return its manifest. tags: - apps requestBody: required: true content: application/json: schema: type: object properties: filePath: type: string description: Absolute path to the .vbundle file required: - filePath responses: "200": description: Successful response content: application/json: schema: type: object properties: manifest: type: object properties: {} additionalProperties: {} scanResult: type: object properties: passed: type: boolean blocked: type: array items: type: string warnings: type: array items: type: string required: - passed - blocked - warnings additionalProperties: false signatureResult: type: object properties: trustTier: type: string signerKeyId: type: string signerDisplayName: type: string signerAccount: type: string required: - trustTier additionalProperties: false bundleSizeBytes: type: number required: - manifest - scanResult - signatureResult - bundleSizeBytes additionalProperties: false /v1/apps/share: post: operationId: apps_share_post summary: Share an app description: Upload a zip app bundle and create a shareable link. tags: - apps responses: "200": description: Successful response content: application/json: schema: type: object properties: shareToken: type: string shareUrl: type: string bundleSizeBytes: type: number required: - shareToken - shareUrl - bundleSizeBytes additionalProperties: false /v1/apps/shared: get: operationId: apps_shared_get summary: List shared apps description: Return all apps available via cloud share links. tags: - apps responses: "200": description: Successful response content: application/json: schema: type: object properties: apps: type: array items: type: object properties: uuid: type: string name: type: string description: type: string icon: type: string preview: type: string entry: type: string trustTier: type: string signerDisplayName: type: string bundleSizeBytes: type: number installedAt: type: string version: type: string contentId: type: string updateAvailable: type: boolean required: - uuid - name - entry - trustTier - bundleSizeBytes - installedAt additionalProperties: false required: - apps additionalProperties: false /v1/apps/shared/{token}: delete: operationId: apps_shared_by_token_delete summary: Delete shared app description: Remove a shared app link. tags: - apps parameters: - name: token in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false get: operationId: apps_shared_by_token_get summary: Download shared app description: Download a shared app bundle as a zip file. tags: - apps parameters: - name: token in: path required: true schema: type: string responses: "200": description: Successful response content: application/zip: schema: type: string format: binary /v1/apps/shared/{token}/metadata: get: operationId: apps_shared_by_token_metadata_get summary: Get shared app metadata description: Return metadata for a shared app bundle. tags: - apps parameters: - name: token in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: name: type: string description: type: string icon: type: string bundleSizeBytes: type: number required: - name - description - icon - bundleSizeBytes additionalProperties: false /v1/apps/sign-bundle: post: operationId: apps_signbundle_post summary: Sign an app bundle description: Return a signing payload or complete the signing step when signature fields are provided. tags: - apps requestBody: required: true content: application/json: schema: type: object properties: payload: type: string description: Canonical JSON payload to sign signature: type: string keyId: type: string publicKey: type: string required: - payload responses: "200": description: Successful response content: application/json: schema: type: object properties: signed: type: boolean signatureJson: type: object properties: {} additionalProperties: {} payload: type: string message: type: string additionalProperties: false /v1/apps/signing-identity: get: operationId: apps_signingidentity_get summary: Get signing identity description: Return signing identity info. Signing is managed client-side over HTTP. tags: - apps responses: "200": description: Successful response content: application/json: schema: type: object properties: message: type: string required: - message additionalProperties: false /v1/attachments: delete: operationId: attachments_delete summary: Delete attachment description: Delete an attachment by ID. tags: - attachments requestBody: required: true content: application/json: schema: type: object properties: attachmentId: type: string required: - attachmentId responses: "204": description: Successful response post: operationId: attachments_post summary: Upload attachment description: Upload an attachment. Supports application/json (base64 data or file path reference), multipart/form-data (file + filename + mimeType fields), and application/octet-stream (raw bytes with filename and mimeType query params). tags: - attachments requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The file to upload filename: type: string mimeType: type: string required: - file - filename - mimeType responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string filename: type: string mimeType: type: string sizeBytes: type: number kind: type: string required: - id - filename - mimeType - sizeBytes - kind additionalProperties: false /v1/attachments/{id}: get: operationId: attachments_by_id_get summary: Get attachment metadata description: Return metadata and optional base64 data for an attachment. tags: - attachments parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string filename: type: string mimeType: type: string sizeBytes: type: number kind: type: string data: anyOf: - type: string description: Base64-encoded content - type: "null" fileBacked: type: boolean required: - id - filename - mimeType - sizeBytes - kind - data additionalProperties: false /v1/attachments/{id}/content: get: operationId: attachments_by_id_content_get summary: Get attachment content description: Serve raw file bytes for an attachment. Supports Range headers. tags: - attachments parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/octet-stream: schema: type: string format: binary "416": description: Range Not Satisfiable /v1/attachments/lookup: post: operationId: attachments_lookup_post summary: Look up attachment by source path description: Search for a previously registered attachment by its original source path, scoped to a conversation. tags: - attachments requestBody: required: true content: application/json: schema: type: object properties: sourcePath: type: string description: Original source path of the file conversationId: type: string description: Conversation ID to search within required: - sourcePath - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: filePath: type: string required: - filePath additionalProperties: false /v1/attachments/register: post: operationId: attachments_register_post summary: Register a file-backed attachment description: Register an on-disk file as a file-backed attachment. The file must be within the workspace directory and must remain on disk for the lifetime of the attachment. tags: - attachments requestBody: required: true content: application/json: schema: type: object properties: path: type: string description: Absolute path to the file mimeType: type: string description: MIME type of the file filename: type: string description: Display filename (defaults to basename of path) required: - path - mimeType responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string originalFilename: type: string mimeType: type: string sizeBytes: type: number kind: type: string filePath: type: string createdAt: type: number required: - id - originalFilename - mimeType - sizeBytes - kind - filePath - createdAt additionalProperties: false /v1/audio/{audioId}: get: operationId: audio_by_audioId_get summary: Get audio segment description: Retrieve a previously stored audio segment by ID. Unauthenticated — the audioId is an unguessable UUID capability token. tags: - audio parameters: - name: audioId in: path required: true schema: type: string responses: "200": description: Successful response /v1/audit: get: operationId: audit_get summary: List recent tool invocations description: Returns recent tool invocation records from the audit log, ordered by most recent first. tags: - audit parameters: - name: limit in: query required: false schema: type: integer description: Maximum number of entries to return (default 20) responses: "200": description: Successful response content: application/json: schema: type: object properties: invocations: type: array items: {} description: Tool invocation records required: - invocations additionalProperties: false /v1/auth/info: get: operationId: auth_info_get summary: Get authentication status description: Returns platform identity and authentication status for this assistant. tags: - auth responses: "200": description: Successful response content: application/json: schema: type: object properties: platformUrl: anyOf: - type: string - type: "null" assistantId: anyOf: - type: string - type: "null" organizationId: anyOf: - type: string - type: "null" userId: anyOf: - type: string - type: "null" authenticated: type: boolean message: type: string required: - platformUrl - assistantId - organizationId - userId - authenticated additionalProperties: false /v1/avatar/character-components: get: operationId: avatar_charactercomponents_get summary: Get character components description: Return available avatar character components. tags: - avatar responses: "200": description: Successful response content: application/json: schema: type: object properties: bodyShapes: type: array items: type: object properties: id: type: string viewBox: type: object properties: width: type: number height: type: number required: - width - height additionalProperties: false faceCenter: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false svgPath: type: string required: - id - viewBox - faceCenter - svgPath additionalProperties: false eyeStyles: type: array items: type: object properties: id: type: string sourceViewBox: type: object properties: width: type: number height: type: number required: - width - height additionalProperties: false eyeCenter: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false paths: type: array items: type: object properties: svgPath: type: string color: type: string required: - svgPath - color additionalProperties: false required: - id - sourceViewBox - eyeCenter - paths additionalProperties: false colors: type: array items: type: object properties: id: type: string hex: type: string required: - id - hex additionalProperties: false faceCenterOverrides: type: array items: type: object properties: bodyShape: type: string eyeStyle: type: string faceCenter: type: object properties: x: type: number y: type: number required: - x - y additionalProperties: false required: - bodyShape - eyeStyle - faceCenter additionalProperties: false required: - bodyShapes - eyeStyles - colors - faceCenterOverrides additionalProperties: false /v1/avatar/character/ascii: get: operationId: avatar_character_ascii_get summary: Render character as ASCII art description: Render the current native character as ASCII art. tags: - avatar parameters: - name: width in: query required: false schema: type: string description: Width in characters (default 60) responses: "200": description: Successful response content: application/json: schema: type: object properties: ascii: type: string required: - ascii additionalProperties: false /v1/avatar/generate: post: operationId: avatar_generate_post summary: Generate AI avatar description: Generate an AI avatar from a text description and save it. tags: - avatar requestBody: required: true content: application/json: schema: type: object properties: description: type: string required: - description responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean message: type: string required: - ok - message additionalProperties: false /v1/avatar/get: get: operationId: avatar_get_get summary: Get current avatar description: Retrieve the current avatar as a file path or base64 string. tags: - avatar parameters: - name: format in: query required: false schema: type: string description: '"path" or "base64"' responses: "200": description: Successful response /v1/avatar/image: post: operationId: avatar_image_post summary: Upload avatar image description: Upload a base64-encoded image as the avatar; writes the PNG and clears character traits atomically. tags: - avatar requestBody: required: true content: application/json: schema: type: object properties: content: type: string encoding: type: string const: base64 required: - content responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/avatar/notify-updated: post: operationId: avatar_notifyupdated_post summary: Notify avatar updated description: Publish avatar change notifications to connected clients. tags: - avatar responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/avatar/remove: post: operationId: avatar_remove_post summary: Remove custom avatar description: Remove the custom avatar image and restore the character default. tags: - avatar responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean hadAvatar: type: boolean required: - ok - hadAvatar additionalProperties: false /v1/avatar/render-from-traits: post: operationId: avatar_renderfromtraits_post summary: Render avatar from traits description: Write character traits and render an avatar PNG. tags: - avatar requestBody: required: true content: application/json: schema: type: object properties: bodyShape: type: string eyeStyle: type: string color: type: string required: - bodyShape - eyeStyle - color responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/avatar/set: post: operationId: avatar_set_post summary: Set avatar from image file description: Copy an image file to the avatar location. tags: - avatar requestBody: required: true content: application/json: schema: type: object properties: imagePath: type: string required: - imagePath responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/avatar/state: get: operationId: avatar_state_get summary: Get avatar state description: Return the authoritative avatar render mode (character, image, or none). tags: - avatar responses: "200": description: Successful response content: application/json: schema: type: object properties: kind: type: string enum: - character - image - none traits: anyOf: - type: object properties: bodyShape: type: string eyeStyle: type: string color: type: string required: - bodyShape - eyeStyle - color additionalProperties: false - type: "null" source: anyOf: - type: string enum: - builder - upload - ai - type: "null" image: anyOf: - type: object properties: updatedAt: type: string etag: type: string required: - updatedAt - etag additionalProperties: false - type: "null" required: - kind - traits - source - image additionalProperties: false /v1/background-tools: get: operationId: backgroundtools_get summary: List active background tools description: List all active background tool executions, optionally filtered by conversationId. tags: - background-tools parameters: - name: conversationId in: query required: false schema: type: string description: Filter by conversation ID responses: "200": description: Successful response content: application/json: schema: type: object properties: tools: type: array items: type: object properties: id: type: string toolName: type: string conversationId: type: string command: type: string startedAt: type: number required: - id - toolName - conversationId - command - startedAt additionalProperties: false completed: type: array items: type: object properties: id: type: string toolName: type: string conversationId: type: string command: type: string startedAt: type: number status: type: string enum: - completed - failed - cancelled exitCode: anyOf: - type: number - type: "null" output: type: string completedAt: type: number required: - id - toolName - conversationId - command - startedAt - status - exitCode - output - completedAt additionalProperties: false required: - tools - completed additionalProperties: false /v1/background-tools/cancel: post: operationId: backgroundtools_cancel_post summary: Cancel a background tool description: Cancel an active background tool execution by ID. tags: - background-tools requestBody: required: true content: application/json: schema: type: object properties: id: type: string required: - id responses: "200": description: Successful response content: application/json: schema: type: object properties: cancelled: type: boolean required: - cancelled additionalProperties: false /v1/background-wake/drain-due: post: operationId: backgroundwake_draindue_post summary: Drain due background wake work description: Run due heartbeat and scheduler work for a background wake lease. tags: - background-wake requestBody: required: true content: application/json: schema: anyOf: - type: object properties: leaseId: type: string minLength: 1 reason: type: string minLength: 1 sourceGeneration: type: string minLength: 1 startedAt: anyOf: - type: number - type: string deadlineAt: anyOf: - type: number - type: string required: - leaseId - reason - sourceGeneration - startedAt - deadlineAt - type: object properties: lease_id: type: string minLength: 1 reason: type: string minLength: 1 source_generation: type: string minLength: 1 started_at: anyOf: - type: number - type: string deadline_at: anyOf: - type: number - type: string required: - lease_id - reason - source_generation - started_at - deadline_at responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean leaseId: type: string reason: type: string sourceGeneration: type: string startedAt: type: number deadlineAt: type: number required: - accepted - leaseId - reason - sourceGeneration - startedAt - deadlineAt additionalProperties: false /v1/background-wake/intent: get: operationId: backgroundwake_intent_get summary: Get background wake intent description: Return the current computed background wake intent. tags: - background-wake responses: "200": description: Successful response content: application/json: schema: type: object properties: intent: anyOf: - type: object properties: nextWakeAt: type: number actualNextDueAt: type: number reason: type: string enum: - heartbeat - schedule - mixed sourceGeneration: type: string computedAt: type: number sourcePayload: type: object propertyNames: type: string additionalProperties: {} required: - nextWakeAt - actualNextDueAt - reason - sourceGeneration - computedAt - sourcePayload additionalProperties: false - type: "null" required: - intent additionalProperties: false /v1/background-wake/prepare-sleep: post: operationId: backgroundwake_preparesleep_post summary: Prepare for assistant sleep description: Return the current background wake intent and whether sleep should be deferred. tags: - background-wake responses: "200": description: Successful response content: application/json: schema: type: object properties: intent: anyOf: - type: object properties: nextWakeAt: type: number actualNextDueAt: type: number reason: type: string enum: - heartbeat - schedule - mixed sourceGeneration: type: string computedAt: type: number sourcePayload: type: object propertyNames: type: string additionalProperties: {} required: - nextWakeAt - actualNextDueAt - reason - sourceGeneration - computedAt - sourcePayload additionalProperties: false - type: "null" deferSleep: type: boolean required: - intent - deferSleep additionalProperties: false /v1/backup/destinations: get: operationId: backup_destinations_get summary: List configured offsite backup destinations description: Returns the current offsite destinations array, materializing the iCloud Drive default when no explicit array is configured. tags: - backups responses: "200": description: Successful response content: application/json: schema: type: object properties: destinations: type: array items: type: object properties: path: type: string encrypt: type: boolean required: - path - encrypt additionalProperties: false required: - destinations additionalProperties: false /v1/backup/destinations/add: post: operationId: backup_destinations_add_post summary: Add an offsite backup destination description: Appends a new destination. Materializes the iCloud default first if destinations is currently null. Errors if the path already exists. tags: - backups requestBody: required: true content: application/json: schema: type: object properties: path: type: string minLength: 1 description: Absolute path to the destination directory encrypt: description: Encrypt snapshots at this destination (default true) type: boolean required: - path responses: "200": description: Successful response content: application/json: schema: type: object properties: destinations: type: array items: type: object properties: path: type: string encrypt: type: boolean required: - path - encrypt additionalProperties: false required: - destinations additionalProperties: false /v1/backup/destinations/remove: post: operationId: backup_destinations_remove_post summary: Remove an offsite backup destination description: Removes the destination matching the given path. Errors if no matching destination exists. tags: - backups requestBody: required: true content: application/json: schema: type: object properties: path: type: string minLength: 1 description: Exact path match of the destination to remove required: - path responses: "200": description: Successful response content: application/json: schema: type: object properties: destinations: type: array items: type: object properties: path: type: string encrypt: type: boolean required: - path - encrypt additionalProperties: false required: - destinations additionalProperties: false /v1/backup/destinations/set-encrypt: post: operationId: backup_destinations_setencrypt_post summary: Toggle encryption for an existing destination description: Updates the encrypt flag for a destination. Errors if no destination with the given path exists. tags: - backups requestBody: required: true content: application/json: schema: type: object properties: path: type: string minLength: 1 description: Exact path match of an existing destination encrypt: type: boolean description: true to encrypt future snapshots, false for plaintext required: - path - encrypt responses: "200": description: Successful response content: application/json: schema: type: object properties: destination: type: object properties: path: type: string encrypt: type: boolean required: - path - encrypt additionalProperties: false required: - destination additionalProperties: false /v1/backup/disable: post: operationId: backup_disable_post summary: Disable automated backups description: Sets backup.enabled = false. Existing snapshots are untouched. tags: - backups responses: "200": description: Successful response content: application/json: schema: type: object properties: enabled: type: boolean const: false required: - enabled additionalProperties: false /v1/backup/enable: post: operationId: backup_enable_post summary: Enable automated backups description: Sets backup.enabled = true. Optionally overrides intervalHours (1-168), retention (1-100), and offsiteEnabled. tags: - backups requestBody: required: true content: application/json: schema: type: object properties: intervalHours: type: integer minimum: 1 maximum: 168 retention: type: integer minimum: 1 maximum: 100 offsiteEnabled: type: boolean responses: "200": description: Successful response content: application/json: schema: type: object properties: {} additionalProperties: {} /v1/backup/status: get: operationId: backup_status_get summary: Show backup status and next-run timing description: Reports enabled/disabled state, interval and retention, last-run and next-run timing from the backup:last_run_at checkpoint, local snapshot count, and per-destination reachability and snapshot counts. When `backup.offsite.enabled` is false the `offsite` array is empty and `offsiteEnabled` is false. tags: - backups responses: "200": description: Successful response content: application/json: schema: type: object properties: enabled: type: boolean intervalHours: type: number retention: type: number lastRunAt: anyOf: - type: string - type: "null" nextRunAt: anyOf: - type: string - type: "null" localDir: type: string localSnapshotCount: type: number offsiteEnabled: type: boolean offsite: type: array items: type: object properties: path: type: string encrypt: type: boolean reachable: type: boolean snapshotCount: type: number required: - path - encrypt - reachable - snapshotCount additionalProperties: false required: - enabled - intervalHours - retention - lastRunAt - nextRunAt - localDir - localSnapshotCount - offsiteEnabled - offsite additionalProperties: false /v1/backups: get: operationId: backups_get summary: List backup snapshots description: Lists local and offsite backup snapshots. Each offsite destination includes a `reachable` flag reflecting whether the backing volume is currently available. When `backup.offsite.enabled` is false the `offsite` array is empty and `offsiteEnabled` is false — clients should gate offsite UI on `offsiteEnabled` rather than `offsite.length`. tags: - backups responses: "200": description: Successful response content: application/json: schema: type: object properties: local: type: array items: {} offsite: type: array items: type: object properties: destination: type: object properties: {} additionalProperties: {} snapshots: type: array items: {} reachable: type: boolean required: - destination - snapshots - reachable additionalProperties: false offsiteEnabled: type: boolean nextRunAt: anyOf: - type: string - type: "null" required: - local - offsite - offsiteEnabled - nextRunAt additionalProperties: false /v1/backups/create: post: operationId: backups_create_post summary: Create a backup snapshot immediately description: Trigger a manual snapshot. Bypasses the enabled and interval gates, but honors the in-progress mutex — a concurrent caller receives 409. tags: - backups responses: "200": description: Successful response content: application/json: schema: type: object properties: local: type: object properties: {} additionalProperties: {} offsite: type: array items: {} durationMs: type: number required: - local - offsite - durationMs additionalProperties: false /v1/backups/restore: post: operationId: backups_restore_post summary: Restore from a backup snapshot description: "Restores a snapshot into the workspace. Destructive: the underlying commit flow backs up existing files before overwriting. The daemon closes the live SQLite handle before writing and invalidates its config/trust caches afterwards. Credentials are NOT included — users re-authenticate integrations after a restore." tags: - backups requestBody: required: true content: application/json: schema: type: object properties: path: type: string description: Absolute path to the snapshot file to restore required: - path responses: "200": description: Successful response content: application/json: schema: type: object properties: manifest: type: object properties: {} additionalProperties: {} restoredFiles: type: number required: - manifest - restoredFiles additionalProperties: false /v1/backups/verify: post: operationId: backups_verify_post summary: Verify a backup snapshot description: Validates a snapshot without restoring. Decrypts encrypted bundles to a temp file, runs the vbundle validator, and returns a pass/fail status. tags: - backups requestBody: required: true content: application/json: schema: type: object properties: path: type: string description: Absolute path to the snapshot file to verify required: - path responses: "200": description: Successful response content: application/json: schema: type: object properties: valid: type: boolean manifest: type: object properties: {} additionalProperties: {} error: type: string required: - valid additionalProperties: false /v1/bookmarks: get: operationId: bookmarks_get summary: List bookmarks description: Return all bookmarks (newest first), joined with their parent message and conversation. tags: - bookmarks responses: "200": description: Successful response content: application/json: schema: type: object properties: bookmarks: type: array items: type: object properties: id: type: string messageId: type: string conversationId: type: string conversationTitle: anyOf: - type: string - type: "null" messagePreview: type: string messageRole: type: string messageCreatedAt: type: number createdAt: type: number required: - id - messageId - conversationId - conversationTitle - messagePreview - messageRole - messageCreatedAt - createdAt additionalProperties: false required: - bookmarks additionalProperties: false post: operationId: bookmarks_post summary: Create a bookmark description: Bookmark the given message. Idempotent on `messageId` — calling twice returns the same bookmark. tags: - bookmarks requestBody: required: true content: application/json: schema: type: object properties: messageId: type: string conversationId: type: string required: - messageId - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string messageId: type: string conversationId: type: string conversationTitle: anyOf: - type: string - type: "null" messagePreview: type: string messageRole: type: string messageCreatedAt: type: number createdAt: type: number required: - id - messageId - conversationId - conversationTitle - messagePreview - messageRole - messageCreatedAt - createdAt additionalProperties: false /v1/bookmarks/by-message/{messageId}: delete: operationId: bookmarks_bymessage_by_messageId_delete summary: Delete a bookmark by message id description: Delete the bookmark (if any) attached to the given message. Succeeds even if no row matched. tags: - bookmarks parameters: - name: messageId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean const: true required: - success additionalProperties: false /v1/brain-graph: get: operationId: braingraph_get summary: Get brain graph data description: Return a knowledge-graph shaped for brain-lobe visualization, with memory items mapped to brain regions. tags: - brain-graph responses: "200": description: Successful response content: application/json: schema: type: object properties: entities: type: array items: {} description: Graph entity nodes relations: type: array items: {} description: Graph relation edges memorySummary: type: array items: {} description: Memory kind counts and colors totalKnowledgeCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 generatedAt: type: string description: ISO 8601 timestamp required: - entities - relations - memorySummary - totalKnowledgeCount - generatedAt additionalProperties: false /v1/brain-graph-ui: get: operationId: braingraphui_get summary: Serve brain graph UI description: Return the brain-graph HTML visualization page. The gateway injects an auth token before serving. tags: - brain-graph responses: "200": description: Successful response /v1/browser/execute: post: operationId: browser_execute_post summary: Execute a browser operation description: Invoke a browser operation (navigate, click, type, screenshot, etc.) via the headless browser subsystem. tags: - browser requestBody: required: true content: application/json: schema: type: object properties: operation: type: string enum: - navigate - snapshot - screenshot - close - attach - detach - click - type - press_key - scroll - select_option - hover - wait_for - extract - wait_for_download - fill_credential - status input: default: {} type: object propertyNames: type: string additionalProperties: {} sessionId: default: default type: string minLength: 1 conversationId: type: string minLength: 1 required: - operation responses: "200": description: Successful response content: application/json: schema: type: object properties: content: type: string isError: type: boolean screenshots: type: array items: type: object properties: mediaType: type: string data: type: string required: - mediaType - data additionalProperties: false required: - content - isError additionalProperties: false /v1/browser/tabs: post: operationId: browser_tabs_post summary: Manage browser tabs description: List, create, select, or close browser tabs via the Chrome extension backend. tags: - browser requestBody: required: true content: application/json: schema: type: object properties: command: type: string enum: - list - select - new - close sessionId: default: default type: string minLength: 1 conversationId: type: string minLength: 1 tabId: type: number url: type: string targetClientId: type: string minLength: 1 required: - command responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean tabs: type: array items: type: object properties: tabId: type: number windowId: type: number url: type: string title: type: string active: type: boolean pinned: type: boolean required: - active - pinned additionalProperties: false tab: {} tabId: type: number clientId: type: string closed: type: boolean required: - ok additionalProperties: false /v1/btw: post: operationId: btw_post summary: Run ephemeral LLM side-chain description: Stream an ephemeral LLM call reusing the conversation's provider and message history. Response is SSE (btw_text_delta, btw_complete, btw_error). tags: - btw requestBody: required: true content: application/json: schema: type: object properties: conversationKey: type: string description: Conversation key to scope the call content: type: string description: User prompt content clientTimezone: description: IANA timezone reported by the active client type: string required: - conversationKey - content responses: "200": description: Successful response /v1/cache/delete: post: operationId: cache_delete_post summary: Delete a cache entry description: Remove a cached value by key. tags: - cache requestBody: required: true content: application/json: schema: type: object properties: key: type: string minLength: 1 required: - key responses: "200": description: Successful response content: application/json: schema: type: object properties: deleted: type: boolean required: - deleted additionalProperties: false /v1/cache/get: post: operationId: cache_get_post summary: Get a cache entry description: Retrieve a cached value by key. Returns null if not found. tags: - cache requestBody: required: true content: application/json: schema: type: object properties: key: type: string minLength: 1 required: - key responses: "200": description: Successful response content: application/json: schema: anyOf: - type: object properties: data: {} required: - data additionalProperties: false - type: "null" /v1/cache/set: post: operationId: cache_set_post summary: Set a cache entry description: Store a value in the daemon's in-memory cache, optionally with a TTL. tags: - cache requestBody: required: true content: application/json: schema: type: object properties: data: {} key: type: string minLength: 1 ttl_ms: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - data responses: "200": description: Successful response content: application/json: schema: type: object properties: key: type: string required: - key additionalProperties: false /v1/calls/{callSessionId}: get: operationId: calls_by_callSessionId_get summary: Get call status description: Return the current status and details of a call session. tags: - calls parameters: - name: callSessionId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: callSessionId: type: string conversationId: type: string status: type: string toNumber: type: string fromNumber: type: string provider: type: string providerCallSid: type: string task: type: string startedAt: anyOf: - type: string - type: "null" endedAt: anyOf: - type: string - type: "null" lastError: anyOf: - type: string - type: "null" pendingQuestion: anyOf: - type: object properties: {} additionalProperties: {} - type: "null" createdAt: type: string updatedAt: type: string required: - callSessionId - conversationId - status - toNumber - fromNumber - provider - providerCallSid - task - startedAt - endedAt - lastError - pendingQuestion - createdAt - updatedAt additionalProperties: false /v1/calls/{callSessionId}/answer: post: operationId: calls_by_callSessionId_answer_post summary: Answer a pending call question description: Provide an answer to a pending question during an active call. tags: - calls parameters: - name: callSessionId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: answer: type: string description: Answer text pendingQuestionId: type: string description: ID of the pending question required: - answer responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean questionId: type: string required: - ok - questionId additionalProperties: false /v1/calls/{callSessionId}/cancel: post: operationId: calls_by_callSessionId_cancel_post summary: Cancel a call description: Cancel an active or pending call. tags: - calls parameters: - name: callSessionId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: reason: type: string description: Cancellation reason responses: "200": description: Successful response content: application/json: schema: type: object properties: callSessionId: type: string status: type: string required: - callSessionId - status additionalProperties: false /v1/calls/{callSessionId}/instruction: post: operationId: calls_by_callSessionId_instruction_post summary: Relay instruction to active call description: Send a real-time instruction to an active call. tags: - calls parameters: - name: callSessionId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: instruction: type: string description: Instruction text to relay required: - instruction responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/calls/start: post: operationId: calls_start_post summary: Start a call description: Initiate a new outbound phone call. Supports idempotency keys to prevent duplicate calls. tags: - calls requestBody: required: true content: application/json: schema: type: object properties: phoneNumber: type: string description: Phone number to call task: type: string description: Task description for the call context: type: string description: Additional context for the call conversationId: type: string description: Conversation to associate with callerIdentityMode: type: string description: "Caller identity: 'assistant_number' or 'user_number'" idempotencyKey: type: string description: Idempotency key to prevent duplicate calls required: - conversationId responses: "201": description: Successful response content: application/json: schema: type: object properties: callSessionId: type: string callSid: type: string status: type: string toNumber: type: string fromNumber: type: string callerIdentityMode: type: string required: - callSessionId - callSid - status - toNumber - fromNumber - callerIdentityMode additionalProperties: false /v1/channel-verification-sessions: delete: operationId: channelverificationsessions_delete summary: Cancel verification sessions description: Cancel all active inbound and outbound verification sessions. tags: - channel-verification requestBody: required: true content: application/json: schema: type: object properties: channel: type: string required: - channel responses: "200": description: Successful response post: operationId: channelverificationsessions_post summary: Create verification session description: Create a channel verification session (inbound challenge, outbound, or trusted contact). tags: - channel-verification requestBody: required: true content: application/json: schema: type: object properties: channel: type: string description: Channel ID destination: type: string description: Outbound destination rebind: type: boolean conversationId: type: string originConversationId: type: string purpose: type: string description: guardian or trusted_contact contactChannelId: type: string required: - channel - destination - rebind - conversationId - originConversationId - purpose - contactChannelId responses: "200": description: Successful response /v1/channel-verification-sessions/resend: post: operationId: channelverificationsessions_resend_post summary: Resend verification code description: Resend the outbound verification code. tags: - channel-verification requestBody: required: true content: application/json: schema: type: object properties: channel: type: string originConversationId: type: string required: - channel responses: "200": description: Successful response /v1/channel-verification-sessions/revoke: post: operationId: channelverificationsessions_revoke_post summary: Revoke verification binding description: Cancel all sessions and revoke the guardian binding. tags: - channel-verification requestBody: required: true content: application/json: schema: type: object properties: channel: type: string required: - channel responses: "200": description: Successful response /v1/channel-verification-sessions/status: get: operationId: channelverificationsessions_status_get summary: Get verification status description: Check guardian binding and verification session status. tags: - channel-verification parameters: - name: channel in: query required: false schema: type: string description: Optional channel ID filter responses: "200": description: Successful response /v1/channels/available: get: operationId: channels_available_get summary: Get available channels description: Return the channels this assistant can surface to clients, with display metadata (label, icon, verification capability, setup copy). A fixed base list plus `email` when an inbox is registered, plus the channels installed plugins bring by declaring ingress routes. Each carries a `source` saying which of those it is. tags: - channels responses: "200": description: Successful response content: application/json: schema: type: object properties: channels: type: array items: type: object properties: id: type: string source: type: string description: "`default` for a channel the assistant ships, `plugin:` for one an installed plugin brings" label: type: string subtitle: type: string icon: type: string supportsVerification: type: boolean setupMessages: type: object properties: guardian: type: string contact: type: string required: - guardian - contact additionalProperties: false required: - id - source - label - subtitle - icon - supportsVerification - setupMessages additionalProperties: false description: "Available channels in display order: the ones the assistant ships, then the ones installed plugins bring by declaring ingress routes. `source` distinguishes them." required: - channels additionalProperties: false /v1/channels/conversation: delete: operationId: channels_conversation_delete summary: Delete channel conversation description: Delete a conversation by channel source. tags: - channels responses: "200": description: Successful response /v1/channels/dead-letters: get: operationId: channels_deadletters_get summary: List dead letters description: Return undeliverable channel messages. tags: - channels responses: "200": description: Successful response /v1/channels/delivery-ack: post: operationId: channels_deliveryack_post summary: Acknowledge channel delivery description: Acknowledge delivery of a channel message. tags: - channels responses: "204": description: Successful response /v1/channels/inbound: post: operationId: channels_inbound_post summary: Process inbound channel message description: Receive an inbound message from a channel integration. tags: - channels requestBody: required: true content: application/json: schema: type: object properties: sourceChannel: type: string interface: type: string conversationExternalId: type: string externalMessageId: type: string content: type: string isEdit: type: boolean callbackQueryId: type: string callbackData: type: string actorDisplayName: type: string actorExternalId: type: string actorUsername: type: string sourceMetadata: type: object properties: updateId: type: string messageId: type: string chatType: type: string threadId: type: string channelName: type: string languageCode: type: string isBot: type: boolean timezone: type: string timezoneLabel: type: string timezoneOffsetSeconds: type: number isStranger: type: boolean isRestricted: type: boolean hints: type: array items: type: string uxBrief: type: string clientTimezone: type: string commandIntent: type: object properties: type: type: string payload: type: string required: - type slackBotMentioned: type: boolean account: type: string actorTeamId: type: string appContext: type: object properties: entities: type: array items: type: object properties: type: type: string value: anyOf: - type: string - type: object properties: messageTs: type: string channelId: type: string teamId: type: string enterpriseId: type: string required: - type - value required: - entities admissionPolicy: type: string enum: - no_one - guardian_only - trusted_contacts - any_contact - strangers trustVerdict: type: object properties: trustClass: type: string enum: - guardian - trusted_contact - unverified_contact - unknown canonicalSenderId: anyOf: - type: string - type: "null" resolutionFailed: type: boolean guardianExternalUserId: type: string guardianDeliveryChatId: anyOf: - type: string - type: "null" guardianPrincipalId: type: string guardianDisplayName: type: string contactId: type: string channelId: type: string type: type: string address: type: string externalChatId: anyOf: - type: string - type: "null" status: type: string policy: type: string verifiedAt: anyOf: - type: number - type: "null" memberDisplayName: type: string interactionCount: type: number hasInterceptableVerificationSession: type: boolean required: - trustClass - canonicalSenderId emailProvider: type: string emailSubject: type: string emailRecipient: type: string emailInReplyTo: type: string emailReferences: type: string additionalProperties: {} attachmentIds: type: array items: type: string replyCallbackUrl: type: string required: - sourceChannel - interface - conversationExternalId - externalMessageId - content - actorExternalId responses: "200": description: Successful response /v1/channels/readiness: get: operationId: channels_readiness_get summary: Get channel readiness description: Return readiness snapshots for one or all channels. tags: - channels parameters: - name: channel in: query required: false schema: type: string description: Optional channel ID filter - name: includeRemote in: query required: false schema: type: string description: Include remote checks (default true) responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean snapshots: type: array items: type: object properties: channel: type: string enum: - telegram - phone - vellum - whatsapp - slack - email - platform - a2a - discord - plugin ready: type: boolean setupStatus: anyOf: - type: string - type: "null" checkedAt: anyOf: - type: number - type: "null" stale: type: boolean reasons: type: array items: type: string localChecks: type: array items: type: object properties: name: type: string passed: type: boolean message: anyOf: - type: string - type: "null" required: - name - passed additionalProperties: false remoteChecks: type: array items: type: object properties: name: type: string passed: type: boolean message: anyOf: - type: string - type: "null" required: - name - passed additionalProperties: false channelHandle: anyOf: - type: string - type: "null" required: - channel - ready additionalProperties: false description: Channel readiness snapshots required: - success - snapshots additionalProperties: false /v1/channels/readiness/refresh: post: operationId: channels_readiness_refresh_post summary: Refresh channel readiness description: Invalidate cache and re-evaluate channel readiness. tags: - channels requestBody: required: true content: application/json: schema: type: object properties: channel: description: Optional channel ID to refresh type: string enum: - telegram - phone - vellum - whatsapp - slack - email - platform - a2a - discord - plugin includeRemote: description: Include remote checks (default true) type: boolean responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean snapshots: type: array items: type: object properties: channel: type: string enum: - telegram - phone - vellum - whatsapp - slack - email - platform - a2a - discord - plugin ready: type: boolean setupStatus: anyOf: - type: string - type: "null" checkedAt: anyOf: - type: number - type: "null" stale: type: boolean reasons: type: array items: type: string localChecks: type: array items: type: object properties: name: type: string passed: type: boolean message: anyOf: - type: string - type: "null" required: - name - passed additionalProperties: false remoteChecks: type: array items: type: object properties: name: type: string passed: type: boolean message: anyOf: - type: string - type: "null" required: - name - passed additionalProperties: false channelHandle: anyOf: - type: string - type: "null" required: - channel - ready additionalProperties: false description: Refreshed readiness snapshots required: - success - snapshots additionalProperties: false /v1/channels/replay: post: operationId: channels_replay_post summary: Replay dead letters description: Retry delivery of dead-letter messages. tags: - channels responses: "200": description: Successful response /v1/clients: get: operationId: clients_get summary: List connected clients description: Return all connected clients, optionally filtered by capability. tags: - clients parameters: - name: capability in: query required: false schema: type: string description: Filter clients by a specific capability. responses: "200": description: Successful response content: application/json: schema: type: object properties: clients: type: array items: type: object properties: {} additionalProperties: {} required: - clients additionalProperties: false /v1/clients/disconnect: post: operationId: clients_disconnect_post summary: Force-disconnect a client description: Dispose all hub subscribers for the given clientId, forcibly closing their SSE streams. tags: - clients requestBody: required: true content: application/json: schema: type: object properties: clientId: type: string description: The client UUID to disconnect. required: - clientId responses: "200": description: Successful response content: application/json: schema: type: object properties: disconnected: type: number description: Number of disposed subscribers. required: - disconnected additionalProperties: false /v1/clients/presence: post: operationId: clients_presence_post summary: Report desktop presence description: Record the desktop presence state reported by the client identified by the X-Vellum-Client-Id header. tags: - clients requestBody: required: true content: application/json: schema: type: object properties: state: type: string enum: - active - idle - away description: Reported desktop presence state. required: - state responses: "200": description: Successful response content: application/json: schema: type: object properties: recorded: type: boolean description: Whether a connected client matched the reporting clientId. required: - recorded additionalProperties: false /v1/clients/web-presence: post: operationId: clients_webpresence_post summary: Report web tab visibility and focused conversation description: Record the visibility and focused conversation reported by the web client identified by the X-Vellum-Client-Id header. tags: - clients requestBody: required: true content: application/json: schema: type: object properties: visible: type: boolean description: Whether the reporting tab is currently visible. focusedConversationId: anyOf: - type: string - type: "null" description: The conversation currently focused (chat composer on screen) in the tab, or null. required: - visible - focusedConversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: recorded: type: boolean description: Whether a connected client matched the reporting clientId. required: - recorded additionalProperties: false /v1/config: get: operationId: config_get summary: Get full config description: Return the raw settings.json configuration object. tags: - config responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ConfigGetResponse" patch: operationId: config_patch summary: Patch config description: Deep-merge a partial JSON object into the settings.json configuration. tags: - config requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ConfigPatchRequest" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ConfigGetResponse" /v1/config/allowlist/validate: get: operationId: config_allowlist_validate_get summary: Validate secret-allowlist.json regex patterns description: "Compile each regex pattern in secret-allowlist.json and return any syntax errors. Returns { exists: false } if no file is present." tags: - config responses: "200": description: Successful response /v1/config/embeddings: get: operationId: config_embeddings_get summary: Get embedding config description: Return the active embedding provider, model, and available options. tags: - config responses: "200": description: Successful response put: operationId: config_embeddings_put summary: Set embedding config description: Change the embedding provider and optionally model. tags: - config requestBody: required: true content: application/json: schema: type: object properties: provider: type: string model: type: string required: - provider responses: "200": description: Successful response /v1/config/llm/call-sites: get: operationId: config_llm_callsites_get summary: List LLM call sites description: Returns the full catalog of LLM call sites with display names, descriptions, and domain groupings. Used by clients to render the per-call-site override settings UI. tags: - config responses: "200": description: Successful response content: application/json: schema: type: object properties: domains: type: array items: type: object properties: id: type: string displayName: type: string required: - id - displayName additionalProperties: false callSites: type: array items: type: object properties: id: type: string displayName: type: string description: type: string domain: type: string defaultProfile: type: string shippedDefaultProfile: type: string required: - id - displayName - description - domain additionalProperties: false required: - domains - callSites additionalProperties: false /v1/config/llm/default-provider: get: operationId: config_llm_defaultprovider_get summary: Get the default provider and its availability description: Returns `llm.defaultProvider`, the connection name it resolves to, and whether that connection is currently usable (connection exists, credential stored, Vellum authenticated). Availability is informational — a broken default is a valid persisted state that surfaces explainable errors at resolution time. tags: - config responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/DefaultProviderStatus" put: operationId: config_llm_defaultprovider_put summary: Set the default provider description: Replaces `llm.defaultProvider`. Strict-validates the body (unlike the generic config write paths, which silently drop invalid values). Does not require the referenced connection to exist — a dangling name is allowed by design and reported via the availability status. tags: - config requestBody: required: true content: application/json: schema: type: object properties: provider: type: string enum: - anthropic - openai - gemini - fireworks - openrouter - chatgpt - vellum - together - vercel-ai-gateway - minimax - atlascloud - baseten - poolside connectionName: type: string minLength: 1 required: - provider responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/DefaultProviderStatus" /v1/config/llm/profiles: get: operationId: config_llm_profiles_get summary: List defined LLM profiles description: Returns the sorted list of profile names defined in `llm.profiles` plus the workspace-wide active profile. Used to populate per-call profile dropdowns (e.g. memory router playground) without requiring the caller to type profile names. tags: - config responses: "200": description: Successful response content: application/json: schema: type: object properties: profiles: type: array items: type: string activeProfile: anyOf: - type: string - type: "null" required: - profiles - activeProfile additionalProperties: false /v1/config/llm/profiles/{name}: put: operationId: config_llm_profiles_by_name_put summary: Replace an inference profile description: Replace the settings-UI-managed leaves of a single llm.profiles entry while preserving non-UI leaves. tags: - config parameters: - name: name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: provider: $ref: "#/components/schemas/LLMProvider" model: type: string minLength: 1 maxTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 effort: type: string enum: - none - low - medium - high - xhigh - max speed: type: string enum: - standard - fast verbosity: type: string enum: - low - medium - high temperature: anyOf: - type: number minimum: 0 maximum: 2 - type: "null" topP: anyOf: - type: number minimum: 0 maximum: 1 - type: "null" thinking: type: object properties: enabled: type: boolean streamThinking: type: boolean level: type: string enum: - minimal - low - medium - high contextWindow: type: object properties: enabled: type: boolean maxInputTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 targetBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 compactThreshold: type: number exclusiveMinimum: 0 maximum: 1 summaryBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 overflowRecovery: type: object properties: enabled: type: boolean safetyMarginRatio: type: number exclusiveMinimum: 0 exclusiveMaximum: 1 maxAttempts: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 interactiveLatestTurnCompression: type: string enum: - truncate - summarize - drop nonInteractiveLatestTurnCompression: type: string enum: - truncate - summarize - drop openrouter: type: object properties: only: type: array items: type: string minLength: 1 logitBias: type: string enum: - suppress-cjk disableCache: type: boolean source: type: string enum: - managed - user label: anyOf: - type: string minLength: 1 - type: "null" description: type: string provider_connection: type: string minLength: 1 status: anyOf: - $ref: "#/components/schemas/ProfileStatus" - type: "null" mix: minItems: 2 type: array items: type: object properties: profile: type: string minLength: 1 weight: type: number exclusiveMinimum: 0 required: - profile - weight responses: "200": description: Successful response /v1/config/platform: get: operationId: config_platform_get summary: Get platform config description: Return the platform base URL configuration. tags: - config responses: "200": description: Successful response content: application/json: schema: type: object properties: baseUrl: type: string success: type: boolean required: - baseUrl - success additionalProperties: false put: operationId: config_platform_put summary: Update platform config description: Set the platform base URL. tags: - config requestBody: required: true content: application/json: schema: type: object properties: baseUrl: type: string required: - baseUrl responses: "200": description: Successful response /v1/config/schema: get: operationId: config_schema_get summary: Get config JSON Schema description: Return the JSON Schema for the assistant config, optionally scoped to a dotted-path sub-schema (e.g. ?path=calls). tags: - config parameters: - name: path in: query required: false schema: type: string description: Optional dotted path to a config sub-key responses: "200": description: Successful response /v1/config/set: post: operationId: config_set_post summary: Set a single config path description: Assign a value at a dotted config path with direct-replacement semantics (preserves explicit null, replaces object subtrees instead of merging). Used by the `assistant config set ` CLI command. tags: - config responses: "200": description: Successful response /v1/confirm: post: operationId: confirm_post summary: Resolve a pending confirmation description: Approve or deny a pending tool confirmation by requestId. tags: - approvals requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string description: Pending interaction request ID decision: type: string description: "One of: allow, deny" selectedPattern: type: string description: Allowlist pattern for persistent decisions selectedScope: type: string description: Scope for persistent decisions required: - requestId - decision responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false /v1/consolidation/config: get: operationId: consolidation_config_get summary: Get consolidation config description: Return the current memory v2 consolidation schedule configuration. tags: - consolidation responses: "200": description: Successful response content: application/json: schema: type: object properties: available: type: boolean enabled: type: boolean intervalMs: type: number nextRunAt: anyOf: - type: number - type: "null" lastRunAt: anyOf: - type: number - type: "null" success: type: boolean required: - available - enabled - intervalMs - nextRunAt - lastRunAt - success additionalProperties: false /v1/consolidation/run-now: post: operationId: consolidation_runnow_post summary: Run consolidation now description: Enqueue an immediate memory v2 consolidation job. Returns once the job is queued; the job itself runs through the memory jobs worker. tags: - consolidation responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean ran: type: boolean description: Whether a job was enqueued jobId: anyOf: - type: string - type: "null" required: - success - ran - jobId additionalProperties: false /v1/consolidation/runs: get: operationId: consolidation_runs_get summary: List consolidation runs description: "Return recent memory v2 consolidation conversations as run records. Each consolidation dispatch creates exactly one background conversation tagged with `source = memory_v2_consolidation`; that conversation IS the run. Synthetic fields: `id` mirrors `conversationId` (no separate run row exists), `scheduledFor` and `startedAt` both equal `conversation.createdAt` (no separate schedule timestamp), `finishedAt` is the `createdAt` of the latest assistant message in the conversation (NOT `conversation.lastMessageAt`, which the kickoff user prompt bumps before the agent runs). `status` is `'ok'` when the conversation has at least one assistant message — i.e. positive evidence the agent emitted output — otherwise `'running'`. This is a weaker signal than heartbeat's `'ok'`: without a dedicated runs table we cannot distinguish 'ran cleanly' from 'crashed after emitting at least one assistant message'. `skipReason` and `error` are always null — skipped runs (lock held, disabled, empty buffer) never create a conversation, and run failure detail is not stored on the conversation row. Shape mirrors `heartbeat/runs` so the schedules settings UI can reuse its run-row component." tags: - consolidation parameters: - name: limit in: query required: false schema: type: integer description: Max runs to return (default 20, max 100) - name: before in: query required: false schema: type: integer description: "Cursor for older runs: pass the previous page's `nextCursor` to return runs strictly older than it." responses: "200": description: Successful response content: application/json: schema: type: object properties: runs: type: array items: type: object properties: id: type: string scheduledFor: type: number startedAt: anyOf: - type: number - type: "null" finishedAt: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" status: type: string enum: - ok - running skipReason: anyOf: - type: string - type: "null" error: anyOf: - type: string - type: "null" conversationId: anyOf: - type: string - type: "null" conversationExists: type: boolean conversationArchivedAt: anyOf: - type: number - type: "null" estimatedCostUsd: type: number createdAt: type: number required: - id - scheduledFor - startedAt - finishedAt - durationMs - status - skipReason - error - conversationId - conversationExists - conversationArchivedAt - estimatedCostUsd - createdAt additionalProperties: false description: Consolidation run records nextCursor: anyOf: - type: number - type: "null" description: Cursor for fetching older runs (pass as `before`); null when no older runs exist required: - runs - nextCursor additionalProperties: false /v1/contact-channels/{contactChannelId}: patch: operationId: contactchannels_by_contactChannelId_patch summary: Update a contact channel description: Update status, policy, or reason on a contact's channel. tags: - contacts parameters: - name: contactChannelId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: status: description: Channel status type: string policy: description: Channel policy type: string reason: description: Reason for the change type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean contact: description: Updated contact (if applicable) type: object properties: id: type: string displayName: type: string role: type: string enum: - guardian - contact notes: anyOf: - type: string - type: "null" contactType: type: string enum: - human - assistant lastInteraction: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number channels: type: array items: type: object properties: id: type: string contactId: type: string type: type: string address: type: string isPrimary: type: boolean externalUserId: anyOf: - type: string - type: "null" status: type: string policy: type: string verifiedAt: anyOf: - type: number - type: "null" verifiedVia: anyOf: - type: string - type: "null" lastSeenAt: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" lastInteraction: anyOf: - type: number - type: "null" revokedReason: anyOf: - type: string - type: "null" blockedReason: anyOf: - type: string - type: "null" required: - id - contactId - type - address - isPrimary - externalUserId - lastSeenAt - interactionCount - lastInteraction additionalProperties: false required: - id - displayName - role - contactType - interactionCount - createdAt - updatedAt - channels additionalProperties: false required: - ok additionalProperties: false /v1/contacts: get: operationId: contacts_get summary: List contacts description: Return all contacts, optionally filtered by type or channel status. tags: - contacts parameters: - name: limit in: query required: false schema: type: integer description: Max contacts to return (default 50) - name: role in: query required: false schema: type: string description: Filter by role (e.g. guardian) - name: contactType in: query required: false schema: type: string description: Filter by contact type (human or assistant) - name: query in: query required: false schema: type: string description: Full-text search query - name: channelAddress in: query required: false schema: type: string description: Filter by channel address - name: channelType in: query required: false schema: type: string description: Filter by channel type responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean contacts: type: array items: type: object properties: id: type: string displayName: type: string role: type: string enum: - guardian - contact notes: anyOf: - type: string - type: "null" contactType: type: string enum: - human - assistant lastInteraction: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number channels: type: array items: type: object properties: id: type: string contactId: type: string type: type: string address: type: string isPrimary: type: boolean externalUserId: anyOf: - type: string - type: "null" status: type: string policy: type: string verifiedAt: anyOf: - type: number - type: "null" verifiedVia: anyOf: - type: string - type: "null" lastSeenAt: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" lastInteraction: anyOf: - type: number - type: "null" revokedReason: anyOf: - type: string - type: "null" blockedReason: anyOf: - type: string - type: "null" required: - id - contactId - type - address - isPrimary - externalUserId - lastSeenAt - interactionCount - lastInteraction additionalProperties: false required: - id - displayName - role - contactType - interactionCount - createdAt - updatedAt - channels additionalProperties: false description: Contact objects with channels and metadata required: - ok - contacts additionalProperties: false /v1/contacts/{id}: get: operationId: contacts_by_id_get summary: Get a contact description: Return a single contact with its channels and assistant metadata. tags: - contacts parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean contact: type: object properties: id: type: string displayName: type: string role: type: string enum: - guardian - contact notes: anyOf: - type: string - type: "null" contactType: type: string enum: - human - assistant lastInteraction: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number channels: type: array items: type: object properties: id: type: string contactId: type: string type: type: string address: type: string isPrimary: type: boolean externalUserId: anyOf: - type: string - type: "null" status: type: string policy: type: string verifiedAt: anyOf: - type: number - type: "null" verifiedVia: anyOf: - type: string - type: "null" lastSeenAt: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" lastInteraction: anyOf: - type: number - type: "null" revokedReason: anyOf: - type: string - type: "null" blockedReason: anyOf: - type: string - type: "null" required: - id - contactId - type - address - isPrimary - externalUserId - lastSeenAt - interactionCount - lastInteraction additionalProperties: false required: - id - displayName - role - contactType - interactionCount - createdAt - updatedAt - channels additionalProperties: false assistantMetadata: description: Assistant-side metadata type: object properties: contactId: type: string species: type: string metadata: anyOf: - type: object properties: {} additionalProperties: {} - type: "null" required: - contactId - species - metadata additionalProperties: false required: - ok - contact additionalProperties: false /v1/contacts/invites: get: operationId: contacts_invites_get summary: List invites description: Return all invites, optionally filtered by sourceChannel or status. tags: - contacts parameters: - name: sourceChannel in: query required: false schema: type: string description: Filter by source channel - name: status in: query required: false schema: type: string description: Filter by invite status responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean invites: type: array items: {} description: Invite objects required: - ok - invites additionalProperties: false post: operationId: contacts_invites_post summary: Create an invite description: Create a new invite. Supports voice invites when sourceChannel is "phone". tags: - contacts requestBody: required: true content: application/json: schema: type: object properties: contactId: type: string description: Contact to invite sourceChannel: type: string description: Source channel (e.g. phone) note: type: string description: Optional note maxUses: type: number description: Max redemptions expiresInMs: type: number description: Expiry duration in ms expectedExternalUserId: type: string description: Expected user ID (E.164 for phone) sourceConversationId: type: string description: Conversation the invite was created from (opaque) required: - contactId responses: "201": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean invite: type: object properties: {} additionalProperties: {} description: Created invite rawToken: description: One-time raw invite token (returned at creation only) type: string required: - ok - invite additionalProperties: false "400": description: Invalid invite parameters /v1/contacts/invites/{id}: delete: operationId: contacts_invites_by_id_delete summary: Revoke an invite description: Revoke an invite by ID. tags: - contacts parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response "404": description: Invite not found /v1/contacts/invites/{id}/call: post: operationId: contacts_invites_by_id_call_post summary: Trigger invite call description: "Trigger an outbound call for a phone invite. Gateway-only: the gateway validates its canonical invite row and supplies the resolved call fields in the body." tags: - contacts parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: phoneNumber: type: string description: E.164 number the invite call dials (invite's bound caller) friendName: description: Invitee display name for the call greeting anyOf: - type: string - type: "null" guardianName: description: Guardian display label recorded on the invite anyOf: - type: string - type: "null" required: - phoneNumber responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean callSid: type: string description: Call SID from the provider required: - ok - callSid additionalProperties: false "400": description: Invite not eligible for outbound call /v1/contacts/invites/redeem: post: operationId: contacts_invites_redeem_post summary: Redeem an invite description: Redeem an invite by token or voice code. tags: - contacts requestBody: required: true content: application/json: schema: type: object properties: token: description: Invite token (token-based redemption) type: string code: description: Voice code (voice-code redemption) type: string callerExternalUserId: description: Caller E.164 phone (voice-code) type: string externalUserId: description: External user ID (token-based) type: string externalChatId: description: External chat ID (token-based) type: string sourceChannel: description: Source channel (token-based) type: string displayName: description: Sender display name (token-based) type: string username: description: Sender username (token-based) type: string assistantId: description: Assistant ID (voice-code) type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean invite: type: object properties: {} additionalProperties: {} description: Redeemed invite (token path) type: type: string description: Redemption type (voice path) memberId: type: string description: Member ID (voice path) required: - ok - invite - type - memberId additionalProperties: false "400": description: Invalid redemption parameters or failed redemption /v1/contacts/merge: post: operationId: contacts_merge_post summary: Merge two contacts description: Merge two contacts, keeping one and absorbing the other. tags: - contacts requestBody: required: true content: application/json: schema: type: object properties: keepId: type: string description: ID of the contact to keep mergeId: type: string description: ID of the contact to merge into the kept one required: - keepId - mergeId responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean contact: description: Merged (surviving) contact type: object properties: id: type: string displayName: type: string role: type: string enum: - guardian - contact notes: anyOf: - type: string - type: "null" contactType: type: string enum: - human - assistant lastInteraction: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number channels: type: array items: type: object properties: id: type: string contactId: type: string type: type: string address: type: string isPrimary: type: boolean externalUserId: anyOf: - type: string - type: "null" status: type: string policy: type: string verifiedAt: anyOf: - type: number - type: "null" verifiedVia: anyOf: - type: string - type: "null" lastSeenAt: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" lastInteraction: anyOf: - type: number - type: "null" revokedReason: anyOf: - type: string - type: "null" blockedReason: anyOf: - type: string - type: "null" required: - id - contactId - type - address - isPrimary - externalUserId - lastSeenAt - interactionCount - lastInteraction additionalProperties: false required: - id - displayName - role - contactType - interactionCount - createdAt - updatedAt - channels additionalProperties: false required: - ok additionalProperties: false /v1/contacts/prompt: post: operationId: contacts_prompt_post summary: Prompt user to register a contact channel description: Broadcasts a contact_request to connected clients, waits for the user to submit an address via the gateway. The gateway owns the contact write and notifies the daemon via resolve_contact_prompt IPC. tags: - contacts requestBody: required: true content: application/json: schema: type: object properties: channel: description: Suggested channel type hint (e.g. phone, email, telegram). Free text — not enforced. type: string placeholder: description: Placeholder text for the address input field. type: string defaultValue: description: Suggested address to pre-fill the input with (e.g. a known email). The user can edit it before submitting. type: string label: description: Display label shown in the prompt UI. type: string description: description: Longer description for the prompt UI. type: string role: default: unknown description: Intended role of the contact being registered. type: string enum: - guardian - trusted-contact - unknown responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean error: type: string contactId: type: string channelId: type: string channelType: type: string address: type: string required: - ok additionalProperties: false /v1/contacts/search: post: operationId: contacts_search_post summary: Search contacts description: Search contacts by query, channel address, or channel type. tags: - contacts requestBody: required: true content: application/json: schema: type: object properties: query: type: string channelAddress: type: string channelType: type: string limit: type: number responses: "200": description: Successful response content: application/json: schema: type: array items: type: object properties: id: type: string displayName: type: string role: type: string enum: - guardian - contact notes: anyOf: - type: string - type: "null" contactType: type: string enum: - human - assistant lastInteraction: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number channels: type: array items: type: object properties: id: type: string contactId: type: string type: type: string address: type: string isPrimary: type: boolean externalUserId: anyOf: - type: string - type: "null" status: type: string policy: type: string verifiedAt: anyOf: - type: number - type: "null" verifiedVia: anyOf: - type: string - type: "null" lastSeenAt: anyOf: - type: number - type: "null" interactionCount: anyOf: - type: number - type: "null" lastInteraction: anyOf: - type: number - type: "null" revokedReason: anyOf: - type: string - type: "null" blockedReason: anyOf: - type: string - type: "null" required: - id - contactId - type - address - isPrimary - externalUserId - lastSeenAt - interactionCount - lastInteraction additionalProperties: false required: - id - displayName - role - contactType - interactionCount - createdAt - updatedAt - channels additionalProperties: false /v1/content-source: post: operationId: contentsource_post summary: Validate and persist a content source URL tags: - content-source requestBody: required: true content: application/json: schema: type: object properties: url: type: string required: - url responses: "200": description: Successful response /v1/conversation-starters: get: operationId: conversationstarters_get summary: List conversation starters description: Return conversation starter chips, ordered for category diversity. tags: - conversation-starters parameters: - name: limit in: query required: false schema: type: integer description: Max starters to return (1–20, default 4) - name: offset in: query required: false schema: type: integer description: Pagination offset (default 0) responses: "200": description: Successful response content: application/json: schema: type: object properties: starters: type: array items: type: object properties: id: type: string label: type: string prompt: type: string category: anyOf: - type: string - type: "null" batch: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - label - prompt - category - batch additionalProperties: false description: Ordered list of starter chips total: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Total number of available starters status: type: string enum: - ready - refreshing - empty - generating description: "One of: ready, refreshing, empty, generating" required: - starters - total - status additionalProperties: false /v1/conversation-starters/{id}: delete: operationId: conversationstarters_by_id_delete summary: Delete conversation starter description: Remove a generated conversation starter chip from the current starter set. tags: - conversation-starters parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: deleted: type: boolean id: type: string required: - deleted - id additionalProperties: false "404": description: Conversation starter not found /v1/conversations: delete: operationId: conversations_delete summary: Clear all conversations description: Permanently delete ALL conversations, messages, and memory. tags: - conversations responses: "204": description: Successful response get: operationId: conversations_get summary: List conversations description: Paginated list of conversations with attention state and display metadata. tags: - conversations parameters: - name: limit in: query required: false schema: type: integer description: Maximum number of conversations to return (default 50). - name: offset in: query required: false schema: type: integer description: Number of conversations to skip (default 0). - name: conversationType in: query required: false schema: type: string enum: - background - scheduled description: Filter by conversation type. Pass "background" to list background and scheduled conversations together (the back-compat umbrella), or "scheduled" to list only scheduled conversations. - name: archiveStatus in: query required: false schema: type: string enum: - active - archived - all description: Filter by archive state. Defaults to "active" (non-archived rows only). Pass "archived" to list only archived rows (for the Archive page) or "all" to include both. - name: originChannel in: query required: false schema: type: string enum: - telegram - phone - vellum - whatsapp - slack - email - platform - a2a - discord - plugin description: Filter by origin channel. When provided, only conversations with this exact origin_channel value are returned. Omit to include all channels. - name: groupId in: query required: false schema: type: string description: Filter to a single group, so each sidebar section can load independently of the paginated list. Pass "system:all" for conversations in no group, "system:pinned" for the Pinned section, or a custom group id. A group-scoped request is recency-ordered like every list read (COALESCE(last_message_at, updated_at) descending) and never has pinned rows appended to it. Omit to span every group. - name: needsAttention in: query required: false schema: type: string enum: - "true" description: 'Pass "true" to return only conversations whose latest assistant message the user has not seen: the same predicate behind the unread count and the section index, so a client that keeps no complete conversation list can ask for exactly the rows its attention surfaces need. Composes with every other filter. Any value other than "true" is rejected. Omit to span every conversation.' - name: foregroundOnly in: query required: false schema: type: string enum: - "true" description: Pass "true" to return only user-facing foreground conversations, dropping the automated background and scheduled runs the standard listing admits when they are filed in a custom group (a surfaced run stays). This is the same predicate the unread count and the section index apply, so a client can ask for the newest conversation a user can open in one row instead of paging past runs it would skip. Composes with every other filter; a foreground-only first page never has pinned rows appended to it. Any value other than "true" is rejected. Omit to keep every visible row. responses: "200": description: Successful response content: application/json: schema: type: object properties: conversations: type: array items: type: object properties: id: type: string title: type: string createdAt: type: number updatedAt: type: number lastMessageAt: anyOf: - type: number - type: "null" conversationType: type: string enum: - standard - background - scheduled source: type: string scheduleJobId: type: string channelBinding: type: object properties: sourceChannel: type: string externalChatId: type: string externalChatName: type: string externalThreadId: type: string externalUserId: anyOf: - type: string - type: "null" displayName: anyOf: - type: string - type: "null" username: anyOf: - type: string - type: "null" slackThread: type: object properties: channelId: type: string threadTs: type: string link: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false required: - channelId - threadTs additionalProperties: false slackChannel: type: object properties: channelId: type: string name: type: string link: type: object properties: webUrl: type: string required: - webUrl additionalProperties: false required: - channelId additionalProperties: false sourceLink: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false required: - sourceChannel - externalChatId - externalUserId - displayName - username additionalProperties: false conversationOriginChannel: anyOf: - type: string enum: - telegram - phone - vellum - whatsapp - slack - email - platform - a2a - discord - plugin - type: "null" assistantAttention: type: object properties: hasUnseenLatestAssistantMessage: type: boolean latestAssistantMessageAt: type: number lastSeenAssistantMessageAt: type: number lastSeenConfidence: type: string enum: - explicit - inferred lastSeenSignalType: type: string enum: - macos_notification_view - macos_conversation_opened - ios_conversation_opened - web_bulk_mark_read - telegram_inbound_message - telegram_callback - slack_inbound_message - slack_callback required: - hasUnseenLatestAssistantMessage additionalProperties: false isPinned: type: boolean const: true displayOrder: anyOf: - type: number - type: "null" groupId: anyOf: - type: string - type: "null" forkParent: type: object properties: conversationId: type: string messageId: type: string title: type: string required: - conversationId - messageId - title additionalProperties: false historyOrphaned: type: boolean const: true archivedAt: type: number surfacedAt: type: number inferenceProfile: type: string enabledPlugins: anyOf: - type: array items: type: string - type: "null" isProcessing: type: boolean required: - id - title - createdAt - updatedAt - lastMessageAt - conversationType - source - groupId - isProcessing additionalProperties: false nextOffset: type: number hasMore: type: boolean groups: type: array items: type: object properties: id: type: string name: type: string sortPosition: type: number isSystemGroup: type: boolean required: - id - name - sortPosition - isSystemGroup additionalProperties: false required: - conversations - nextOffset - hasMore additionalProperties: false post: operationId: conversations_post summary: Create a conversation description: Create or get an existing conversation by key. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationKey: description: Optional external key. Echoed back in the response. Non-vellum channels (Telegram, WhatsApp) use this to scope to a logical channel thread; vellum-web clients can omit it and rely on the assistant-minted `id`. type: string conversationType: description: Conversation type for the new row. "background" keeps it out of the foreground list and the sidebar's Recents grouping, used by internal side-channel flows (onboarding research, persona/identity rewrites) that mint a throwaway thread the user should never see. "scheduled" is not accepted here; scheduled rows are owned by the schedule pipeline. type: string enum: - standard - background title: description: Explicit title for the conversation. When provided on creation, it is persisted as a user-set title (never overwritten by the auto-titler). Used by flows that mint a conversation up-front and don't want an auto-generated title. type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string description: Assistant-minted internal conversation id. The authoritative identifier for the conversation. conversationKey: type: string description: Echo of the optional external key supplied by the client. conversationType: type: string created: type: boolean required: - id - conversationKey - conversationType - created additionalProperties: false /v1/conversations/{conversationId}/slack-channel/resolve: post: operationId: conversations_by_conversationId_slackchannel_resolve_post summary: Resolve Slack channel name description: Resolve and persist a friendly Slack channel name for an external conversation binding. tags: - conversations - slack parameters: - name: conversationId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: channelId: type: string channelName: type: string cached: type: boolean resolved: type: boolean reason: type: string enum: - auth - dm - no_name - not_found - permission - rate_limit - slack_error required: - channelId - cached - resolved additionalProperties: false /v1/conversations/{id}: delete: operationId: conversations_by_id_delete summary: Delete a conversation description: Permanently delete a single conversation and its messages. tags: - conversations parameters: - name: id in: path required: true schema: type: string responses: "204": description: Successful response get: operationId: conversations_by_id_get summary: Get conversation detail description: Retrieve a single conversation with full metadata. Rows the listing hides by type (legacy private rows) are not found here either. tags: - conversations parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: conversation: type: object properties: id: type: string title: type: string createdAt: type: number updatedAt: type: number lastMessageAt: anyOf: - type: number - type: "null" conversationType: type: string enum: - standard - background - scheduled source: type: string scheduleJobId: type: string channelBinding: type: object properties: sourceChannel: type: string externalChatId: type: string externalChatName: type: string externalThreadId: type: string externalUserId: anyOf: - type: string - type: "null" displayName: anyOf: - type: string - type: "null" username: anyOf: - type: string - type: "null" slackThread: type: object properties: channelId: type: string threadTs: type: string link: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false required: - channelId - threadTs additionalProperties: false slackChannel: type: object properties: channelId: type: string name: type: string link: type: object properties: webUrl: type: string required: - webUrl additionalProperties: false required: - channelId additionalProperties: false sourceLink: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false required: - sourceChannel - externalChatId - externalUserId - displayName - username additionalProperties: false conversationOriginChannel: anyOf: - type: string enum: - telegram - phone - vellum - whatsapp - slack - email - platform - a2a - discord - plugin - type: "null" assistantAttention: type: object properties: hasUnseenLatestAssistantMessage: type: boolean latestAssistantMessageAt: type: number lastSeenAssistantMessageAt: type: number lastSeenConfidence: type: string enum: - explicit - inferred lastSeenSignalType: type: string enum: - macos_notification_view - macos_conversation_opened - ios_conversation_opened - web_bulk_mark_read - telegram_inbound_message - telegram_callback - slack_inbound_message - slack_callback required: - hasUnseenLatestAssistantMessage additionalProperties: false isPinned: type: boolean const: true displayOrder: anyOf: - type: number - type: "null" groupId: anyOf: - type: string - type: "null" forkParent: type: object properties: conversationId: type: string messageId: type: string title: type: string required: - conversationId - messageId - title additionalProperties: false historyOrphaned: type: boolean const: true archivedAt: type: number surfacedAt: type: number inferenceProfile: type: string enabledPlugins: anyOf: - type: array items: type: string - type: "null" isProcessing: type: boolean required: - id - title - createdAt - updatedAt - lastMessageAt - conversationType - source - groupId - isProcessing additionalProperties: false required: - conversation additionalProperties: false /v1/conversations/{id}/archive: post: operationId: conversations_by_id_archive_post summary: Archive a conversation description: Move a conversation to the archived state. tags: - conversations parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean conversationId: type: string required: - ok - conversationId additionalProperties: false /v1/conversations/{id}/cancel: post: operationId: conversations_by_id_cancel_post summary: Cancel generation description: Abort the in-progress assistant response for a conversation. tags: - conversations parameters: - name: id in: path required: true schema: type: string responses: "202": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean cancelled: type: boolean conversationId: type: string required: - ok - cancelled - conversationId additionalProperties: false /v1/conversations/{id}/compaction: get: operationId: conversations_by_id_compaction_get summary: Get the compaction(s) attributed to an LLM call description: Return the chronological list of compactions attributed to the call identified by `callId` — those that ran strictly between the previous real (non-`compactionAgent`) LLM call and the selected call. Served from the first-class compaction log when `compactionLogs.destination = "clickhouse"` is configured, falling back to the legacy projection over `llm_request_logs` rows where `call_site = "compactionAgent"`. Usually empty or a single compaction; the recovery cascade can fire several before one call lands. Drives the Inspector's Compaction tab. tags: - conversations parameters: - name: id in: path required: true schema: type: string - name: callId in: query required: true schema: type: string description: ID of the selected LLM call from the rail. Defines the chronological cutoff for the attributed compactions. responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string events: type: array items: type: object properties: id: type: string createdAt: type: number trigger: anyOf: - type: string - type: "null" compacted: anyOf: - type: boolean - type: "null" summaryFailed: anyOf: - type: boolean - type: "null" skipReason: anyOf: - type: string - type: "null" contextTokensBefore: anyOf: - type: number - type: "null" contextTokensAfter: anyOf: - type: number - type: "null" messagesBefore: anyOf: - type: number - type: "null" messagesAfter: anyOf: - type: number - type: "null" compactedMessages: anyOf: - type: number - type: "null" preservedTailMessages: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" summaryModel: anyOf: - type: string - type: "null" summaryInputTokens: anyOf: - type: number - type: "null" summaryOutputTokens: anyOf: - type: number - type: "null" summaryText: anyOf: - type: string - type: "null" required: - id - createdAt - trigger - compacted - summaryFailed - skipReason - contextTokensBefore - contextTokensAfter - messagesBefore - messagesAfter - compactedMessages - preservedTailMessages - durationMs - summaryModel - summaryInputTokens - summaryOutputTokens - summaryText additionalProperties: false required: - conversationId - events additionalProperties: false "400": description: Returned when the callId is missing or refers to a call in a different conversation. "404": description: Returned when the conversation or the referenced LLM call does not exist. /v1/conversations/{id}/enabledplugins: put: operationId: conversations_by_id_enabledplugins_put summary: Set conversation enabled plugins description: Scope a single conversation to a subset of installed plugins (first-party defaults are always available). Pass null to clear the scope back to the default (all enabled plugins). tags: - conversations parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: enabledPlugins: anyOf: - type: array items: type: string - type: "null" required: - enabledPlugins responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string enabledPlugins: anyOf: - type: array items: type: string - type: "null" required: - conversationId - enabledPlugins additionalProperties: false /v1/conversations/{id}/inference-profile: put: operationId: conversations_by_id_inferenceprofile_put summary: Set conversation inference profile description: Override the LLM inference profile for a single conversation. Optionally supply ttlSeconds to create a session-backed (expiring) override. tags: - conversations parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: profile: anyOf: - type: string - type: "null" ttlSeconds: anyOf: - type: number exclusiveMinimum: 0 - type: "null" sessionId: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - profile responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string profile: anyOf: - type: string - type: "null" sessionId: anyOf: - type: string - type: "null" expiresAt: anyOf: - type: number - type: "null" ttlSeconds: anyOf: - type: number - type: "null" replaced: anyOf: - type: object properties: profile: anyOf: - type: string - type: "null" sessionId: anyOf: - type: string - type: "null" expiresAt: anyOf: - type: number - type: "null" required: - profile - sessionId - expiresAt additionalProperties: false - type: "null" required: - conversationId - profile - sessionId - expiresAt - replaced additionalProperties: false /v1/conversations/{id}/name: patch: operationId: conversations_by_id_name_patch summary: Rename a conversation description: Update the display name of a conversation. tags: - conversations parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string required: - name responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/conversations/{id}/playground/compact: post: operationId: conversations_by_id_playground_compact_post summary: Force compaction on a conversation (dev-only playground) tags: - playground parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response /v1/conversations/{id}/playground/compaction-state: get: operationId: conversations_by_id_playground_compactionstate_get summary: Read current compaction state for a conversation tags: - playground parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response /v1/conversations/{id}/playground/inject-compaction-failures: post: operationId: conversations_by_id_playground_injectcompactionfailures_post summary: Directly mutate compaction circuit-breaker state (dev-only playground) tags: - playground parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: consecutiveFailures: type: integer minimum: 0 maximum: 10 circuitOpenForMs: type: integer minimum: 0 maximum: 86400000 responses: "200": description: Successful response /v1/conversations/{id}/playground/reset-compaction-circuit: post: operationId: conversations_by_id_playground_resetcompactioncircuit_post summary: Clear compaction circuit-breaker state (dev-only playground) tags: - playground parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response /v1/conversations/{id}/retry: post: operationId: conversations_by_id_retry_post summary: Retry the last assistant turn description: Permanently discard the most recent assistant display turn (the assistant rows and tool-result rows after the last turn-starting user message), keep that user message, and re-run generation from it. Accepted immediately; the regenerated turn streams over SSE like a normal send. tags: - conversations parameters: - name: id in: path required: true schema: type: string responses: "202": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean const: true conversationId: type: string userMessageId: type: string description: The user message the turn is re-running from discardedCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Number of message rows discarded from the tail required: - accepted - conversationId - userMessageId - discardedCount additionalProperties: false "404": description: Conversation not found "409": description: The assistant is currently responding "422": description: No user message exists to retry from /v1/conversations/{id}/slash: post: operationId: conversations_by_id_slash_post summary: Resolve a local meta slash command description: "Run a local meta slash command (/clean, /status, /commands, /models) without starting a turn: no messages are persisted and no turn events are emitted. /clean also strips runtime injections from the history. Returns the text to render and, for /clean, the post-strip context usage." tags: - conversations parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: command: type: string description: The slash command text, e.g. `/clean` or `/status`. required: - command responses: "200": description: Successful response content: application/json: schema: type: object properties: kind: type: string enum: - clean - info text: type: string contextUsage: type: object properties: tokens: type: number maxTokens: anyOf: - type: number - type: "null" fillRatio: anyOf: - type: number - type: "null" required: - tokens - maxTokens - fillRatio additionalProperties: false required: - kind - text additionalProperties: false /v1/conversations/{id}/surface: post: operationId: conversations_by_id_surface_post summary: Surface a conversation into Recents description: Explicitly promote a background or scheduled conversation into the default conversation listing (the Recents sidebar grouping), or demote it with surfaced=false. Conversations are never surfaced automatically. tags: - conversations parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: surfaced: type: boolean description: true to surface the conversation into Recents, false to clear the promotion. required: - surfaced responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean conversationId: type: string surfacedAt: anyOf: - type: number - type: "null" description: Epoch-ms timestamp of the promotion, or null when cleared. required: - ok - conversationId - surfacedAt additionalProperties: false /v1/conversations/{id}/unarchive: post: operationId: conversations_by_id_unarchive_post summary: Unarchive a conversation description: Restore an archived conversation back to the default sidebar. tags: - conversations parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean conversationId: type: string required: - ok - conversationId additionalProperties: false /v1/conversations/{id}/undo: post: operationId: conversations_by_id_undo_post summary: Undo last message description: Remove the most recent user+assistant message pair from the conversation. tags: - conversations parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: removedCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 conversationId: type: string required: - removedCount - conversationId additionalProperties: false /v1/conversations/archive/bulk: post: operationId: conversations_archive_bulk_post summary: Bulk archive conversations description: Archive multiple conversations in one request. Emits a single sync invalidation for the entire batch. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationIds: minItems: 1 type: array items: type: string required: - conversationIds responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean archived: type: number required: - ok - archived additionalProperties: false /v1/conversations/attention: get: operationId: conversations_attention_get summary: List conversation attention states description: Return attention state (seen/unseen) for conversations, with pagination. tags: - conversations parameters: - name: state in: query required: false schema: type: string description: "Filter: seen, unseen, or all (default all)" - name: source in: query required: false schema: type: string description: Filter by source (default all) - name: channel in: query required: false schema: type: string description: Filter by source channel - name: limit in: query required: false schema: type: integer description: Max results (1–100, default 20) - name: before in: query required: false schema: type: number description: Cursor for pagination (timestamp) responses: "200": description: Successful response content: application/json: schema: type: object properties: conversations: type: array items: {} description: Attention state objects hasMore: type: boolean required: - conversations - hasMore additionalProperties: false /v1/conversations/cli/clear: post: operationId: conversations_cli_clear_post summary: Clear all conversations (CLI) description: "Tear down all active conversations and clear the database. Requires X-Confirm-Destructive: clear-all-conversations." tags: - conversations responses: "200": description: Successful response content: application/json: schema: type: object properties: cleared: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - cleared additionalProperties: false /v1/conversations/cli/create: post: operationId: conversations_cli_create_post summary: Create a conversation (CLI) description: Create a new conversation with an optional title and seeded messages. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: title: type: string messages: type: array items: type: object properties: role: type: string enum: - user - assistant content: type: string required: - role - content conversationType: type: string enum: - standard - background - scheduled responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string title: type: string conversationKey: type: string messagesInserted: type: integer minimum: 0 maximum: 9007199254740991 required: - id - title - conversationKey - messagesInserted additionalProperties: false /v1/conversations/cli/export: post: operationId: conversations_cli_export_post summary: Export a conversation (CLI) description: Export a conversation as markdown or JSON. Returns the formatted output string. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string format: default: md type: string enum: - md - json responses: "200": description: Successful response content: application/json: schema: type: object properties: output: type: string conversationId: type: string required: - output - conversationId additionalProperties: false /v1/conversations/cli/list: post: operationId: conversations_cli_list_post summary: List conversations (CLI) description: Simplified conversation list for CLI output — returns id, title, updatedAt. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: limit: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 includeArchived: type: boolean responses: "200": description: Successful response content: application/json: schema: type: object properties: conversations: type: array items: type: object properties: id: type: string title: anyOf: - type: string - type: "null" updatedAt: type: number isProcessing: type: boolean required: - id - title - updatedAt - isProcessing additionalProperties: false required: - conversations additionalProperties: false /v1/conversations/cli/slack/detach: post: operationId: conversations_cli_slack_detach_post summary: Detach the assistant from a Slack thread (CLI) description: Stops Slack active-thread listening for a Slack thread. The CLI resolves current conversation defaults. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 channelId: type: string minLength: 1 threadTs: type: string minLength: 1 responses: "200": description: Successful response content: application/json: schema: type: object properties: detached: type: boolean channelId: type: string threadTs: type: string source: type: string enum: - explicit - conversation_binding conversationId: type: string required: - detached - channelId - threadTs - source additionalProperties: false /v1/conversations/fork: post: operationId: conversations_fork_post summary: Fork a conversation description: Create a copy of a conversation, optionally truncated at a specific message. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string throughMessageId: type: string description: Truncate the fork at this message required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: conversation: type: object properties: id: type: string title: type: string createdAt: type: number updatedAt: type: number lastMessageAt: anyOf: - type: number - type: "null" conversationType: type: string enum: - standard - background - scheduled source: type: string scheduleJobId: type: string channelBinding: type: object properties: sourceChannel: type: string externalChatId: type: string externalChatName: type: string externalThreadId: type: string externalUserId: anyOf: - type: string - type: "null" displayName: anyOf: - type: string - type: "null" username: anyOf: - type: string - type: "null" slackThread: type: object properties: channelId: type: string threadTs: type: string link: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false required: - channelId - threadTs additionalProperties: false slackChannel: type: object properties: channelId: type: string name: type: string link: type: object properties: webUrl: type: string required: - webUrl additionalProperties: false required: - channelId additionalProperties: false sourceLink: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false required: - sourceChannel - externalChatId - externalUserId - displayName - username additionalProperties: false conversationOriginChannel: anyOf: - type: string enum: - telegram - phone - vellum - whatsapp - slack - email - platform - a2a - discord - plugin - type: "null" assistantAttention: type: object properties: hasUnseenLatestAssistantMessage: type: boolean latestAssistantMessageAt: type: number lastSeenAssistantMessageAt: type: number lastSeenConfidence: type: string enum: - explicit - inferred lastSeenSignalType: type: string enum: - macos_notification_view - macos_conversation_opened - ios_conversation_opened - web_bulk_mark_read - telegram_inbound_message - telegram_callback - slack_inbound_message - slack_callback required: - hasUnseenLatestAssistantMessage additionalProperties: false isPinned: type: boolean const: true displayOrder: anyOf: - type: number - type: "null" groupId: anyOf: - type: string - type: "null" forkParent: type: object properties: conversationId: type: string messageId: type: string title: type: string required: - conversationId - messageId - title additionalProperties: false historyOrphaned: type: boolean const: true archivedAt: type: number surfacedAt: type: number inferenceProfile: type: string enabledPlugins: anyOf: - type: array items: type: string - type: "null" isProcessing: type: boolean required: - id - title - createdAt - updatedAt - lastMessageAt - conversationType - source - groupId - isProcessing additionalProperties: false required: - conversation additionalProperties: false /v1/conversations/import: post: operationId: conversations_import_post summary: Import conversations description: Import conversations from a standard JSON payload. Created conversations record a provenance source of `import:` derived from the `sourceKey` prefix (e.g. `chatgpt:abc123` -> `import:chatgpt`), or `import:unknown` when no prefix is present. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversations: type: array items: type: object properties: sourceKey: type: string title: type: string createdAt: type: number updatedAt: type: number messages: type: array items: type: object properties: role: type: string content: anyOf: - type: string - type: array items: type: object properties: type: type: string text: type: string required: - type - text createdAt: type: number required: - role - content required: - title - messages required: - conversations responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean imported: type: number skipped: type: number messages: type: number errors: type: array items: type: object properties: index: type: number sourceKey: type: string error: type: string required: - index - error additionalProperties: false required: - ok - imported - skipped - messages - errors additionalProperties: false /v1/conversations/inference-profile-session: post: operationId: conversations_inferenceprofilesession_post summary: Open an inference-profile session description: Open (or replace) a session-backed inference-profile override for a conversation. Supports an optional TTL — omit for a sticky (non-expiring) override. A profile that provably cannot dispatch is rejected rather than pinned. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 profile: type: string minLength: 1 ttlSeconds: anyOf: - type: number exclusiveMinimum: 0 - type: "null" sessionId: type: string format: uuid pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ required: - conversationId - profile responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string profile: anyOf: - type: string - type: "null" sessionId: anyOf: - type: string - type: "null" expiresAt: anyOf: - type: number - type: "null" ttlSeconds: anyOf: - type: number - type: "null" replaced: anyOf: - type: object properties: profile: anyOf: - type: string - type: "null" sessionId: anyOf: - type: string - type: "null" expiresAt: anyOf: - type: number - type: "null" required: - profile - sessionId - expiresAt additionalProperties: false - type: "null" required: - conversationId - profile - sessionId - expiresAt - replaced additionalProperties: false /v1/conversations/inference-profile-session/close: post: operationId: conversations_inferenceprofilesession_close_post summary: Close an inference-profile session description: Close the active session-backed inference-profile override for a conversation. Only closes session-backed overrides; sticky overrides are left untouched. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string closed: anyOf: - type: object properties: profile: anyOf: - type: string - type: "null" sessionId: anyOf: - type: string - type: "null" required: - profile - sessionId additionalProperties: false - type: "null" noop: type: boolean required: - conversationId - closed - noop additionalProperties: false /v1/conversations/inference-profile-sessions: get: operationId: conversations_inferenceprofilesessions_get summary: List active inference-profile sessions description: List all active (non-expired) session-backed inference-profile overrides, optionally filtered by conversationId. tags: - conversations parameters: - name: conversationId in: query required: false schema: type: string description: Optional conversation ID filter responses: "200": description: Successful response content: application/json: schema: type: object properties: sessions: type: array items: type: object properties: conversationId: type: string conversationTitle: anyOf: - type: string - type: "null" profile: type: string sessionId: type: string expiresAt: type: number remainingSeconds: type: number required: - conversationId - conversationTitle - profile - sessionId - expiresAt - remainingSeconds additionalProperties: false required: - sessions additionalProperties: false /v1/conversations/llm-context: get: operationId: conversations_llmcontext_get summary: Get LLM context for a conversation description: Returns normalized LLM request/response logs for an entire conversation. tags: - conversations parameters: - name: conversationKey in: query required: false schema: type: string description: Stable external conversation key. - name: conversationId in: query required: false schema: type: string description: Internal conversation identifier. - name: view in: query required: false schema: type: string enum: - full - summary description: Response shape. 'summary' omits per-log request/response sections; defaults to 'full'. responses: "200": description: Successful response content: application/json: schema: type: object properties: messageId: anyOf: - type: string - type: "null" conversationKey: anyOf: - type: string - type: "null" conversationId: anyOf: - type: string - type: "null" conversationKind: type: string conversationTotalEstimatedCostUsd: anyOf: - type: number - type: "null" logs: type: array items: type: object properties: id: type: string createdAt: type: number requestPayload: type: "null" responsePayload: type: "null" provider: anyOf: - type: string - type: "null" summary: anyOf: - type: object properties: provider: anyOf: - type: string - type: "null" model: anyOf: - type: string - type: "null" status: anyOf: - type: string - type: "null" inputTokens: anyOf: - type: number - type: "null" outputTokens: anyOf: - type: number - type: "null" cacheCreationInputTokens: anyOf: - type: number - type: "null" cacheReadInputTokens: anyOf: - type: number - type: "null" stopReason: anyOf: - type: string - type: "null" requestMessageCount: anyOf: - type: number - type: "null" requestToolCount: anyOf: - type: number - type: "null" responseMessageCount: anyOf: - type: number - type: "null" responseToolCallCount: anyOf: - type: number - type: "null" responsePreview: anyOf: - type: string - type: "null" toolCallNames: anyOf: - type: array items: type: string - type: "null" estimatedCostUsd: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" additionalProperties: false - type: "null" requestSections: anyOf: - type: array items: type: object properties: kind: type: string label: anyOf: - type: string - type: "null" role: anyOf: - type: string - type: "null" text: anyOf: - type: string - type: "null" toolName: anyOf: - type: string - type: "null" data: {} language: anyOf: - type: string - type: "null" required: - kind additionalProperties: false - type: "null" responseSections: anyOf: - type: array items: type: object properties: kind: type: string label: anyOf: - type: string - type: "null" role: anyOf: - type: string - type: "null" text: anyOf: - type: string - type: "null" toolName: anyOf: - type: string - type: "null" data: {} language: anyOf: - type: string - type: "null" required: - kind additionalProperties: false - type: "null" agentLoopExitReason: anyOf: - type: string - type: "null" callSite: anyOf: - type: string - type: "null" error: anyOf: - type: object properties: name: anyOf: - type: string - type: "null" message: anyOf: - type: string - type: "null" code: anyOf: - type: string - type: "null" provider: anyOf: - type: string - type: "null" statusCode: anyOf: - type: number - type: "null" retryAfterMs: anyOf: - type: number - type: "null" apiErrorCode: anyOf: - type: string - type: "null" apiErrorType: anyOf: - type: string - type: "null" apiErrorParam: anyOf: - type: string - type: "null" requestId: anyOf: - type: string - type: "null" additionalProperties: false - type: "null" latency: anyOf: - type: object properties: phases: type: array items: type: object properties: key: type: string label: type: string ms: type: number subPhases: type: array items: type: object properties: key: type: string label: type: string ms: type: number required: - key - label - ms additionalProperties: false required: - key - label - ms additionalProperties: false ttftMs: anyOf: - type: number - type: "null" totalToFirstTokenMs: anyOf: - type: number - type: "null" providerDurationMs: anyOf: - type: number - type: "null" firstTokenKind: anyOf: - type: string enum: - thinking - text - type: "null" required: - phases additionalProperties: false - type: "null" required: - id - createdAt - requestPayload - responsePayload additionalProperties: false memoryRecall: anyOf: - type: object properties: enabled: type: boolean degraded: type: boolean provider: anyOf: - type: string - type: "null" model: anyOf: - type: string - type: "null" degradation: anyOf: - type: object properties: reason: type: string semanticUnavailable: type: boolean fallbackSources: type: array items: type: string required: - reason - semanticUnavailable - fallbackSources additionalProperties: false - type: "null" semanticHits: anyOf: - type: number - type: "null" mergedCount: anyOf: - type: number - type: "null" selectedCount: anyOf: - type: number - type: "null" tier1Count: anyOf: - type: number - type: "null" tier2Count: anyOf: - type: number - type: "null" hybridSearchLatencyMs: anyOf: - type: number - type: "null" sparseVectorUsed: anyOf: - type: boolean - type: "null" injectedTokens: anyOf: - type: number - type: "null" latencyMs: anyOf: - type: number - type: "null" topCandidates: type: array items: type: object properties: nodeId: type: string score: type: number semanticSimilarity: type: number recencyBoost: type: number type: type: string required: - nodeId - score - semanticSimilarity - recencyBoost additionalProperties: false injectedText: anyOf: - type: string - type: "null" reason: anyOf: - type: string - type: "null" queryContext: anyOf: - type: string - type: "null" required: - enabled - degraded - provider - model - degradation - topCandidates - injectedText - reason - queryContext additionalProperties: false - type: "null" memoryV2Activation: anyOf: - type: object properties: turn: type: number mode: type: string concepts: type: array items: type: object properties: slug: type: string finalActivation: type: number ownActivation: type: number priorActivation: type: number simUser: type: number simAssistant: type: number simNow: type: number simUserRerankBoost: type: number simAssistantRerankBoost: type: number inRerankPool: type: boolean spreadContribution: type: number source: type: string status: type: string required: - slug - finalActivation - ownActivation - priorActivation - simUser - simAssistant - simNow - spreadContribution - source - status additionalProperties: false config: type: object properties: d: type: number c_user: type: number c_assistant: type: number c_now: type: number k: type: number hops: type: number top_k: type: number epsilon: type: number required: - d - c_user - c_assistant - c_now - k - hops - top_k - epsilon additionalProperties: false required: - turn - mode - concepts - config additionalProperties: false - type: "null" memoryV3Selection: anyOf: - type: object properties: turn: type: number live: type: boolean selections: type: array items: type: object properties: slug: type: string source: type: string pinned: type: boolean sectionOrdinal: anyOf: - type: number - type: "null" sectionHeading: anyOf: - type: string - type: "null" required: - slug - source - pinned additionalProperties: false injectedText: type: string required: - turn - live - selections - injectedText additionalProperties: false - type: "null" required: - conversationKind - logs - memoryRecall - memoryV2Activation additionalProperties: false /v1/conversations/rename: post: operationId: conversations_rename_post summary: Rename a conversation description: Update the display title of a conversation. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 title: type: string minLength: 1 required: - conversationId - title responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean const: true required: - ok additionalProperties: false /v1/conversations/reorder: post: operationId: conversations_reorder_post summary: Move conversations between sections description: Batch-update which group holds each conversation, and its pin state. Lists are ordered by recency, so this sets placement, not order. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: updates: type: array items: type: object properties: conversationId: type: string isPinned: type: boolean groupId: anyOf: - type: string - type: "null" required: - conversationId required: - updates responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/conversations/search: get: operationId: conversations_search_get summary: Search conversations description: Full-text search across conversation titles and message content. tags: - conversations parameters: - name: q in: query required: true schema: type: string description: Search query - name: limit in: query required: false schema: type: integer description: Max results - name: maxMessagesPerConversation in: query required: false schema: type: integer description: Max messages per conversation responses: "200": description: Successful response content: application/json: schema: type: object properties: query: type: string results: type: array items: {} required: - query - results additionalProperties: false /v1/conversations/sections: get: operationId: conversations_sections_get summary: Sidebar section index description: "One row per renderable sidebar section (Pinned, each non-empty custom group, each origin channel with unassigned conversations, Chats) with total and unread counts and no conversation rows. Lets a client know which sections exist, and what their badges say, without fetching any conversation list. Totals follow the standard listing visibility; unread applies the same rules as GET /v1/conversations/unread-count scoped to the section. Chats is always present, even at zero: it is the leftover bucket and renders regardless." tags: - conversations responses: "200": description: Successful response content: application/json: schema: type: object properties: sections: type: array items: oneOf: - type: object properties: kind: type: string const: pinned total: type: number unread: type: number required: - kind - total - unread additionalProperties: false - type: object properties: kind: type: string const: group groupId: type: string name: type: string icon: anyOf: - type: string - type: "null" sortPosition: type: number total: type: number unread: type: number required: - kind - groupId - name - icon - sortPosition - total - unread additionalProperties: false - type: object properties: kind: type: string const: channel channelId: type: string total: type: number unread: type: number required: - kind - channelId - total - unread additionalProperties: false - type: object properties: kind: type: string const: chats total: type: number unread: type: number required: - kind - total - unread additionalProperties: false type: object required: - sections additionalProperties: false /v1/conversations/seen: post: operationId: conversations_seen_post summary: Record a seen signal description: Mark a conversation as seen, advancing the attention cursor. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string sourceChannel: type: string signalType: type: string confidence: type: string enum: - explicit - inferred source: type: string evidenceText: type: string metadata: type: object propertyNames: type: string additionalProperties: {} observedAt: type: number required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/conversations/seen/bulk: post: operationId: conversations_seen_bulk_post summary: Bulk mark conversations as seen description: Mark multiple conversations as seen in one request. Emits a single sync invalidation for the entire batch instead of per-conversation events. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationIds: minItems: 1 type: array items: type: string required: - conversationIds responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean updated: type: number required: - ok - updated additionalProperties: false /v1/conversations/summarize: post: operationId: conversations_summarize_post summary: Summarize a conversation up to a message description: Replace the conversation's context before the given message with a generated summary. The boundary snaps to the start of the turn containing beforeMessageId; that turn and everything after stay verbatim. Messages are never deleted. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string beforeMessageId: type: string description: Summarize all messages before this one required: - conversationId - beforeMessageId responses: "202": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean const: true conversationId: type: string required: - accepted - conversationId additionalProperties: false /v1/conversations/switch: post: operationId: conversations_switch_post summary: Switch active conversation description: Set the active conversation for the current session. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string conversationKey: type: string description: Optional key to register for this conversation required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string title: type: string conversationType: type: string inferenceProfile: type: string required: - conversationId - title - conversationType additionalProperties: false /v1/conversations/unread: post: operationId: conversations_unread_post summary: Mark conversation unread description: Reset the seen cursor so the conversation appears unread. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/conversations/unread-count: get: operationId: conversations_unreadcount_get summary: Unread conversation count description: "Count of foreground conversations whose latest assistant message is unseen. Matches the sidebar's unread indicators: archived rows and non-surfaced background/scheduled rows are excluded." tags: - conversations responses: "200": description: Successful response content: application/json: schema: type: object properties: count: type: number required: - count additionalProperties: false /v1/conversations/wake: post: operationId: conversations_wake_post summary: Wake a conversation description: Invoke the agent loop for a conversation with an opportunity hint. tags: - conversations requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 hint: type: string minLength: 1 source: default: cli type: string cronRunId: type: string minLength: 1 scheduleId: type: string minLength: 1 persist: type: boolean externalContent: type: string required: - conversationId - hint responses: "200": description: Successful response content: application/json: schema: type: object properties: invoked: type: boolean producedToolCalls: type: boolean reason: type: string required: - invoked - producedToolCalls additionalProperties: false /v1/credential-requests: post: operationId: credentialrequests_post summary: Mint a one-time credential-collection link description: Create a single-use tokenized URL that collects one credential value via the public credential-entry page. Link state lives in the gateway; the value is stored via the credential vault on submission. tags: - credentials requestBody: required: true content: application/json: schema: type: object properties: service: type: string minLength: 1 field: type: string minLength: 1 label: type: string required: - service - field responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean url: type: string token: type: string expiresAt: type: number error: type: string required: - ok additionalProperties: false /v1/credentials/delete: post: operationId: credentials_delete_post summary: Delete a credential description: Remove a secret, its metadata, and any associated OAuth connection from the vault. Refused with CREDENTIAL_IN_USE while an LLM provider connection resolves its auth through the credential, unless `force` is set. tags: - credentials requestBody: required: true content: application/json: schema: type: object properties: service: type: string description: Service namespace field: type: string description: Field name force: description: Delete even when provider connections depend on the credential type: boolean required: - service - field responses: "200": description: Successful response content: application/json: schema: type: object properties: service: type: string field: type: string affectedConnections: type: array items: type: string description: Provider connections that depended on the deleted credential required: - service - field - affectedConnections additionalProperties: false /v1/credentials/inspect: post: operationId: credentials_inspect_post summary: Inspect a credential description: Return metadata and a masked preview of a stored credential. Does not reveal the plaintext value. tags: - credentials requestBody: required: true content: application/json: schema: type: object properties: service: description: Service namespace type: string field: description: Field name type: string id: description: Credential UUID for lookup by ID type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: service: type: string field: type: string credentialId: anyOf: - type: string - type: "null" scrubbedValue: type: string hasSecret: type: boolean required: - service - field - credentialId - scrubbedValue - hasSecret additionalProperties: false /v1/credentials/list: post: operationId: credentials_list_post summary: List all credentials with metadata description: Return all stored credentials with metadata, OAuth connection info, and platform-managed credentials. tags: - credentials requestBody: required: true content: application/json: schema: type: object properties: search: description: Filter by substring match type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: credentials: type: array items: {} description: Local credentials with metadata managedCredentials: type: array items: {} description: Platform-managed credentials required: - credentials - managedCredentials additionalProperties: false /v1/credentials/prompt: post: operationId: credentials_prompt_post summary: Prompt user for a credential description: Trigger a secure input prompt in the user's app to collect a credential value. tags: - credentials requestBody: required: true content: application/json: schema: type: object properties: service: type: string minLength: 1 field: type: string minLength: 1 label: type: string minLength: 1 description: type: string placeholder: type: string usageDescription: type: string allowedDomains: type: array items: type: string allowedTools: type: array items: type: string injectionTemplates: type: array items: type: object properties: hostPattern: type: string minLength: 1 injectionType: type: string enum: - header - query headerName: type: string valuePrefix: type: string queryParamName: type: string required: - hostPattern - injectionType conversationId: type: string required: - service - field - label responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean cancelled: type: boolean pending: type: boolean collectionUrl: type: string expiresAt: type: number error: type: string service: type: string field: type: string message: type: string redirected: type: boolean required: - ok additionalProperties: false /v1/credentials/reveal: post: operationId: credentials_reveal_post summary: Reveal a credential's plaintext value description: Return the raw plaintext value of a stored credential. Blocked in untrusted shell mode. With forChat, returns a chat-safe redaction sentinel instead of the plaintext. tags: - credentials requestBody: required: true content: application/json: schema: type: object properties: service: description: Service namespace type: string field: description: Field name type: string id: description: Credential UUID for lookup by ID type: string forChat: description: Return the credential's redaction sentinel (renders as a click-to-reveal chip in chat) instead of the plaintext. Requires the chat-credential-reveal feature flag. type: boolean revealNonce: description: Conversation-bound reveal nonce from the tool-shell environment. Scopes any recorded chat-redaction authority (plaintext proof or forChat mint) to the conversation whose tool executed this reveal; without it the reveal succeeds but records no authority. type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: value: type: string description: The plaintext credential value (or its redaction sentinel when forChat is set) required: - value additionalProperties: false /v1/credentials/set: post: operationId: credentials_set_post summary: Store a credential with metadata description: Store a secret value and create or update its metadata (label, description, allowed tools). tags: - credentials requestBody: required: true content: application/json: schema: type: object properties: service: type: string description: Service namespace (e.g. google) field: type: string description: Field name (e.g. client_secret) value: type: string description: Secret value to store label: description: Human-friendly label type: string description: description: What this credential is used for type: string allowedTools: description: Tool names that may use this credential type: array items: type: string allowedDomains: description: Domains the credential may be sent to type: array items: type: string injectionTemplates: description: How the credential is injected into requests type: array items: type: object properties: hostPattern: type: string minLength: 1 injectionType: type: string enum: - header - query headerName: type: string valuePrefix: type: string queryParamName: type: string required: - hostPattern - injectionType required: - service - field - value responses: "200": description: Successful response content: application/json: schema: type: object properties: credentialId: type: string service: type: string field: type: string required: - credentialId - service - field additionalProperties: false /v1/credentials/status: get: operationId: credentials_status_get summary: Credential backend status description: Return the active credential storage backend and its configuration details. tags: - credentials responses: "200": description: Successful response content: application/json: schema: type: object properties: backend: type: string required: - backend additionalProperties: false /v1/debug: get: operationId: debug_get summary: Debug introspection description: "Return runtime diagnostics: uptime, provider info, memory stats, job counts, and schedule counts." tags: - debug responses: "200": description: Successful response content: application/json: schema: type: object properties: session: type: object properties: {} additionalProperties: {} description: Uptime and start time provider: type: object properties: {} additionalProperties: {} description: Inference provider configuration memory: type: object properties: {} additionalProperties: {} description: Conversation and memory item counts jobs: type: object properties: {} additionalProperties: {} description: Background job counts schedules: type: object properties: {} additionalProperties: {} description: Schedule counts (total, enabled) timestamp: type: string description: Current server timestamp (ISO 8601) required: - session - provider - memory - jobs - schedules - timestamp additionalProperties: false /v1/debug/bash: post: operationId: debug_bash_post summary: Execute a shell command in the assistant process description: Developer debugging tool. Requires the assistant to be running with VELLUM_DEBUG=1. tags: - debug requestBody: required: true content: application/json: schema: type: object properties: command: type: string description: Shell command to execute via bash -c timeoutMs: description: "Execution timeout in milliseconds (default: 30000)" type: number required: - command responses: "200": description: Successful response content: application/json: schema: type: object properties: stdout: type: string stderr: type: string exitCode: anyOf: - type: number - type: "null" timedOut: type: boolean error: type: string required: - stdout - stderr - exitCode - timedOut additionalProperties: false /v1/defer/cancel: post: operationId: defer_cancel_post summary: Cancel deferred wakes description: Cancel a specific deferred wake by ID, or all defers for a conversation. tags: - defer requestBody: required: true content: application/json: schema: type: object properties: id: type: string all: type: boolean conversationId: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: cancelled: type: number error: type: string required: - cancelled additionalProperties: false /v1/defer/create: post: operationId: defer_create_post summary: Create a deferred wake description: Schedule a future wake-up on a conversation, optionally with a delay or absolute timestamp. tags: - defer requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 hint: type: string minLength: 1 delaySeconds: type: number fireAt: type: number name: type: string required: - conversationId - hint responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string name: type: string fireAt: type: number conversationId: type: string required: - id - name - fireAt - conversationId additionalProperties: false /v1/defer/list: post: operationId: defer_list_post summary: List active deferred wakes description: List all active deferred wakes, optionally filtered by conversation. tags: - defer requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: defers: type: array items: type: object properties: id: type: string name: type: string hint: type: string conversationId: type: string fireAt: type: number status: type: string required: - id - name - hint - conversationId - fireAt - status additionalProperties: false required: - defers additionalProperties: false /v1/diagnostics/env-vars: get: operationId: diagnostics_envvars_get summary: List safe environment variables description: Return environment variable names and values that are safe to expose (no secrets). tags: - diagnostics responses: "200": description: Successful response /v1/dictation: post: operationId: dictation_post summary: Process dictation description: Classify voice input as dictation or action, clean up text, and apply user style preferences. tags: - diagnostics requestBody: required: true content: application/json: schema: type: object properties: transcription: type: string description: Raw speech transcription context: type: object properties: cursorInTextField: description: Whether the cursor is in an editable text field when dictation started type: boolean additionalProperties: {} description: Dictation context (app name, window title, bundle ID, cursor state, selected text) profileId: type: string description: Optional dictation profile ID required: - transcription - context responses: "200": description: Successful response content: application/json: schema: type: object properties: text: type: string description: Processed text output mode: type: string description: "Detected mode: dictation, command, or action" actionPlan: description: Action plan (only when mode is action) type: string resolvedProfileId: type: string description: Resolved dictation profile ID profileSource: type: string description: How the profile was resolved required: - text - mode - resolvedProfileId - profileSource additionalProperties: false /v1/disk-pressure/acknowledge: post: operationId: diskpressure_acknowledge_post summary: Acknowledge disk pressure description: Acknowledge the current disk pressure lock and enter cleanup mode without overriding assistant protections. tags: - disk-pressure responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: object properties: enabled: type: boolean state: type: string enum: - disabled - ok - warning - critical - unknown locked: type: boolean acknowledged: type: boolean overrideActive: type: boolean effectivelyLocked: type: boolean lockId: anyOf: - type: string - type: "null" usagePercent: anyOf: - type: number - type: "null" thresholdPercent: type: number path: anyOf: - type: string - type: "null" lastCheckedAt: anyOf: - type: string - type: "null" blockedCapabilities: type: array items: type: string enum: - agent-turns - background-work - remote-ingress error: anyOf: - type: string - type: "null" required: - enabled - state - locked - acknowledged - overrideActive - effectivelyLocked - lockId - usagePercent - thresholdPercent - path - lastCheckedAt - blockedCapabilities - error additionalProperties: false required: - status additionalProperties: false "409": description: No active lock or lock already acknowledged. /v1/disk-pressure/override: post: operationId: diskpressure_override_post summary: Override disk pressure description: Override the current disk pressure lock only after confirming "I understand the risks". tags: - disk-pressure requestBody: required: true content: application/json: schema: type: object properties: confirmation: type: string required: - confirmation responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: object properties: enabled: type: boolean state: type: string enum: - disabled - ok - warning - critical - unknown locked: type: boolean acknowledged: type: boolean overrideActive: type: boolean effectivelyLocked: type: boolean lockId: anyOf: - type: string - type: "null" usagePercent: anyOf: - type: number - type: "null" thresholdPercent: type: number path: anyOf: - type: string - type: "null" lastCheckedAt: anyOf: - type: string - type: "null" blockedCapabilities: type: array items: type: string enum: - agent-turns - background-work - remote-ingress error: anyOf: - type: string - type: "null" required: - enabled - state - locked - acknowledged - overrideActive - effectivelyLocked - lockId - usagePercent - thresholdPercent - path - lastCheckedAt - blockedCapabilities - error additionalProperties: false required: - status additionalProperties: false "400": description: Confirmation phrase is invalid. "409": description: No active lock or lock already overridden. /v1/disk-pressure/status: get: operationId: diskpressure_status_get summary: Get disk pressure status description: Return the current disk pressure status snapshot. When safe storage limits are disabled, returns a disabled status. tags: - disk-pressure responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: object properties: enabled: type: boolean state: type: string enum: - disabled - ok - warning - critical - unknown locked: type: boolean acknowledged: type: boolean overrideActive: type: boolean effectivelyLocked: type: boolean lockId: anyOf: - type: string - type: "null" usagePercent: anyOf: - type: number - type: "null" thresholdPercent: type: number path: anyOf: - type: string - type: "null" lastCheckedAt: anyOf: - type: string - type: "null" blockedCapabilities: type: array items: type: string enum: - agent-turns - background-work - remote-ingress error: anyOf: - type: string - type: "null" required: - enabled - state - locked - acknowledged - overrideActive - effectivelyLocked - lockId - usagePercent - thresholdPercent - path - lastCheckedAt - blockedCapabilities - error additionalProperties: false required: - status additionalProperties: false /v1/documents: get: operationId: documents_get summary: List documents description: Return all documents, optionally filtered by conversation. tags: - documents parameters: - name: conversationId in: query required: false schema: type: string description: Filter by conversation ID responses: "200": description: Successful response content: application/json: schema: type: object properties: documents: type: array items: type: object properties: surfaceId: type: string conversationId: type: string title: type: string wordCount: type: number createdAt: type: number updatedAt: type: number required: - surfaceId - conversationId - title - wordCount - createdAt - updatedAt additionalProperties: false required: - documents additionalProperties: false post: operationId: documents_post summary: Save a document description: Create or upsert a document (by surfaceId). tags: - documents requestBody: required: true content: application/json: schema: type: object properties: surfaceId: type: string description: Surface ID (unique key) conversationId: type: string description: Owning conversation title: type: string description: Document title content: type: string description: Document content wordCount: type: number description: Word count required: - surfaceId - conversationId - title - content - wordCount responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean const: true surfaceId: type: string required: - success - surfaceId additionalProperties: false /v1/documents/{id}: get: operationId: documents_by_id_get summary: Get a document description: Return a single document by surface ID. tags: - documents parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean surfaceId: type: string conversationId: type: string title: type: string content: type: string wordCount: type: number createdAt: type: number updatedAt: type: number required: - success - surfaceId - conversationId - title - content - wordCount - createdAt - updatedAt additionalProperties: false /v1/documents/{id}/comments: get: operationId: documents_by_id_comments_get summary: List comments for a document description: Return comments for a document, optionally filtered by status. tags: - documents parameters: - name: id in: path required: true schema: type: string - name: status in: query required: false schema: type: string enum: - open - resolved - all description: "Filter by comment status (default: all)" responses: "200": description: Successful response content: application/json: schema: type: object properties: comments: type: array items: type: object properties: id: type: string surfaceId: type: string conversationId: type: string author: type: string content: type: string anchorStart: anyOf: - type: number - type: "null" anchorEnd: anyOf: - type: number - type: "null" anchorText: anyOf: - type: string - type: "null" parentCommentId: anyOf: - type: string - type: "null" status: type: string enum: - open - resolved resolvedBy: anyOf: - type: string - type: "null" resolvedAt: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number required: - id - surfaceId - conversationId - author - content - anchorStart - anchorEnd - anchorText - parentCommentId - status - resolvedBy - resolvedAt - createdAt - updatedAt additionalProperties: false description: Comment records required: - comments additionalProperties: false post: operationId: documents_by_id_comments_post summary: Create a comment on a document description: Add a new comment to a document. tags: - documents parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: content: type: string minLength: 1 description: Comment text content author: default: user description: Comment author type: string const: user anchorStart: description: Selection start offset anyOf: - type: number - type: "null" anchorEnd: description: Selection end offset anyOf: - type: number - type: "null" anchorText: description: Anchored text snippet anyOf: - type: string - type: "null" parentCommentId: description: Parent comment ID for replies anyOf: - type: string - type: "null" conversationId: type: string description: Owning conversation ID required: - content - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string surfaceId: type: string conversationId: type: string author: type: string content: type: string anchorStart: anyOf: - type: number - type: "null" anchorEnd: anyOf: - type: number - type: "null" anchorText: anyOf: - type: string - type: "null" parentCommentId: anyOf: - type: string - type: "null" status: type: string enum: - open - resolved resolvedBy: anyOf: - type: string - type: "null" resolvedAt: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number required: - id - surfaceId - conversationId - author - content - anchorStart - anchorEnd - anchorText - parentCommentId - status - resolvedBy - resolvedAt - createdAt - updatedAt additionalProperties: false /v1/documents/{id}/comments/{commentId}: delete: operationId: documents_by_id_comments_by_commentId_delete summary: Delete a document comment description: Permanently delete a comment. tags: - documents parameters: - name: id in: path required: true schema: type: string - name: commentId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean const: true required: - success additionalProperties: false patch: operationId: documents_by_id_comments_by_commentId_patch summary: Update a document comment description: Update the status or content of a comment. tags: - documents parameters: - name: id in: path required: true schema: type: string - name: commentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: status: description: New comment status type: string enum: - open - resolved content: description: Updated comment text type: string minLength: 1 resolvedBy: description: Who resolved the comment type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string surfaceId: type: string conversationId: type: string author: type: string content: type: string anchorStart: anyOf: - type: number - type: "null" anchorEnd: anyOf: - type: number - type: "null" anchorText: anyOf: - type: string - type: "null" parentCommentId: anyOf: - type: string - type: "null" status: type: string enum: - open - resolved resolvedBy: anyOf: - type: string - type: "null" resolvedAt: anyOf: - type: number - type: "null" createdAt: type: number updatedAt: type: number required: - id - surfaceId - conversationId - author - content - anchorStart - anchorEnd - anchorText - parentCommentId - status - resolvedBy - resolvedAt - createdAt - updatedAt additionalProperties: false /v1/documents/{id}/conversations: post: operationId: documents_by_id_conversations_post summary: Link a document to a conversation description: Associate a document with a conversation so the assistant sees it as context. tags: - documents parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string description: Conversation to link required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean const: true required: - success additionalProperties: false /v1/documents/{id}/pdf: get: operationId: documents_by_id_pdf_get summary: Export a document as PDF description: Render a document to PDF and return the binary content. tags: - documents parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/pdf: schema: type: string format: binary /v1/domain/register: post: operationId: domain_register_post summary: Register a subdomain for this assistant tags: - domain requestBody: required: true content: application/json: schema: type: object properties: subdomain: type: string email_username: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string subdomain: type: string domain: type: string created_at: type: string created: type: string email_error: type: object properties: detail: type: string code: type: string required: - detail - code additionalProperties: false required: - id additionalProperties: false /v1/domain/status: get: operationId: domain_status_get summary: Show domain registration and health tags: - domain responses: "200": description: Successful response content: application/json: schema: type: object properties: count: type: number next: anyOf: - type: string - type: "null" previous: anyOf: - type: string - type: "null" results: type: array items: type: object properties: id: type: string subdomain: type: string domain: type: string created_at: type: string created: type: string required: - id additionalProperties: false required: - count - results additionalProperties: false /v1/domain/verification-status: post: operationId: domain_verificationstatus_post summary: Get live DNS verification status for a domain tags: - domain requestBody: required: true content: application/json: schema: type: object properties: domain_id: type: string required: - domain_id responses: "200": description: Successful response content: application/json: schema: type: object properties: domain: type: string status: type: string message: type: string required: - domain - status - message additionalProperties: false /v1/email/attachment-get: get: operationId: email_attachmentget_get summary: Stream-download an email attachment description: Download the binary content of a specific email attachment as a chunked stream. Response headers include content-type from the upstream and x-filename derived from content-disposition. tags: - email parameters: - name: messageId in: query required: true schema: type: string description: Email message ID - name: attachmentId in: query required: true schema: type: string description: Attachment ID responses: "200": description: Successful response /v1/email/attachment-list: get: operationId: email_attachmentlist_get summary: List attachments for an email message description: Return attachment metadata (id, filename, content_type, size_bytes, content_id, created_at) for all attachments on a given email message. tags: - email parameters: - name: messageId in: query required: true schema: type: string description: Email message ID responses: "200": description: Successful response content: application/json: schema: type: object properties: results: type: array items: type: object properties: id: type: string filename: type: string content_type: type: string size_bytes: type: number content_id: type: string created_at: type: string required: - id - filename - content_type - size_bytes - content_id - created_at additionalProperties: false required: - results additionalProperties: false /v1/email/download: get: operationId: email_download_get summary: Download a specific email message description: Download a specific email message by ID. tags: - email parameters: - name: messageId in: query required: true schema: type: string description: Email message ID responses: "200": description: Successful response content: application/json: schema: {} /v1/email/list: get: operationId: email_list_get summary: List email messages description: List received and sent emails for this assistant, with optional filtering. tags: - email parameters: - name: direction in: query required: false schema: type: string description: "Filter by direction: inbound, outbound, or all" - name: limit in: query required: false schema: type: string description: Maximum number of results - name: since in: query required: false schema: type: string description: Only show messages since this date (ISO 8601) responses: "200": description: Successful response content: application/json: schema: type: object properties: results: type: array items: {} count: type: number required: - results - count additionalProperties: false /v1/email/register: post: operationId: email_register_post summary: Register an email address description: Register a new email address on the Vellum platform for the current assistant. tags: - email requestBody: required: true content: application/json: schema: type: object properties: username: type: string minLength: 1 description: The local part of the email address required: - username responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string address: type: string created_at: type: string required: - id - address - created_at additionalProperties: false /v1/email/send: post: operationId: email_send_post summary: Send an email description: Send an email from the assistant's registered email address via the Vellum runtime proxy. tags: - email requestBody: required: true content: application/json: schema: type: object properties: to: minItems: 1 type: array items: type: string description: Recipient email address(es) text: type: string minLength: 1 description: Email body (plain text) subject: description: Subject line type: string html: description: HTML body (auto-generated from text if omitted) type: string cc: description: CC recipients type: array items: type: string bcc: description: BCC recipients type: array items: type: string attachments: description: File attachments type: array items: type: object properties: filename: type: string content_type: type: string content: type: string description: Base64-encoded file content required: - filename - content_type - content reply_to: description: Reply-to email ID type: string required: - to - text responses: "200": description: Successful response content: application/json: schema: type: object properties: delivery_id: type: string status: type: string required: - delivery_id - status additionalProperties: false /v1/email/status: get: operationId: email_status_get summary: Get email address status and usage description: Show the email address registered for this assistant along with current usage and quota information. tags: - email responses: "200": description: Successful response content: application/json: schema: type: object properties: address: type: string status: type: string created_at: type: string usage: type: object properties: sent_today: type: number daily_limit: type: number received_today: type: number sent_this_month: type: number received_this_month: type: number required: - sent_today - daily_limit - received_today - sent_this_month - received_this_month additionalProperties: false required: - address - status - created_at - usage additionalProperties: false /v1/email/unregister: post: operationId: email_unregister_post summary: Unregister the email address description: Remove the email address currently registered for this assistant. tags: - email responses: "200": description: Successful response content: application/json: schema: type: object properties: unregistered: type: string required: - unregistered additionalProperties: false /v1/events: get: operationId: events_get summary: Subscribe to assistant events description: Stream assistant events as Server-Sent Events (SSE). tags: - events parameters: - name: conversationId in: query required: false schema: type: string description: Scope to a single conversation by its assistant-minted internal id. 404s if no such conversation exists. - name: conversationKey in: query required: false schema: type: string description: Scope to a single conversation by an external key (non-vellum channels) or the web idempotency key. Materializes a row on first use. Ignored when conversationId is also provided. - name: lastSeenSeq in: query required: false schema: type: string description: "Optional reconnect cursor: the highest global event seq the client has already applied. `seq` is a single per-assistant counter shared across all conversations, so one cursor resumes the stream regardless of how many conversations are multiplexed on the connection. When set, the daemon replays any buffered events with seq > lastSeenSeq (re-applying the subscriber's targeting/scope filter) before going live. If the cursor is older than the ring buffer's oldest entry the connection simply goes live; the client is expected to detect the gap from the next event's seq and refetch via the messages API. Must be a non-negative integer." responses: "200": description: Successful response /v1/events/emit: post: operationId: events_emit_post summary: Emit an assistant event description: Trigger an in-process assistant event by kind. Used by the gateway after owning a write that the assistant runtime would normally emit. tags: - events requestBody: required: true content: application/json: schema: type: object properties: kind: type: string enum: - contacts_changed required: - kind responses: "204": description: Successful response /v1/events/tail: get: operationId: events_tail_get summary: Fetch a conversation's buffered event tail description: Return the ring-buffered assistant events for one conversation with seq greater than fromSeq — the request/response twin of reconnecting the SSE stream with lastSeenSeq. A client recovering from a delivery gap fetches the /messages snapshot (anchored at its seq watermark) and then this tail from that anchor, folding the returned envelopes through the same apply path as live events; snapshot plus tail is deterministically complete. complete=false means the ring no longer reaches back to fromSeq and the snapshot alone must serve as the recovery. tags: - events parameters: - name: conversationId in: query required: false schema: type: string description: Assistant-minted internal conversation id whose events to return. Required. - name: fromSeq in: query required: false schema: type: string description: Return buffered events with seq strictly greater than this value — typically the seq watermark of a just-fetched /messages snapshot. Must be a non-negative integer. - name: toSeq in: query required: false schema: type: string description: Optional inclusive upper bound on returned seqs. A caller that already knows where its live delivery resumed (e.g. the first live event after a gap) can trim the response to exactly the hole. Purely a bandwidth trim — client folds are seq-idempotent, so overlap with live delivery is harmless without it. Must be an integer >= fromSeq. responses: "200": description: Successful response content: application/json: schema: type: object properties: events: type: array items: {} description: Buffered assistant event envelopes ({id, conversationId, emittedAt, seq, message}) with seq > fromSeq, ascending, filtered to the conversation and to the caller's delivery set (client identity headers). Same wire shape as the /events SSE data frames. complete: type: boolean description: True when the ring still covered fromSeq, so the returned events are the contiguous tail. False when eviction broke contiguity — events is empty and the caller must recover from the snapshot alone. frontier: anyOf: - type: number - type: "null" description: Seq of the last returned event (or fromSeq when the tail is empty but contiguous). Null when complete is false. required: - events - complete - frontier additionalProperties: false /v1/export: post: operationId: export_post summary: Export logs and audit data description: Export audit records, assistant logs, and config as a tar.gz archive. tags: - export requestBody: required: true content: application/json: schema: type: object properties: auditLimit: description: Max audit records (default 1000) type: integer minimum: -9007199254740991 maximum: 9007199254740991 conversationId: description: Scope to a single conversation type: string full: description: Full export — include messages, LLM request logs, and usage events for all conversations. type: boolean startTime: description: Lower bound epoch ms type: number endTime: description: Upper bound epoch ms type: number responses: "200": description: Successful response content: application/gzip: schema: type: string format: binary "500": description: Failed to create archive /v1/filing/config: get: operationId: filing_config_get summary: Get filing config description: Return the current filing schedule configuration. tags: - filing responses: "200": description: Successful response content: application/json: schema: type: object properties: available: type: boolean enabled: type: boolean intervalMs: type: number activeHoursStart: anyOf: - type: number - type: "null" activeHoursEnd: anyOf: - type: number - type: "null" nextRunAt: anyOf: - type: number - type: "null" lastRunAt: anyOf: - type: number - type: "null" success: type: boolean required: - available - enabled - intervalMs - activeHoursStart - activeHoursEnd - nextRunAt - lastRunAt - success additionalProperties: false /v1/filing/run-now: post: operationId: filing_runnow_post summary: Run filing now description: Enqueue an immediate PKB filing job. Returns once the job is queued; the job itself runs through the memory jobs worker. tags: - filing responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean ran: type: boolean description: Whether a job was enqueued required: - success - ran additionalProperties: false /v1/gateway/logs/tail: get: operationId: gateway_logs_tail_get summary: Tail gateway log entries description: Return the last N structured log entries from the gateway log files. tags: - gateway-logs parameters: - name: n in: query required: false schema: type: string description: "Number of lines to return (1–1000, default: 10)" - name: level in: query required: false schema: type: string description: "Minimum pino level name (default: info)" - name: module in: query required: false schema: type: string description: Filter to exact pino module name responses: "200": description: Successful response content: application/json: schema: type: object properties: lines: type: array items: type: object propertyNames: type: string additionalProperties: {} truncated: type: boolean required: - lines - truncated additionalProperties: false /v1/gateway/status: get: operationId: gateway_status_get summary: Get gateway status description: Reports the gateway's public tunnel status. `tunnel` holds the active public URL when a tunnel is connected and is omitted otherwise. Errors with 503 when the gateway is not running. The tunnel only matters for routing inbound Twilio webhooks and live voice/audio WebSockets. tags: - gateway responses: "200": description: Successful response content: application/json: schema: type: object properties: tunnel: type: string additionalProperties: false /v1/groups: get: operationId: groups_get summary: List groups description: Return all conversation groups. tags: - groups responses: "200": description: Successful response content: application/json: schema: type: object properties: groups: type: array items: type: object properties: id: type: string name: type: string icon: description: Client-chosen icon name; null when the group has none anyOf: - type: string - type: "null" sortPosition: type: number isSystemGroup: type: boolean required: - id - name - sortPosition - isSystemGroup additionalProperties: false required: - groups additionalProperties: false post: operationId: groups_post summary: Create group description: Create a new custom conversation group. Server assigns sort_position. tags: - groups requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Group name icon: description: Client-chosen icon name anyOf: - type: string - type: "null" required: - name responses: "201": description: Successful response content: application/json: schema: type: object properties: id: type: string name: type: string icon: description: Client-chosen icon name; null when the group has none anyOf: - type: string - type: "null" sortPosition: type: number isSystemGroup: type: boolean required: - id - name - sortPosition - isSystemGroup additionalProperties: false "400": description: Missing or invalid name, or sort_position ceiling reached /v1/groups/{groupId}: delete: operationId: groups_by_groupId_delete summary: Delete group description: Delete a custom conversation group. tags: - groups parameters: - name: groupId in: path required: true schema: type: string responses: "204": description: Successful response "403": description: System groups cannot be deleted "404": description: Group not found patch: operationId: groups_by_groupId_patch summary: Update group description: Update a conversation group's name, icon, or sort position. tags: - groups parameters: - name: groupId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string icon: description: Client-chosen icon name; null clears it anyOf: - type: string - type: "null" sortPosition: type: number responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string name: type: string icon: description: Client-chosen icon name; null when the group has none anyOf: - type: string - type: "null" sortPosition: type: number isSystemGroup: type: boolean required: - id - name - sortPosition - isSystemGroup additionalProperties: false "403": description: System group sort position cannot be changed "404": description: Group not found /v1/groups/reorder: post: operationId: groups_reorder_post summary: Reorder groups description: Batch-update sort positions for conversation groups. tags: - groups requestBody: required: true content: application/json: schema: type: object properties: updates: type: array items: type: object properties: groupId: type: string sortPosition: type: number required: - groupId - sortPosition description: Array of { groupId, sortPosition } objects required: - updates responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false "403": description: Cannot reorder system groups /v1/guardian-actions/decision: post: operationId: guardianactions_decision_post summary: Submit guardian decision description: Submit a guardian action decision (approve/reject). tags: - guardian requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string description: Guardian request ID action: type: string description: Decision action conversationId: type: string description: Conversation ID required: - requestId - action responses: "200": description: Successful response content: application/json: schema: type: object properties: applied: type: boolean requestId: type: string reason: description: Decline reason (present only when applied is false) type: string replyText: description: Resolver reply text for the guardian (e.g. verification code) type: string required: - applied - requestId additionalProperties: false /v1/guardian-actions/pending: get: operationId: guardianactions_pending_get summary: List pending guardian actions description: Return pending guardian decision prompts for a conversation. tags: - guardian parameters: - name: conversationId in: query required: false schema: type: string description: Conversation ID (required) responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string prompts: type: array items: {} description: Guardian decision prompt objects required: - conversationId - prompts additionalProperties: false /v1/health: get: operationId: health_get summary: Detailed health check description: Returns runtime health including version, disk, memory, CPU, and migration status. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string timestamp: type: string version: type: string disk: anyOf: - type: object properties: path: type: string totalMb: type: number usedMb: type: number freeMb: type: number required: - path - totalMb - usedMb - freeMb additionalProperties: false - type: "null" memory: type: object properties: currentMb: type: number maxMb: type: number required: - currentMb - maxMb additionalProperties: false cpu: type: object properties: currentPercent: type: number maxCores: type: number required: - currentPercent - maxCores additionalProperties: false migrations: type: object properties: dbVersion: type: number lastWorkspaceMigrationId: anyOf: - type: string - type: "null" required: - dbVersion - lastWorkspaceMigrationId additionalProperties: false ces: type: object properties: connected: type: boolean required: - connected additionalProperties: false capabilities: type: object properties: memoryOptOut: type: boolean retryLastTurn: type: boolean required: - memoryOptOut - retryLastTurn additionalProperties: false profiler: type: object properties: enabled: type: boolean mode: anyOf: - type: string - type: "null" runId: anyOf: - type: string - type: "null" runDir: anyOf: - type: string - type: "null" totalBytes: type: number artifactCount: type: number budget: anyOf: - type: object properties: maxBytes: type: number remainingBytes: type: number minFreeMb: type: number freeMb: type: number overBudget: type: boolean required: - maxBytes - remainingBytes - minFreeMb - freeMb - overBudget additionalProperties: false - type: "null" lastCompletedRun: anyOf: - type: object properties: runId: type: string totalBytes: type: number artifactCount: type: number hasSummaries: type: boolean completedAt: type: string required: - runId - totalBytes - artifactCount - hasSummaries - completedAt additionalProperties: false - type: "null" required: - enabled - mode - runId - runDir - totalBytes - artifactCount - budget - lastCompletedRun additionalProperties: false reason: type: string dbMigrations: type: object properties: ready: type: boolean state: type: string enum: - not_started - running - failed - ready reason: type: string error: type: string required: - ready - state additionalProperties: false required: - status - timestamp - version - disk - memory - cpu - migrations - ces - capabilities additionalProperties: false /v1/healthz: get: operationId: healthz_get summary: Detailed health check (alias) description: Alias for /v1/health. Returns runtime health including version, disk, memory, CPU, and migration status. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string timestamp: type: string version: type: string disk: anyOf: - type: object properties: path: type: string totalMb: type: number usedMb: type: number freeMb: type: number required: - path - totalMb - usedMb - freeMb additionalProperties: false - type: "null" memory: type: object properties: currentMb: type: number maxMb: type: number required: - currentMb - maxMb additionalProperties: false cpu: type: object properties: currentPercent: type: number maxCores: type: number required: - currentPercent - maxCores additionalProperties: false migrations: type: object properties: dbVersion: type: number lastWorkspaceMigrationId: anyOf: - type: string - type: "null" required: - dbVersion - lastWorkspaceMigrationId additionalProperties: false ces: type: object properties: connected: type: boolean required: - connected additionalProperties: false capabilities: type: object properties: memoryOptOut: type: boolean retryLastTurn: type: boolean required: - memoryOptOut - retryLastTurn additionalProperties: false profiler: type: object properties: enabled: type: boolean mode: anyOf: - type: string - type: "null" runId: anyOf: - type: string - type: "null" runDir: anyOf: - type: string - type: "null" totalBytes: type: number artifactCount: type: number budget: anyOf: - type: object properties: maxBytes: type: number remainingBytes: type: number minFreeMb: type: number freeMb: type: number overBudget: type: boolean required: - maxBytes - remainingBytes - minFreeMb - freeMb - overBudget additionalProperties: false - type: "null" lastCompletedRun: anyOf: - type: object properties: runId: type: string totalBytes: type: number artifactCount: type: number hasSummaries: type: boolean completedAt: type: string required: - runId - totalBytes - artifactCount - hasSummaries - completedAt additionalProperties: false - type: "null" required: - enabled - mode - runId - runDir - totalBytes - artifactCount - budget - lastCompletedRun additionalProperties: false reason: type: string dbMigrations: type: object properties: ready: type: boolean state: type: string enum: - not_started - running - failed - ready reason: type: string error: type: string required: - ready - state additionalProperties: false required: - status - timestamp - version - disk - memory - cpu - migrations - ces - capabilities additionalProperties: false /v1/heartbeat/checklist: get: operationId: heartbeat_checklist_get summary: Get heartbeat checklist description: Return the HEARTBEAT.md checklist content. tags: - heartbeat responses: "200": description: Successful response content: application/json: schema: type: object properties: content: type: string description: Checklist markdown content isDefault: type: boolean description: True when no custom checklist exists required: - content - isDefault additionalProperties: false put: operationId: heartbeat_checklist_put summary: Write heartbeat checklist description: Overwrite the HEARTBEAT.md checklist content. tags: - heartbeat requestBody: required: true content: application/json: schema: type: object properties: content: type: string description: Checklist markdown content required: - content responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false /v1/heartbeat/config: get: operationId: heartbeat_config_get summary: Get heartbeat config description: Return the current heartbeat schedule configuration. tags: - heartbeat responses: "200": description: Successful response content: application/json: schema: type: object properties: enabled: type: boolean intervalMs: type: number activeHoursStart: anyOf: - type: number - type: "null" activeHoursEnd: anyOf: - type: number - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" nextRunAt: anyOf: - type: number - type: "null" lastRunAt: anyOf: - type: number - type: "null" success: type: boolean required: - enabled - intervalMs - activeHoursStart - activeHoursEnd - cronExpression - timezone - nextRunAt - lastRunAt - success additionalProperties: false put: operationId: heartbeat_config_put summary: Update heartbeat config description: Update the heartbeat schedule configuration. tags: - heartbeat requestBody: required: true content: application/json: schema: type: object properties: enabled: description: Enable or disable heartbeat type: boolean intervalMs: description: Heartbeat interval in ms type: number activeHoursStart: description: Active hours start (0–23) anyOf: - type: number - type: "null" activeHoursEnd: description: Active hours end (0–23) anyOf: - type: number - type: "null" cronExpression: description: Cron expression for heartbeat timing, or null for fixed interval anyOf: - type: string - type: "null" timezone: description: Timezone for cron evaluation anyOf: - type: string - type: "null" responses: "200": description: Successful response content: application/json: schema: type: object properties: enabled: type: boolean intervalMs: type: number activeHoursStart: anyOf: - type: number - type: "null" activeHoursEnd: anyOf: - type: number - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" nextRunAt: anyOf: - type: number - type: "null" lastRunAt: anyOf: - type: number - type: "null" success: type: boolean required: - enabled - intervalMs - activeHoursStart - activeHoursEnd - cronExpression - timezone - nextRunAt - lastRunAt - success additionalProperties: false /v1/heartbeat/run-now: post: operationId: heartbeat_runnow_post summary: Run heartbeat now description: Trigger an immediate heartbeat run. tags: - heartbeat responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean ran: type: boolean description: Whether the heartbeat actually ran required: - success - ran additionalProperties: false /v1/heartbeat/runs: get: operationId: heartbeat_runs_get summary: List heartbeat runs description: Return recent heartbeat conversation runs. tags: - heartbeat parameters: - name: limit in: query required: false schema: type: integer description: Max runs to return (default 20, max 100) - name: before in: query required: false schema: type: integer description: "Cursor for older runs: pass the previous page's `nextCursor` to return runs strictly older than it." responses: "200": description: Successful response content: application/json: schema: type: object properties: runs: type: array items: type: object properties: id: type: string scheduledFor: type: number startedAt: anyOf: - type: number - type: "null" finishedAt: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" status: type: string skipReason: anyOf: - type: string - type: "null" error: anyOf: - type: string - type: "null" conversationId: anyOf: - type: string - type: "null" conversationExists: type: boolean conversationArchivedAt: anyOf: - type: number - type: "null" estimatedCostUsd: type: number createdAt: type: number required: - id - scheduledFor - startedAt - finishedAt - durationMs - status - skipReason - error - conversationId - conversationExists - conversationArchivedAt - estimatedCostUsd - createdAt additionalProperties: false description: Heartbeat run records nextCursor: anyOf: - type: number - type: "null" description: Cursor for fetching older runs (pass as `before`); null when no older runs exist required: - runs - nextCursor additionalProperties: false /v1/home/feed: get: operationId: home_feed_get summary: Get home activity feed description: Return the current Home activity feed with TTL + time-away filtering applied. Also returns a context banner (greeting, relative time-away label, new-item count). tags: - home parameters: - name: timeAwaySeconds in: query required: true schema: type: integer description: Seconds since the user was last active in the client. Used to compute the context-banner relative-time label. responses: "200": description: Successful response content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string type: type: string const: notification priority: type: integer minimum: 0 maximum: 100 title: type: string summary: type: string timestamp: type: string status: default: new type: string enum: - new - seen - acted_on - dismissed expiresAt: type: string actions: type: array items: type: object properties: id: type: string label: type: string prompt: type: string required: - id - label - prompt additionalProperties: false urgency: type: string enum: - low - medium - high - critical conversationId: type: string detailPanel: type: object properties: kind: type: string enum: - emailDraft - documentPreview - permissionChat - paymentAuth - toolPermission - updatesList required: - kind additionalProperties: false category: type: string enum: - security - scheduling - background - email - system noteworthy: type: boolean fromAssistant: type: boolean metadata: type: object propertyNames: type: string additionalProperties: {} sourceType: type: string enum: - heartbeat - memory_consolidation - schedule - auto_analysis - user - other sourceKey: type: string sourceLabel: type: string createdAt: type: string required: - id - type - priority - summary - timestamp - status - createdAt additionalProperties: false updatedAt: type: string contextBanner: type: object properties: greeting: type: string timeAwayLabel: type: string newCount: type: integer minimum: 0 maximum: 9007199254740991 required: - greeting - timeAwayLabel - newCount additionalProperties: false suggestedPrompts: type: array items: type: object properties: id: type: string label: type: string icon: type: string prompt: type: string source: type: string enum: - deterministic - assistant required: - id - label - prompt - source additionalProperties: false required: - items - updatedAt - contextBanner - suggestedPrompts additionalProperties: false /v1/home/feed/{id}: patch: operationId: home_feed_by_id_patch summary: Patch home feed item status description: Update the `status` field of a single feed item (e.g. mark it seen or acted_on). Returns the updated item on success, 404 if the item does not exist, 500 if the underlying write fails. tags: - home parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: - new - seen - acted_on - dismissed required: - status responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string type: type: string const: notification priority: type: integer minimum: 0 maximum: 100 title: type: string summary: type: string timestamp: type: string status: default: new type: string enum: - new - seen - acted_on - dismissed expiresAt: type: string actions: type: array items: type: object properties: id: type: string label: type: string prompt: type: string required: - id - label - prompt additionalProperties: false urgency: type: string enum: - low - medium - high - critical conversationId: type: string detailPanel: type: object properties: kind: type: string enum: - emailDraft - documentPreview - permissionChat - paymentAuth - toolPermission - updatesList required: - kind additionalProperties: false category: type: string enum: - security - scheduling - background - email - system noteworthy: type: boolean fromAssistant: type: boolean metadata: type: object propertyNames: type: string additionalProperties: {} sourceType: type: string enum: - heartbeat - memory_consolidation - schedule - auto_analysis - user - other sourceKey: type: string sourceLabel: type: string createdAt: type: string required: - id - type - priority - summary - timestamp - status - createdAt additionalProperties: false "404": description: Feed item not found "500": description: Failed to persist feed item status /v1/home/feed/{id}/actions/{actionId}: post: operationId: home_feed_by_id_actions_by_actionId_post summary: Trigger home feed action description: Create a new conversation pre-seeded with the action's prompt as the first user message. Returns the new `conversationId`. tags: - home parameters: - name: id in: path required: true schema: type: string - name: actionId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: conversationId: type: string required: - conversationId additionalProperties: false "404": description: Feed item or action not found "500": description: Failed to create conversation /v1/home/feed/mark-all: post: operationId: home_feed_markall_post summary: Bulk update home feed item statuses description: Flip every home feed item currently at one of the `from` statuses to the single `to` status. Returns the count of items whose status actually changed (items already at `to`, or outside `from`, are left untouched). Used to implement 'Mark all as read' (from=['new'], to='seen') and 'Clear all' (from=['new','seen','acted_on'], to='dismissed'). tags: - home requestBody: required: true content: application/json: schema: type: object properties: from: minItems: 1 type: array items: type: string enum: - new - seen - acted_on - dismissed to: type: string enum: - new - seen - acted_on - dismissed ids: type: array items: type: string required: - from - to responses: "200": description: Successful response content: application/json: schema: type: object properties: updatedCount: type: integer minimum: 0 maximum: 9007199254740991 updatedAt: type: string required: - updatedCount - updatedAt additionalProperties: false "500": description: Failed to persist bulk status update /v1/home/feed/query: post: operationId: home_feed_query_post summary: List home feed items with filters description: Return home feed items filtered by status, urgency, category, conversation, and date range. Defaults to excluding dismissed items. Used by the assistant CLI to inspect what notifications have been surfaced to the user. tags: - home requestBody: required: true content: application/json: schema: type: object properties: includeDismissed: type: boolean statuses: type: array items: type: string enum: - new - seen - acted_on - dismissed before: type: string after: type: string urgencies: type: array items: type: string enum: - low - medium - high - critical categories: type: array items: type: string enum: - security - scheduling - background - email - system conversationId: type: string fromAssistant: type: boolean noteworthy: type: boolean limit: type: integer exclusiveMinimum: 0 maximum: 200 offset: type: integer minimum: 0 maximum: 9007199254740991 responses: "200": description: Successful response content: application/json: schema: type: object properties: items: type: array items: type: object properties: id: type: string type: type: string const: notification priority: type: integer minimum: 0 maximum: 100 title: type: string summary: type: string timestamp: type: string status: default: new type: string enum: - new - seen - acted_on - dismissed expiresAt: type: string actions: type: array items: type: object properties: id: type: string label: type: string prompt: type: string required: - id - label - prompt additionalProperties: false urgency: type: string enum: - low - medium - high - critical conversationId: type: string detailPanel: type: object properties: kind: type: string enum: - emailDraft - documentPreview - permissionChat - paymentAuth - toolPermission - updatesList required: - kind additionalProperties: false category: type: string enum: - security - scheduling - background - email - system noteworthy: type: boolean fromAssistant: type: boolean metadata: type: object propertyNames: type: string additionalProperties: {} sourceType: type: string enum: - heartbeat - memory_consolidation - schedule - auto_analysis - user - other sourceKey: type: string sourceLabel: type: string createdAt: type: string required: - id - type - priority - summary - timestamp - status - createdAt additionalProperties: false total: type: integer minimum: 0 maximum: 9007199254740991 returned: type: integer minimum: 0 maximum: 9007199254740991 hasMore: type: boolean updatedAt: type: string required: - items - total - returned - hasMore - updatedAt additionalProperties: false /v1/home/state: get: operationId: home_state_get summary: Get relationship state description: Return the current `RelationshipState` snapshot. Reads the persisted `relationship-state.json` when present; falls back to an on-demand compute so fresh installs never see a 404. tags: - home responses: "200": description: Successful response content: application/json: schema: type: object properties: version: type: number const: 1 assistantId: type: string tier: anyOf: - type: number const: 1 - type: number const: 2 - type: number const: 3 - type: number const: 4 progressPercent: type: number facts: type: array items: type: object properties: id: type: string category: type: string enum: - voice - world - priorities text: type: string confidence: type: string enum: - strong - uncertain source: type: string enum: - onboarding - inferred required: - id - category - text - confidence - source additionalProperties: false capabilities: type: array items: type: object properties: id: type: string name: type: string description: type: string tier: type: string enum: - unlocked - next-up - earned gate: type: string unlockHint: type: string ctaLabel: type: string required: - id - name - description - tier - gate additionalProperties: false conversationCount: type: number hatchedDate: type: string assistantName: type: string userName: type: string updatedAt: type: string required: - version - assistantId - tier - progressPercent - facts - capabilities - conversationCount - hatchedDate - assistantName - updatedAt additionalProperties: false "500": description: Failed to compute relationship state /v1/host-app-control-result: post: operationId: hostappcontrolresult_post summary: Submit host app-control result description: Resolve a pending host app-control request by requestId. Returns 200 even when no pending interaction matches (late delivery is tolerated). tags: - host requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string minLength: 1 description: Pending app-control request ID state: type: string enum: - running - missing - minimized description: Lifecycle state of the targeted application pngBase64: type: string description: Base64 PNG screenshot of the targeted app window windowBounds: type: object properties: x: type: number y: type: number width: type: number height: type: number required: - x - y - width - height executionResult: type: string executionError: type: string required: - requestId - state responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false "400": description: x-vellum-client-id header is missing for a targeted host app-control request. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. /v1/host-bash-result: post: operationId: hostbashresult_post summary: Submit host bash result description: Resolve a pending host bash request by requestId. tags: - host requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string minLength: 1 description: Pending bash request ID stdout: type: string stderr: type: string exitCode: anyOf: - type: number - type: "null" description: Process exit status, or null when terminated by a signal timedOut: type: boolean required: - requestId responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false "400": description: x-vellum-client-id header is missing for a targeted host bash request. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. "404": description: No pending interaction found for the given requestId. "409": description: Pending interaction exists but is of a different kind (e.g. host_file, host_cu). /v1/host-browser-event: post: operationId: hostbrowserevent_post summary: Forward a CDP event from the browser extension description: Publishes a chrome.debugger.onEvent firing into the runtime-side browser-session event bus. tags: - host requestBody: required: true content: application/json: schema: type: object properties: method: type: string description: CDP event method name params: description: CDP event parameters cdpSessionId: description: CDP session ID (if target-scoped) type: string required: - method responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false /v1/host-browser-result: post: operationId: hostbrowserresult_post summary: Submit host browser result description: Resolve a pending host browser request by requestId. tags: - host requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string description: Pending browser request ID content: type: string isError: type: boolean required: - requestId responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false "400": description: x-vellum-client-id header is missing for a targeted host browser request. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. "404": description: No pending browser request for the given requestId. "409": description: Pending interaction kind is not host_browser (mismatched proxy ID space). /v1/host-browser-session-invalidated: post: operationId: hostbrowsersessioninvalidated_post summary: Notify runtime that a CDP session was invalidated description: Marks the target as invalidated in the runtime-side browser session registry. tags: - host requestBody: required: true content: application/json: schema: type: object properties: targetId: description: CDP target that was detached type: string reason: description: Detach reason type: string clientId: description: Extension client ID that reported the invalidation type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false /v1/host-cu-result: post: operationId: hostcuresult_post summary: Submit host CU result description: Resolve a pending host computer-use request by requestId. tags: - host requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string minLength: 1 description: Pending CU request ID axTree: type: string description: Accessibility tree axDiff: type: string description: Accessibility tree diff screenshot: type: string description: Base64 screenshot screenshotWidthPx: type: number screenshotHeightPx: type: number screenWidthPt: type: number screenHeightPt: type: number executionResult: type: string executionError: type: string secondaryWindows: type: string userGuidance: type: string required: - requestId responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false "400": description: x-vellum-client-id header is missing for a targeted host CU request. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. "404": description: No pending interaction found for the given requestId, or the conversation/proxy no longer exists. "409": description: Pending interaction exists but is of a different kind (e.g. host_bash, host_file). /v1/host-file-result: post: operationId: hostfileresult_post summary: Submit host file result description: Resolve a pending host file proxy request by requestId when the desktop client returns execution results. tags: - host-file requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string minLength: 1 description: Pending request ID to resolve content: type: string description: File content result isError: type: boolean description: Whether the result is an error imageData: type: string description: Optional base64-encoded image bytes for successful image reads audioData: type: string description: Optional base64-encoded audio bytes for successful audio reads audioMimeType: type: string description: MIME type for audioData (e.g. audio/mpeg) required: - requestId responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false "400": description: x-vellum-client-id header is missing for a targeted host file request. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. "404": description: No pending interaction found for the given requestId. "409": description: Pending interaction exists but is of a different kind (e.g. host_bash, host_cu). /v1/host-transfer-result: post: operationId: hosttransferresult_post summary: Submit host transfer result description: Resolve a pending to_host transfer after the client has downloaded and written the file. tags: - host-transfer requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string description: Pending transfer request ID isError: type: boolean bytesWritten: type: number errorMessage: type: string required: - requestId responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false "400": description: x-vellum-client-id header is missing for a targeted host transfer request. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. /v1/host-ui-snapshot-result: post: operationId: hostuisnapshotresult_post summary: Submit host UI-snapshot result description: Resolve a pending UI-snapshot request by requestId. Returns 200 even when no pending interaction matches (late delivery is tolerated). tags: - host requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string description: Pending UI-snapshot request ID pngBase64: type: string description: Base64 PNG capture of the staged view widthPx: type: number heightPx: type: number isError: type: boolean errorMessage: type: string required: - requestId responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false "400": description: x-vellum-client-id header is missing for a targeted UI-snapshot request. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. /v1/identity: get: operationId: identity_get summary: Get assistant identity description: Returns the assistant's identity fields parsed from IDENTITY.md. tags: - identity responses: "200": description: Successful response content: application/json: schema: type: object properties: name: type: string role: type: string personality: type: string emoji: type: string home: type: string version: type: string createdAt: type: string required: - name - role - personality - emoji - home - version additionalProperties: false /v1/image-generation/generate: post: operationId: imagegeneration_generate_post summary: Generate or edit images using AI description: Calls the configured image-generation provider (Gemini or OpenAI) to produce one or more images. tags: - image-generation requestBody: required: true content: application/json: schema: type: object properties: prompt: type: string mode: type: string enum: - generate - edit sourceImages: type: array items: type: object properties: mimeType: type: string dataBase64: type: string required: - mimeType - dataBase64 model: type: string variants: type: number required: - prompt responses: "200": description: Successful response content: application/json: schema: type: object properties: images: type: array items: type: object properties: mimeType: type: string dataBase64: type: string title: type: string required: - mimeType - dataBase64 additionalProperties: false text: type: string resolvedModel: type: string required: - images - resolvedModel additionalProperties: false /v1/inference/active-profile: put: operationId: inference_activeprofile_put summary: Set the active (chat) inference profile description: Set llm.activeProfile after validating the name against the effective profile catalog (provider-aware default expansion included). Unknown or disabled profiles are rejected so the chat-model selection cannot be silently stripped on the next config load. A profile that provably cannot dispatch is also rejected — there is no escape hatch, because an unusable active profile locks the user out of chat. tags: - inference requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 required: - name responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean const: true activeProfile: type: string required: - ok - activeProfile additionalProperties: false "400": description: Unknown or disabled profile name, or a profile that cannot serve requests /v1/inference/callsites: get: operationId: inference_callsites_get summary: List call-site resolutions description: "Return the effective resolution for every LLM call site: the winning profile, its source (override / active / call-site pin / shipped default), and the resolved provider/model plus notable tuning." tags: - inference responses: "200": description: Successful response content: application/json: schema: type: object properties: callSites: type: array items: $ref: "#/components/schemas/CallSiteResolutionSummary" required: - callSites additionalProperties: false /v1/inference/callsites/{site}: get: operationId: inference_callsites_by_site_get summary: Get a call-site resolution detail description: "Return the full resolution for one call site: the winner, the resolution chain (rungs considered and skipped), the shipped default fragment, the user's pin fragment, and a preflight-derived resolution error when dispatch would provably fail." tags: - inference parameters: - name: site in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/CallSiteResolutionDetail" "400": description: Unknown call site /v1/inference/chatgpt-subscription/auth: post: operationId: inference_chatgptsubscription_auth_post summary: Start ChatGPT subscription OAuth PKCE flow description: Generate a PKCE authorize URL for ChatGPT subscription auth. Returns the URL and state for the client to open in a browser. tags: - inference responses: "200": description: Successful response content: application/json: schema: type: object properties: authorize_url: type: string state: type: string required: - authorize_url - state additionalProperties: false /v1/inference/chatgpt-subscription/auth/exchange: post: operationId: inference_chatgptsubscription_auth_exchange_post summary: Exchange ChatGPT subscription OAuth authorization code description: Accept an authorization code and state from the OAuth redirect, exchange it for tokens, store them in CES, and upsert the provider connection. tags: - inference requestBody: required: true content: application/json: schema: type: object properties: code: type: string state: type: string required: - code - state responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/inference/models: get: operationId: inference_models_get summary: List inference catalog models description: Return every model in the code-owned provider catalog, each tagged with its provider. Optionally filter by provider with ?provider=. tags: - inference parameters: - name: provider in: query required: false schema: type: string description: "Filter by provider id. One of: anthropic, openai, gemini, ollama, fireworks, together, openrouter, vercel-ai-gateway, litellm, openai-compatible, minimax, atlascloud, baseten, poolside" responses: "200": description: Successful response content: application/json: schema: type: object properties: models: type: array items: $ref: "#/components/schemas/CatalogModel" required: - models additionalProperties: false "400": description: Unknown provider filter /v1/inference/profiles: get: operationId: inference_profiles_get summary: List effective inference profiles description: "Return the effective profile catalog: code-defined managed defaults merged with user profiles, each annotated with source and (when it has a connection) availability." tags: - inference responses: "200": description: Successful response content: application/json: schema: type: object properties: profiles: type: array items: $ref: "#/components/schemas/InferenceProfileSummary" required: - profiles additionalProperties: false post: operationId: inference_profiles_post summary: Create an inference profile description: Create a validated custom profile. The provider must be a known LLM provider, the model must be in the catalog (unless allowUnlisted), a referenced connection must exist, and the profile must be able to dispatch — a valid provider id with no credentialed connection behind it is rejected unless allowUnavailable is set, in which case it is created with a warning. tags: - inference requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 provider: type: string minLength: 1 model: type: string minLength: 1 connection: type: string minLength: 1 label: type: string minLength: 1 effort: type: string maxTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 temperature: type: number thinking: type: boolean description: type: string allowUnlisted: type: boolean allowUnavailable: type: boolean required: - name - provider - model responses: "201": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InferenceProfileWriteResult" "400": description: Invalid provider, uncataloged model, missing connection, or a profile that cannot serve requests "409": description: A profile with this name already exists /v1/inference/profiles/{name}: delete: operationId: inference_profiles_by_name_delete summary: Delete an inference profile description: Delete a custom profile. Managed default profiles cannot be deleted (they are re-seeded on boot). tags: - inference parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean const: true name: type: string required: - ok - name additionalProperties: false "400": description: Attempt to delete a managed profile "404": description: Profile not found "409": description: Profile is still referenced by activeProfile, advisorProfile, a call site, a default-tier override, or a mix arm get: operationId: inference_profiles_by_name_get summary: Get an effective inference profile description: Return a single effective profile by name, with availability. tags: - inference parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InferenceProfileDetail" "404": description: Profile not found patch: operationId: inference_profiles_by_name_patch summary: Update an inference profile description: Partial update of a custom profile with the same write-time validation as create. The dispatch-availability guard (and its allowUnavailable escape hatch) applies when the update changes provider, model, or connection; metadata-only edits skip it. Managed default profiles are read-only. tags: - inference parameters: - name: name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: provider: type: string minLength: 1 model: type: string minLength: 1 connection: type: string minLength: 1 label: type: string minLength: 1 effort: type: string maxTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 temperature: type: number thinking: type: boolean description: type: string allowUnlisted: type: boolean allowUnavailable: type: boolean responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/InferenceProfileWriteResult" "400": description: Invalid fields, a profile that cannot serve requests, or attempt to edit a managed profile "404": description: Profile not found /v1/inference/provider-connections: get: operationId: inference_providerconnections_get summary: List provider connections description: Return all provider connections. Optionally filter by provider with ?provider=. tags: - inference parameters: - name: provider in: query required: false schema: type: string description: "Filter by provider. One of: anthropic, openai, gemini, ollama, fireworks, together, openrouter, vercel-ai-gateway, litellm, openai-compatible, minimax, atlascloud, baseten, poolside, vellum, chatgpt" responses: "200": description: Successful response content: application/json: schema: type: object properties: connections: type: array items: $ref: "#/components/schemas/ProviderConnection" required: - connections additionalProperties: false post: operationId: inference_providerconnections_post summary: Create a provider connection description: Create a new named provider connection. When auth is omitted it is derived from the provider (keyless providers get none, vellum gets platform, everything else needs credential for api_key auth). An explicit auth object must agree with the provider; platform auth belongs to vellum and only to vellum. Fails with 409 if a connection with this name already exists. tags: - inference requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 provider: $ref: "#/components/schemas/ConnectionProvider" auth: $ref: "#/components/schemas/Auth" credential: type: string minLength: 1 label: type: string minLength: 1 base_url: anyOf: - type: string format: uri - type: "null" models: anyOf: - type: array items: $ref: "#/components/schemas/ConnectionModel" - type: "null" required: - name - provider responses: "201": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ProviderConnection" "400": description: Invalid provider or auth schema "409": description: Connection name already exists /v1/inference/provider-connections/{name}: delete: operationId: inference_providerconnections_by_name_delete summary: Delete a provider connection description: Delete a provider connection. Fails with 400 for the Vellum-managed connection (vellum) which is re-seeded on boot. Fails with 409 if any profile or call-site references the connection. tags: - inference parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean const: true required: - ok additionalProperties: false "400": description: Connection is a Vellum-managed connection and cannot be deleted "404": description: Connection not found "409": description: Connection is referenced by profile(s) or call site(s) get: operationId: inference_providerconnections_by_name_get summary: Get a provider connection description: Return a single provider connection by name. tags: - inference parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ProviderConnection" "404": description: Connection not found patch: operationId: inference_providerconnections_by_name_patch summary: Update a provider connection description: Update an existing connection. Cannot rename or change the provider. Omitting auth keeps the stored auth; passing credential alone rotates the key via provider-derived api_key auth. An explicit auth object must agree with the connection's provider; platform auth belongs to vellum and only to vellum. For the Vellum-managed connection (vellum) the auth is locked to platform; label remains editable. tags: - inference parameters: - name: name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: auth: $ref: "#/components/schemas/Auth" credential: type: string minLength: 1 label: anyOf: - type: string minLength: 1 - type: "null" base_url: anyOf: - type: string format: uri - type: "null" models: anyOf: - type: array items: $ref: "#/components/schemas/ConnectionModel" - type: "null" responses: "200": description: Successful response content: application/json: schema: $ref: "#/components/schemas/ProviderConnection" "400": description: Invalid auth schema, or attempt to change auth on a managed connection "404": description: Connection not found /v1/inference/send: post: operationId: inference_send_post summary: Send a message to the configured LLM description: Send a user message to the configured LLM provider and return the model response. Optionally specify a system prompt, model override, named profile, or max tokens. tags: - inference requestBody: required: true content: application/json: schema: type: object properties: message: type: string minLength: 1 systemPrompt: type: string model: type: string profile: type: string maxTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - message responses: "200": description: Successful response content: application/json: schema: type: object properties: response: type: string model: type: string usage: type: object properties: inputTokens: type: number outputTokens: type: number required: - inputTokens - outputTokens additionalProperties: false evidence: type: object properties: resolved_endpoint: type: string resolved_url: type: string model_id: type: string connection_name: type: string http_status: type: number upstream_error_body: type: string upstream_error_body_state: type: string enum: - captured - empty - truncated - unavailable upstream_error_body_bytes: type: number additionalProperties: false required: - response - model - usage additionalProperties: false /v1/integrations/a2a/config: delete: operationId: integrations_a2a_config_delete summary: Disable A2A channel description: Disable the A2A channel. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean enabled: type: boolean activeConnections: type: number error: type: string required: - success - enabled - activeConnections additionalProperties: false get: operationId: integrations_a2a_config_get summary: Get A2A config description: Check current A2A channel configuration status. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean enabled: type: boolean activeConnections: type: number error: type: string required: - success - enabled - activeConnections additionalProperties: false post: operationId: integrations_a2a_config_post summary: Enable A2A channel description: Enable the A2A channel for inter-assistant communication. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean enabled: type: boolean activeConnections: type: number error: type: string required: - success - enabled - activeConnections additionalProperties: false /v1/integrations/a2a/invite: post: operationId: integrations_a2a_invite_post summary: Create A2A invite description: Create a shareable A2A invite token for link-based contact creation. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean inviteId: type: string token: type: string expiresAt: type: number senderGatewayUrl: type: string error: type: string required: - success additionalProperties: false /v1/integrations/a2a/invite/accept: post: operationId: integrations_a2a_invite_accept_post summary: Accept A2A invite (self-hosted broker) description: Orchestrate cross-daemon invite acceptance for self-hosted deployments. Calls the sender's invite/complete, then creates a local contact via invite/redeem. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean contactId: type: string alreadyConnected: type: boolean error: type: string errorCode: type: string required: - success additionalProperties: false /v1/integrations/a2a/invite/complete: post: operationId: integrations_a2a_invite_complete_post summary: Complete A2A invite (sender side) description: Called by the platform to finalize the sender side of a link-based A2A connection. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean sender: type: object properties: assistantId: type: string displayName: type: string gatewayUrl: type: string required: - assistantId - displayName - gatewayUrl additionalProperties: false error: type: string required: - success additionalProperties: false /v1/integrations/a2a/invite/redeem: post: operationId: integrations_a2a_invite_redeem_post summary: Redeem A2A invite (receiver side) description: Called by the platform to create a trusted contact on the receiver side of a link-based A2A connection. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean contactId: type: string alreadyConnected: type: boolean error: type: string required: - success additionalProperties: false /v1/integrations/ingress/config: get: operationId: integrations_ingress_config_get summary: Get ingress config description: Return the current ingress tunnel configuration. tags: - config responses: "200": description: Successful response put: operationId: integrations_ingress_config_put summary: Update ingress config description: Set the ingress public base URL and enabled state. tags: - config requestBody: required: true content: application/json: schema: type: object properties: publicBaseUrl: type: string enabled: type: boolean required: - publicBaseUrl - enabled responses: "200": description: Successful response content: application/json: schema: type: object properties: enabled: type: boolean publicBaseUrl: type: string localGatewayTarget: type: string managedCallbacks: type: boolean success: type: boolean required: - enabled - publicBaseUrl - localGatewayTarget - success additionalProperties: false /v1/integrations/oauth/start: post: operationId: integrations_oauth_start_post summary: Start OAuth flow (legacy) description: Legacy alias for oauth/start. tags: - oauth requestBody: required: true content: application/json: schema: type: object properties: service: type: string requestedScopes: type: array items: {} required: - service - requestedScopes responses: "200": description: Successful response /v1/integrations/slack/channel/config: delete: operationId: integrations_slack_channel_config_delete summary: Clear Slack channel config description: Clear stored Slack channel credentials. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean hasAppToken: type: boolean hasUserToken: type: boolean connected: type: boolean teamId: type: string teamName: type: string teamUrl: type: string botUserId: type: string botUsername: type: string threadMode: type: string enum: - mention_only - mention_then_thread error: type: string warning: type: string required: - success - hasBotToken - hasAppToken - hasUserToken - connected - threadMode additionalProperties: false get: operationId: integrations_slack_channel_config_get summary: Get Slack channel config description: Check current Slack channel configuration status. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean hasAppToken: type: boolean hasUserToken: type: boolean connected: type: boolean teamId: type: string teamName: type: string teamUrl: type: string botUserId: type: string botUsername: type: string threadMode: type: string enum: - mention_only - mention_then_thread error: type: string warning: type: string required: - success - hasBotToken - hasAppToken - hasUserToken - connected - threadMode additionalProperties: false patch: operationId: integrations_slack_channel_config_patch summary: Update Slack channel settings description: Update Slack channel behavior settings (e.g. thread mode). tags: - integrations requestBody: required: true content: application/json: schema: type: object properties: threadMode: type: string enum: - mention_only - mention_then_thread description: Controls whether the bot follows threads after an initial @mention responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean hasAppToken: type: boolean hasUserToken: type: boolean connected: type: boolean teamId: type: string teamName: type: string teamUrl: type: string botUserId: type: string botUsername: type: string threadMode: type: string enum: - mention_only - mention_then_thread error: type: string warning: type: string required: - success - hasBotToken - hasAppToken - hasUserToken - connected - threadMode additionalProperties: false post: operationId: integrations_slack_channel_config_post summary: Set Slack channel config description: Validate and store Slack channel credentials. tags: - integrations requestBody: required: true content: application/json: schema: type: object properties: botToken: type: string description: Slack bot token appToken: type: string description: Slack app-level token required: - botToken - appToken responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean hasAppToken: type: boolean hasUserToken: type: boolean connected: type: boolean teamId: type: string teamName: type: string teamUrl: type: string botUserId: type: string botUsername: type: string threadMode: type: string enum: - mention_only - mention_then_thread error: type: string warning: type: string required: - success - hasBotToken - hasAppToken - hasUserToken - connected - threadMode additionalProperties: false /v1/integrations/telegram/commands: post: operationId: integrations_telegram_commands_post summary: Register Telegram commands description: Register bot commands with the Telegram API. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean botId: type: string botUsername: type: string connected: type: boolean hasWebhookSecret: type: boolean lastError: type: string error: type: string commandsRegistered: type: array items: type: string warning: type: string required: - success - hasBotToken - connected - hasWebhookSecret additionalProperties: false /v1/integrations/telegram/config: delete: operationId: integrations_telegram_config_delete summary: Clear Telegram config description: Clear credentials and deregister webhook. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean botId: type: string botUsername: type: string connected: type: boolean hasWebhookSecret: type: boolean lastError: type: string error: type: string commandsRegistered: type: array items: type: string warning: type: string required: - success - hasBotToken - connected - hasWebhookSecret additionalProperties: false get: operationId: integrations_telegram_config_get summary: Get Telegram config description: Check current Telegram bot configuration status. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean botId: type: string botUsername: type: string connected: type: boolean hasWebhookSecret: type: boolean lastError: type: string error: type: string commandsRegistered: type: array items: type: string warning: type: string required: - success - hasBotToken - connected - hasWebhookSecret additionalProperties: false post: operationId: integrations_telegram_config_post summary: Set Telegram config description: Set bot token and configure webhook. tags: - integrations requestBody: required: true content: application/json: schema: type: object properties: botToken: type: string description: Telegram bot token required: - botToken responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean botId: type: string botUsername: type: string connected: type: boolean hasWebhookSecret: type: boolean lastError: type: string error: type: string commandsRegistered: type: array items: type: string warning: type: string required: - success - hasBotToken - connected - hasWebhookSecret additionalProperties: false /v1/integrations/telegram/setup: post: operationId: integrations_telegram_setup_post summary: Setup Telegram description: "Composite: set config + register commands." tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasBotToken: type: boolean botId: type: string botUsername: type: string connected: type: boolean hasWebhookSecret: type: boolean lastError: type: string error: type: string commandsRegistered: type: array items: type: string warning: type: string required: - success - hasBotToken - connected - hasWebhookSecret additionalProperties: false /v1/integrations/twilio/config: get: operationId: integrations_twilio_config_get summary: Get Twilio config description: Return current Twilio configuration status. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasCredentials: type: boolean accountSid: type: string phoneNumber: type: string required: - success - hasCredentials additionalProperties: false /v1/integrations/twilio/credentials: delete: operationId: integrations_twilio_credentials_delete summary: Clear Twilio credentials description: Remove stored Twilio credentials. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasCredentials: type: boolean required: - success - hasCredentials additionalProperties: false post: operationId: integrations_twilio_credentials_post summary: Set Twilio credentials description: Validate and store Twilio account SID and auth token. tags: - integrations requestBody: required: true content: application/json: schema: type: object properties: accountSid: type: string description: Twilio account SID authToken: type: string description: Twilio auth token required: - accountSid - authToken responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasCredentials: type: boolean required: - success - hasCredentials additionalProperties: false /v1/integrations/twilio/numbers: get: operationId: integrations_twilio_numbers_get summary: List Twilio numbers description: List phone numbers on the Twilio account. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasCredentials: type: boolean numbers: type: array items: type: object properties: phoneNumber: type: string friendlyName: type: string capabilities: type: object properties: voice: type: boolean required: - voice additionalProperties: false required: - phoneNumber - friendlyName - capabilities additionalProperties: false required: - success - hasCredentials - numbers additionalProperties: false /v1/integrations/twilio/numbers/assign: post: operationId: integrations_twilio_numbers_assign_post summary: Assign Twilio number description: Assign an existing phone number to this assistant. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasCredentials: type: boolean phoneNumber: type: string warning: type: string required: - success - hasCredentials additionalProperties: false /v1/integrations/twilio/numbers/provision: post: operationId: integrations_twilio_numbers_provision_post summary: Provision Twilio number description: Search for and provision a new phone number. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasCredentials: type: boolean phoneNumber: type: string warning: type: string required: - success - hasCredentials additionalProperties: false /v1/integrations/twilio/numbers/release: post: operationId: integrations_twilio_numbers_release_post summary: Release Twilio number description: Release a phone number back to Twilio. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean hasCredentials: type: boolean phoneNumber: type: string warning: type: string required: - success - hasCredentials additionalProperties: false /v1/integrations/vercel/config: delete: operationId: integrations_vercel_config_delete summary: Delete Vercel config description: Delete the stored Vercel API token. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: hasToken: type: boolean success: type: boolean error: type: string required: - hasToken - success additionalProperties: false get: operationId: integrations_vercel_config_get summary: Get Vercel config description: Check if a Vercel API token is stored. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: hasToken: type: boolean success: type: boolean error: type: string required: - hasToken - success additionalProperties: false post: operationId: integrations_vercel_config_post summary: Set or delete Vercel config description: Set or delete the Vercel API token. Action is determined by the body action field. tags: - integrations requestBody: required: true content: application/json: schema: type: object properties: action: type: string enum: - get - set - delete apiToken: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: hasToken: type: boolean success: type: boolean error: type: string required: - hasToken - success additionalProperties: false /v1/internal/mcp/add: post: operationId: internal_mcp_add_post summary: Add an MCP server configuration description: Writes a new MCP server entry to config.json and triggers a reload. tags: - internal requestBody: required: true content: application/json: schema: type: object properties: name: type: string transportType: type: string url: type: string command: type: string args: type: array items: type: string risk: type: string disabled: type: boolean headers: type: object propertyNames: type: string additionalProperties: type: string required: - name - transportType responses: "200": description: Successful response /v1/internal/mcp/auth/revoke: post: operationId: internal_mcp_auth_revoke_post summary: Revoke MCP OAuth credentials description: Deletes stored OAuth tokens for an MCP server and triggers a reload. tags: - internal requestBody: required: true content: application/json: schema: type: object properties: serverId: type: string required: - serverId responses: "200": description: Successful response content: application/json: schema: type: object properties: revoked: type: boolean required: - revoked additionalProperties: false /v1/internal/mcp/auth/start: post: operationId: internal_mcp_auth_start_post summary: Start MCP OAuth flow description: Starts a daemon-owned MCP OAuth flow and returns the authorization URL for the CLI to open in the browser. tags: - internal requestBody: required: true content: application/json: schema: type: object properties: serverId: type: string required: - serverId responses: "200": description: Successful response /v1/internal/mcp/auth/status/{serverId}: get: operationId: internal_mcp_auth_status_by_serverId_get summary: Poll MCP OAuth flow status description: Returns the current status of an in-flight MCP OAuth flow (pending/complete/error). tags: - internal parameters: - name: serverId in: path required: true schema: type: string responses: "200": description: Successful response "404": description: No active OAuth flow for the given serverId /v1/internal/mcp/list: get: operationId: internal_mcp_list_get summary: List MCP servers with health status description: Returns configured MCP servers with live health-check results (connected, needs auth, error, disabled). tags: - internal responses: "200": description: Successful response content: application/json: schema: type: object properties: servers: type: array items: type: object properties: id: type: string status: type: string transport: type: object properties: type: type: string enum: - stdio - sse - streamable-http required: - type additionalProperties: {} enabled: type: boolean defaultRiskLevel: type: string hasOAuth: type: boolean allowedTools: type: array items: type: string blockedTools: type: array items: type: string required: - id - status - transport - enabled - defaultRiskLevel - hasOAuth additionalProperties: false required: - servers additionalProperties: false /v1/internal/mcp/reload: post: operationId: internal_mcp_reload_post summary: Trigger MCP server reload description: Kicks off reloadMcpServers() async on the daemon. Returns immediately. tags: - internal responses: "200": description: Successful response /v1/internal/mcp/remove: post: operationId: internal_mcp_remove_post summary: Remove an MCP server configuration description: Removes an MCP server from config.json, cleans up OAuth credentials, and triggers a reload. tags: - internal requestBody: required: true content: application/json: schema: type: object properties: name: type: string required: - name responses: "200": description: Successful response /v1/internal/mcp/tools-summary: get: operationId: internal_mcp_toolssummary_get summary: Per-server MCP tool counts and token estimates description: Returns registered tool counts, individual tool details, and estimated token overhead for each connected MCP server. tags: - internal responses: "200": description: Successful response content: application/json: schema: type: object properties: servers: type: array items: type: object properties: serverId: type: string toolCount: type: number estimatedTokens: type: number tools: type: array items: type: object properties: name: type: string description: type: string estimatedTokens: type: number required: - name - description - estimatedTokens additionalProperties: false required: - serverId - toolCount - estimatedTokens - tools additionalProperties: false totalToolCount: type: number totalEstimatedTokens: type: number required: - servers - totalToolCount - totalEstimatedTokens additionalProperties: false /v1/internal/mcp/update: post: operationId: internal_mcp_update_post summary: Update an MCP server configuration description: Updates fields on an existing MCP server config entry and triggers a reload. tags: - internal requestBody: required: true content: application/json: schema: type: object properties: name: type: string enabled: type: boolean defaultRiskLevel: type: string maxTools: type: number allowedTools: anyOf: - type: array items: type: string - type: "null" blockedTools: anyOf: - type: array items: type: string - type: "null" headers: anyOf: - type: object propertyNames: type: string additionalProperties: type: string - type: "null" required: - name responses: "200": description: Successful response /v1/internal/oauth/callback: post: operationId: internal_oauth_callback_post summary: Internal OAuth callback description: Receives forwarded OAuth callback results (code or error) from the gateway and resolves the pending callback in the runtime. tags: - internal requestBody: required: true content: application/json: schema: type: object properties: state: type: string code: type: string error: type: string required: - state responses: "200": description: Successful response /v1/internal/oauth/connect/start: post: operationId: internal_oauth_connect_start_post summary: Start daemon-owned OAuth connect flow description: Starts an OAuth connect flow in the daemon and returns the authorization URL for the CLI to open in the browser. tags: - internal requestBody: required: true content: application/json: schema: type: object properties: service: type: string clientId: type: string clientSecret: type: string callbackTransport: type: string enum: - loopback - gateway requestedScopes: type: array items: type: string required: - service - callbackTransport responses: "200": description: Successful response /v1/internal/oauth/connect/status/{state}: get: operationId: internal_oauth_connect_status_by_state_get summary: Poll daemon OAuth connect flow status description: Returns the current status of an in-flight daemon-owned OAuth connect flow (pending/complete/error). tags: - internal parameters: - name: state in: path required: true schema: type: string responses: "200": description: Successful response "404": description: No active OAuth connect flow for the given state token /v1/internal/telemetry/auth-fallback: post: operationId: internal_telemetry_authfallback_post summary: Record auth-fallback counts description: Receives aggregated legacy-loopback auth-fallback counts forwarded by the gateway and persists them for telemetry reporting. tags: - internal - telemetry requestBody: required: true content: application/json: schema: type: object properties: window_start: type: integer minimum: 0 maximum: 9007199254740991 window_end: type: integer minimum: 0 maximum: 9007199254740991 counts: minItems: 1 type: array items: type: object properties: guard: type: string minLength: 1 path: type: string minLength: 1 failure_kind: type: string minLength: 1 count: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - guard - path - failure_kind - count required: - window_start - window_end - counts responses: "200": description: Successful response content: application/json: schema: anyOf: - type: object properties: recorded: type: integer minimum: 0 maximum: 9007199254740991 required: - recorded additionalProperties: false - type: object properties: skipped: type: boolean const: true description: Counts dropped because usage data collection is disabled required: - skipped additionalProperties: false /v1/internal/telemetry/watchdog: post: operationId: internal_telemetry_watchdog_post summary: Relay a watchdog telemetry event description: Emits a gateway-origin watchdog telemetry event directly to platform ingest, bypassing the SQLite watchdog buffer, so integrity alarms never depend on the state they report on. tags: - internal - telemetry requestBody: required: true content: application/json: schema: type: object properties: check_name: type: string minLength: 1 maxLength: 128 detail: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" value: anyOf: - type: number - type: "null" required: - check_name responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean const: true required: - ok additionalProperties: false /v1/internal/twilio/status: post: operationId: internal_twilio_status_post summary: Internal Twilio status callback description: Gateway-to-runtime forwarding for Twilio call status updates. Accepts pre-parsed form params as JSON. tags: - internal responses: "200": description: Successful response /v1/internal/twilio/voice-webhook: post: operationId: internal_twilio_voicewebhook_post summary: Internal Twilio voice webhook description: Gateway-to-runtime forwarding for Twilio voice webhook. Accepts pre-parsed form params as JSON. tags: - internal responses: "200": description: Successful response /v1/lifecycle/drain-status: get: operationId: lifecycle_drainstatus_get summary: In-flight background work description: "Reports conversation turns, memory jobs, schedule runs, workflow runs, and heartbeat runs currently in flight, plus the active quiesce lease. `idle: true` means it is safe to stop the assistant without interrupting work." tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: quiescedUntil: anyOf: - type: number - type: "null" idle: type: boolean description: True when no conversation turn, memory job, schedule run, workflow run, or heartbeat run is in flight. activeConversations: type: array items: type: object properties: conversationId: type: string title: anyOf: - type: string - type: "null" originChannel: anyOf: - type: string - type: "null" originInterface: anyOf: - type: string - type: "null" processingStartedAt: type: number required: - conversationId - title - originChannel - originInterface - processingStartedAt additionalProperties: false memoryJobs: type: array items: type: object properties: id: type: string type: type: string startedAt: anyOf: - type: number - type: "null" required: - id - type - startedAt additionalProperties: false scheduleRuns: type: array items: type: object properties: runId: type: string scheduleName: anyOf: - type: string - type: "null" startedAt: type: number required: - runId - scheduleName - startedAt additionalProperties: false workflowRuns: type: array items: type: object properties: runId: type: string name: anyOf: - type: string - type: "null" startedAt: anyOf: - type: number - type: "null" required: - runId - name - startedAt additionalProperties: false heartbeatRuns: type: array items: type: object properties: runId: type: string startedAt: type: number required: - runId - startedAt additionalProperties: false required: - quiescedUntil - idle - activeConversations - memoryJobs - scheduleRuns - workflowRuns - heartbeatRuns additionalProperties: false /v1/lifecycle/quiesce: delete: operationId: lifecycle_quiesce_delete summary: Release the drain quiesce lease description: Resumes background work immediately instead of waiting for the lease TTL to expire (e.g. when a drain is cancelled). tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: released: type: boolean required: - released additionalProperties: false post: operationId: lifecycle_quiesce_post summary: Arm or refresh the drain quiesce lease description: Pauses the starting of new background work (heartbeat, schedules, watchers, sequences, memory jobs) for the lease TTL. Refresh by calling again; the lease self-expires so an abandoned drain never leaves background work paused. tags: - system requestBody: required: true content: application/json: schema: type: object properties: ttlMs: description: Lease TTL in ms (clamped to a sane range). type: number responses: "200": description: Successful response content: application/json: schema: type: object properties: quiescedUntil: type: number description: Epoch ms when the quiesce lease expires. required: - quiescedUntil additionalProperties: false /v1/live-voice/preflight: post: operationId: livevoice_preflight_post summary: Live voice preflight description: Ensure managed speech defaulting has run, then report whether live voice can start. tags: - live-voice responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - ready - not-ready missing: type: array items: type: object properties: kind: type: string enum: - stt - tts providerId: type: string reason: type: string required: - kind - providerId - reason additionalProperties: false userMessage: type: string required: - status additionalProperties: false /v1/llm-request-logs/{id}/context: get: operationId: llmrequestlogs_by_id_context_get summary: Get normalized context for a single LLM request log description: Return the normalized summary and request/response sections for a specific log entry. tags: - messages parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string createdAt: type: number requestPayload: type: "null" responsePayload: type: "null" provider: anyOf: - type: string - type: "null" summary: anyOf: - type: object properties: provider: anyOf: - type: string - type: "null" model: anyOf: - type: string - type: "null" status: anyOf: - type: string - type: "null" inputTokens: anyOf: - type: number - type: "null" outputTokens: anyOf: - type: number - type: "null" cacheCreationInputTokens: anyOf: - type: number - type: "null" cacheReadInputTokens: anyOf: - type: number - type: "null" stopReason: anyOf: - type: string - type: "null" requestMessageCount: anyOf: - type: number - type: "null" requestToolCount: anyOf: - type: number - type: "null" responseMessageCount: anyOf: - type: number - type: "null" responseToolCallCount: anyOf: - type: number - type: "null" responsePreview: anyOf: - type: string - type: "null" toolCallNames: anyOf: - type: array items: type: string - type: "null" estimatedCostUsd: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" additionalProperties: false - type: "null" requestSections: anyOf: - type: array items: type: object properties: kind: type: string label: anyOf: - type: string - type: "null" role: anyOf: - type: string - type: "null" text: anyOf: - type: string - type: "null" toolName: anyOf: - type: string - type: "null" data: {} language: anyOf: - type: string - type: "null" required: - kind additionalProperties: false - type: "null" responseSections: anyOf: - type: array items: type: object properties: kind: type: string label: anyOf: - type: string - type: "null" role: anyOf: - type: string - type: "null" text: anyOf: - type: string - type: "null" toolName: anyOf: - type: string - type: "null" data: {} language: anyOf: - type: string - type: "null" required: - kind additionalProperties: false - type: "null" agentLoopExitReason: anyOf: - type: string - type: "null" callSite: anyOf: - type: string - type: "null" error: anyOf: - type: object properties: name: anyOf: - type: string - type: "null" message: anyOf: - type: string - type: "null" code: anyOf: - type: string - type: "null" provider: anyOf: - type: string - type: "null" statusCode: anyOf: - type: number - type: "null" retryAfterMs: anyOf: - type: number - type: "null" apiErrorCode: anyOf: - type: string - type: "null" apiErrorType: anyOf: - type: string - type: "null" apiErrorParam: anyOf: - type: string - type: "null" requestId: anyOf: - type: string - type: "null" additionalProperties: false - type: "null" latency: anyOf: - type: object properties: phases: type: array items: type: object properties: key: type: string label: type: string ms: type: number subPhases: type: array items: type: object properties: key: type: string label: type: string ms: type: number required: - key - label - ms additionalProperties: false required: - key - label - ms additionalProperties: false ttftMs: anyOf: - type: number - type: "null" totalToFirstTokenMs: anyOf: - type: number - type: "null" providerDurationMs: anyOf: - type: number - type: "null" firstTokenKind: anyOf: - type: string enum: - thinking - text - type: "null" required: - phases additionalProperties: false - type: "null" required: - id - createdAt - requestPayload - responsePayload additionalProperties: false /v1/llm-request-logs/{id}/payload: get: operationId: llmrequestlogs_by_id_payload_get summary: Get raw payload for a single LLM request log description: Return the full request and response payloads for a specific log entry. tags: - messages parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string requestPayload: {} responsePayload: {} required: - id - requestPayload - responsePayload additionalProperties: false /v1/logs/export: post: operationId: logs_export_post summary: Export logs and audit data (alias) description: Alias for /v1/export. Export audit records, assistant logs, and config as a tar.gz archive. tags: - export requestBody: required: true content: application/json: schema: type: object properties: auditLimit: description: Max audit records (default 1000) type: integer minimum: -9007199254740991 maximum: 9007199254740991 conversationId: description: Scope to a single conversation type: string full: description: Full export — include messages, LLM request logs, and usage events for all conversations. type: boolean startTime: description: Lower bound epoch ms type: number endTime: description: Upper bound epoch ms type: number responses: "200": description: Successful response content: application/gzip: schema: type: string format: binary "500": description: Failed to create archive /v1/memory-graph: get: operationId: memorygraph_get summary: Get the memory graph description: Return the assistant's memory as a backend-agnostic graph of nodes (concepts, skills, capabilities) and edges (authored links and learned associations). Returns supported=false when the active backend exposes no graph. tags: - memory responses: "200": description: Successful response content: application/json: schema: type: object properties: backend: anyOf: - type: string - type: "null" supported: type: boolean nodes: type: array items: type: object properties: id: type: string label: type: string summary: type: string kind: type: string weight: type: number updatedAtMs: type: number required: - id - label additionalProperties: false edges: type: array items: type: object properties: source: type: string target: type: string kind: type: string weight: type: number description: type: string directed: type: boolean required: - source - target additionalProperties: false truncated: type: boolean required: - backend - supported - nodes - edges additionalProperties: false /v1/memory-graph-node: get: operationId: memorygraphnode_get summary: Get a memory graph node's content description: "Return the rendered markdown content of a single concept node by id, for the graph's node-detail view. `found: false` when the node has no readable page." tags: - memory parameters: - name: id in: query required: false schema: type: string description: "Node id from the graph payload (memory-v3: the concept-page slug)." responses: "200": description: Successful response content: application/json: schema: type: object properties: found: type: boolean title: type: string content: type: string required: - found additionalProperties: false /v1/memory-items: get: operationId: memoryitems_get summary: List memory items description: Return memory items with filtering, search, sorting, and pagination. tags: - memory parameters: - name: kind in: query required: false schema: type: string description: Filter by kind - name: status in: query required: false schema: type: string description: Filter by status (default active) - name: search in: query required: false schema: type: string description: Full-text search query - name: sort in: query required: false schema: type: string description: Sort field (default lastSeenAt) - name: order in: query required: false schema: type: string description: asc or desc (default desc) - name: limit in: query required: false schema: type: integer description: Max results (default 100) - name: offset in: query required: false schema: type: integer description: Pagination offset responses: "200": description: Successful response content: application/json: schema: type: object properties: items: type: array items: {} description: Memory item objects total: type: number required: - items - total additionalProperties: false post: operationId: memoryitems_post summary: Create a memory item description: Create a new memory graph node and enqueue embedding. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: kind: type: string description: Memory type (episodic, semantic, procedural, etc.) subject: type: string description: Subject line (first line of content) statement: type: string description: Statement content importance: type: number description: Importance score (default 0.8) required: - kind - statement responses: "201": description: Successful response content: application/json: schema: type: object properties: item: type: object properties: {} additionalProperties: {} description: Created memory item required: - item additionalProperties: false "409": description: A memory with this content already exists /v1/memory-items/{id}: delete: operationId: memoryitems_by_id_delete summary: Delete a memory item description: Delete a memory graph node and its embeddings. tags: - memory parameters: - name: id in: path required: true schema: type: string responses: "204": description: Successful response get: operationId: memoryitems_by_id_get summary: Get a memory item description: Return a single memory item by ID with graph metadata. tags: - memory parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: item: type: object properties: {} additionalProperties: {} description: Memory item with graph metadata required: - item additionalProperties: false patch: operationId: memoryitems_by_id_patch summary: Update a memory item description: Partially update fields on an existing memory graph node. tags: - memory parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: subject: type: string statement: type: string kind: type: string status: type: string importance: type: number responses: "200": description: Successful response content: application/json: schema: type: object properties: item: type: object properties: {} additionalProperties: {} description: Updated memory item required: - item additionalProperties: false "409": description: Another memory item with this content already exists /v1/memory-nodes: get: operationId: memorynodes_get summary: List memory graph nodes description: Return active memory graph nodes ordered by significance. With `search`, all nodes are scanned so the content filter is exhaustive; without it the query is capped at `limit` rows. tags: - memory parameters: - name: search in: query required: false schema: type: string description: Filter nodes whose content contains the query - name: limit in: query required: false schema: type: integer description: Max results (default 50, max 200) - name: kind in: query required: false schema: type: string enum: - skill - cli description: "Restrict to auto-seeded capability nodes: 'skill' or 'cli'" responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean message: type: string nodes: type: array items: type: object properties: id: type: string content: type: string type: type: string fidelity: type: string created: type: number required: - id - content - type - fidelity - created additionalProperties: false total: type: number required: - success - message - nodes - total additionalProperties: false /v1/memory-nodes/delete: post: operationId: memorynodes_delete_post summary: Delete a memory graph node by content match description: "Delete the single memory graph node matching `content`: a case-insensitive exact match takes priority; with no exact match, a substring match is tried. Fails as `{ success: false }` when zero or multiple nodes match." tags: - memory requestBody: required: true content: application/json: schema: type: object properties: content: type: string required: - content responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success - message additionalProperties: false /v1/memory-nodes/update: post: operationId: memorynodes_update_post summary: Update a memory graph node by content match description: "Replace the content of the single memory graph node matching `oldContent`: a case-insensitive exact match takes priority; with no exact match, a substring match is tried. Fails as `{ success: false }` when zero or multiple nodes match, or when another active node already has `newContent`." tags: - memory requestBody: required: true content: application/json: schema: type: object properties: oldContent: type: string newContent: type: string required: - oldContent - newContent responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean message: type: string required: - success - message additionalProperties: false /v1/memory/eval/run: post: operationId: memory_eval_run_post summary: Build blinded A/B retrieval-eval packets over two concept corpora (snapshot vs staged wiki) tags: - memory requestBody: required: true content: application/json: schema: type: object properties: stagingDir: type: string minLength: 1 snapshotDir: type: string minLength: 1 outDir: type: string minLength: 1 turns: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 perConversationCap: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 k: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 dense: type: boolean seed: type: integer minimum: -9007199254740991 maximum: 9007199254740991 turnIds: type: array items: type: string excludeConversationIds: type: array items: type: string required: - stagingDir - snapshotDir - outDir responses: "200": description: Successful response content: application/json: schema: type: object properties: turnsMined: type: number turnsRequested: type: number packetsWritten: type: number packetsPath: type: string keyPath: type: string metaPath: type: string snapshotPages: type: number stagingPages: type: number dense: type: boolean seed: type: number k: type: number embedding: type: object properties: provider: type: string model: type: string dims: anyOf: - type: number - type: "null" required: - provider - model - dims additionalProperties: false turnIds: type: array items: type: string required: - turnsMined - turnsRequested - packetsWritten - packetsPath - keyPath - metaPath - snapshotPages - stagingPages - dense - seed - k - embedding - turnIds additionalProperties: false /v1/memory/eval/tally: post: operationId: memory_eval_tally_post summary: Unblind + tally blind-judge verdicts against the key with a noise-aware win/tie/loss verdict tags: - memory requestBody: required: true content: application/json: schema: type: object properties: verdicts: type: array items: type: object properties: turn: type: string winner: type: string scoreA: type: number scoreB: type: number required: - turn - scoreA - scoreB key: type: array items: type: object properties: turn: type: string a: type: string enum: - snapshot - staging b: type: string enum: - snapshot - staging required: - turn - a - b alpha: type: number exclusiveMinimum: 0 required: - verdicts - key responses: "200": description: Successful response content: application/json: schema: type: object properties: turns: type: number verdictsCounted: type: number unmatchedVerdicts: type: number panel: type: object properties: min: type: number max: type: number mean: type: number required: - min - max - mean additionalProperties: false snapshotWins: type: number stagingWins: type: number ties: type: number decided: type: number meanSnapshot: type: number meanStaging: type: number signTestP: type: number verdict: type: string enum: - wiki-wins - tie - wiki-loses gate: type: string enum: - pass - fail confident: type: boolean notes: type: array items: type: string required: - turns - verdictsCounted - unmatchedVerdicts - panel - snapshotWins - stagingWins - ties - decided - meanSnapshot - meanStaging - signTestP - verdict - gate - confident - notes additionalProperties: false /v1/memory/ingest: post: operationId: memory_ingest_post summary: Batch-ingest fully-formed concept pages directly into memory/concepts/ (bypassing the consolidation buffer) and enqueue reindex jobs tags: - memory requestBody: required: true content: application/json: schema: type: object properties: pages: minItems: 1 maxItems: 200 type: array items: type: object properties: slug: type: string content: type: string required: - slug - content dryRun: type: boolean overwrite: type: boolean required: - pages responses: "200": description: Successful response content: application/json: schema: type: object properties: results: type: array items: type: object properties: slug: type: string action: type: string enum: - written - skipped_exists - invalid warnings: type: array items: type: string error: type: string required: - slug - action - warnings additionalProperties: false written: type: number skipped: type: number invalid: type: number dryRun: type: boolean required: - results - written - skipped - invalid - dryRun additionalProperties: false /v1/memory/remember: post: operationId: memory_remember_post summary: Create a memory by remembering a fact description: Append a user-authored fact to the memory buffer via handleRemember. The fact surfaces in the memory graph immediately as a pending node (its id is returned so clients can navigate to it), and a consolidation run is nudged (deduped, backoff-respecting) so it files into concept pages promptly. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: content: type: string required: - content responses: "200": description: Successful response content: application/json: schema: type: object properties: message: type: string success: type: boolean pendingNodeId: description: Graph node id (`buffer:`) of the pending entry this create appended, for fly-to-node navigation. Absent when the buffer can't be re-read. type: string required: - message - success additionalProperties: false /v1/memory/stats: get: operationId: memory_stats_get summary: Get lightweight memory stats description: "Return a cheap count of concept pages from the cached memory page index, for glanceable surfaces like the identity Memory card. Counts concept pages only and never builds the memory-concept graph. Also reports graph_supported: whether the memory-concept graph is available for this assistant (memory enabled and v3 live), so callers can gate the graph entry point without building the graph, plus tier: the coarse memory tier explaining why the graph is unavailable (off = the user's Memory opt-out, v1/v2 = a legacy engine that has not migrated to v3)." tags: - memory responses: "200": description: Successful response content: application/json: schema: type: object properties: concepts: type: number description: Number of concept pages in memory graph_supported: type: boolean description: Whether the memory-concept graph is available (memory enabled and v3 live) tier: type: string enum: - off - v1 - v2 - v3 description: Coarse memory tier for this assistant; graph_supported is exactly tier === 'v3' required: - concepts - graph_supported - tier additionalProperties: false /v1/memory/v2/backfill: post: operationId: memory_v2_backfill_post summary: Enqueue a memory v2 backfill job description: Enqueues one of four operator-triggered backfill jobs (migrate, rebuild-edges, reembed, activation-recompute) against the memory jobs queue. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: op: type: string enum: - migrate - reembed - activation-recompute force: type: boolean required: - op additionalProperties: false responses: "200": description: Successful response /v1/memory/v2/compare-retrievers: post: operationId: memory_v2_compareretrievers_post summary: Compare retrievers against the router's logged selections (read-only) description: Runs one or more retrievers over a sample of historical turns (memory_v2_activation_logs, mode='router') and scores their selected pages against the logged selections as ground truth, reconstructing each turn's inputs from the messages table + current NOW. Read-only — writes nothing. Each scored turn re-runs the router (one LLM call), so keep `limit` modest. Today the only retriever is the router itself, so this is the harness self-test. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: limit: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 strategy: type: string enum: - recent - random conversationIds: type: array items: type: string minLength: 1 ks: type: array items: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 includeNotInjected: type: boolean additionalProperties: false responses: "200": description: Successful response /v1/memory/v2/concept-frequency: post: operationId: memory_v2_conceptfrequency_post summary: Aggregate per-concept injection frequency from activation logs description: "Debug-only. Aggregates the existing memory_v2_activation_logs table by (slug, status) and cross-references on-disk concept pages so an operator can see which concepts get injected often, which get scored but rejected, and which on-disk pages never even surface as candidates. Optional filters: conversationId narrows to a single conversation; sinceMs restricts to logs created at-or-after the given epoch ms timestamp." tags: - memory requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 sinceMs: type: integer minimum: 0 maximum: 9007199254740991 additionalProperties: false responses: "200": description: Successful response /v1/memory/v2/concept-page: post: operationId: memory_v2_conceptpage_post summary: Read a single memory v2 concept page description: Returns the rendered (frontmatter + body) markdown for a slug. 404 when the slug has no on-disk page — the activation log inspector uses this to show what got injected. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: slug: type: string minLength: 1 required: - slug additionalProperties: false responses: "200": description: Successful response /v1/memory/v2/ema-scores: post: operationId: memory_v2_emascores_post summary: List every concept page with its injection-frequency EMA score description: Computes the time-decayed injection frequency (3-day half-life) for every entry in the current page index by reading memory_v2_injection_events. Returns entries sorted by score descending then slug ASCII, including zero-score pages so callers can decide whether to filter. Read-only; tier 2 of the v4 router uses the same computation to pick its top-M. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: {} additionalProperties: false responses: "200": description: Successful response /v1/memory/v2/list-concept-pages: post: operationId: memory_v2_listconceptpages_post summary: List all memory v2 concept pages with metadata description: Returns slugs, body sizes, edge counts, and last-modified timestamps for every concept page on disk. Read-only; used by the desktop About → Memories surface to render a browse-able list. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: {} additionalProperties: false responses: "200": description: Successful response content: application/json: schema: type: object properties: pages: type: array items: type: object properties: slug: type: string bodyBytes: type: number edgeCount: type: number updatedAtMs: type: number required: - slug - bodyBytes - edgeCount - updatedAtMs additionalProperties: false required: - pages additionalProperties: false /v1/memory/v2/now-text: get: operationId: memory_v2_nowtext_get summary: Return the current rendered `` body description: Returns the current NOW.md (autoloaded essentials/threads/recent). Used by the memory router playground to seed its `` text area with a production-like default so callers can edit from a realistic baseline. tags: - memory responses: "200": description: Successful response content: application/json: schema: type: object properties: nowText: type: string required: - nowText additionalProperties: false /v1/memory/v2/reembed-skills: post: operationId: memory_v2_reembedskills_post summary: Re-seed v2 skill entries from the current skill catalog description: Synchronously re-runs seedV2SkillEntries against the current skill catalog. Gated on concept-page memory being active. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: {} additionalProperties: false responses: "200": description: Successful response /v1/memory/v2/router-prompt-template: get: operationId: memory_v2_routerprompttemplate_get summary: Return the bundled router system-prompt template description: Returns the bundled `ROUTER_PROMPT` body with placeholders intact (`{{ASSISTANT_NAME}}`, `{{USER_NAME}}`, `{{PAGE_INDEX}}`). Used by the memory router playground's 'Load default' affordance so users have a known-good starting point when authoring an inline prompt override. tags: - memory responses: "200": description: Successful response content: application/json: schema: type: object properties: template: type: string required: - template additionalProperties: false /v1/memory/v2/simulate-router: post: operationId: memory_v2_simulaterouter_post summary: Dry-run the v4 router with config overrides (read-only) description: Runs the memory router against the live page index + EMA scores with optional tier_size / batch_size overrides, without recording an injection event or writing an activation log. Returns the slugs that would have been selected, per-slug tier provenance, EMA scores, and the effective router config so operators can validate knob changes before flipping them in workspace config. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: recentTurnPairs: minItems: 1 type: array items: type: object properties: assistantMessage: type: string userMessage: type: string required: - assistantMessage - userMessage additionalProperties: false nowText: type: string configOverrides: type: object properties: tier1_size: anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" tier2_size: anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" batch_size: anyOf: - type: integer minimum: 1 maximum: 9007199254740991 - type: "null" additionalProperties: false profileOverride: type: string minLength: 1 routerPromptOverride: type: string maxLength: 1000000 required: - recentTurnPairs additionalProperties: false responses: "200": description: Successful response content: application/json: schema: type: object properties: selectedSlugs: type: array items: type: string sourceBySlug: type: object propertyNames: type: string additionalProperties: type: string scores: type: object propertyNames: type: string additionalProperties: type: number failureReason: anyOf: - type: string - type: "null" effectiveConfig: type: object properties: tier1_size: anyOf: - type: number - type: "null" tier2_size: anyOf: - type: number - type: "null" batch_size: anyOf: - type: number - type: "null" max_page_ids: type: number required: - tier1_size - tier2_size - batch_size - max_page_ids additionalProperties: false overrides: type: object properties: tier1_size: anyOf: - type: number - type: "null" tier2_size: anyOf: - type: number - type: "null" batch_size: anyOf: - type: number - type: "null" additionalProperties: false totalCandidatePages: type: number profileOverride: anyOf: - type: string - type: "null" routerPromptOverridden: type: boolean required: - selectedSlugs - sourceBySlug - scores - failureReason - effectiveConfig - overrides - totalCandidatePages - profileOverride - routerPromptOverridden additionalProperties: false /v1/memory/v2/validate: post: operationId: memory_v2_validate_post summary: Validate memory v2 workspace state description: Read-only structural validation of the v2 workspace — reports orphan edges, oversized pages, and parse failures. Runnable regardless of memory.v2.enabled so operators can dry-run validation before flipping the flag. tags: - memory requestBody: required: true content: application/json: schema: type: object properties: {} additionalProperties: false responses: "200": description: Successful response /v1/memory/v3/backfill-sections: post: operationId: memory_v3_backfillsections_post summary: "One-time: embed every page's sections (incl synthetic skill/CLI rows) into the dense store" tags: - memory responses: "200": description: Successful response content: application/json: schema: type: object properties: articles: type: number sections: type: number failures: type: number required: - articles - sections - failures additionalProperties: false /v1/memory/v3/rebuild-index: post: operationId: memory_v3_rebuildindex_post summary: Invalidate the v3 lanes so the next turn rebuilds tags: - memory responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean const: true required: - ok additionalProperties: false /v1/memory/worker/start: post: operationId: memory_worker_start_post summary: Start the memory worker description: Spawns (or reuses) the memory worker process as a child of the daemon. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: pid: type: number alreadyRunning: type: boolean pidPath: type: string required: - pid - alreadyRunning - pidPath additionalProperties: false /v1/memory/worker/status: get: operationId: memory_worker_status_get summary: Memory worker status description: Reports the memory worker process liveness and the embedding-backend status (including a degraded flag and reason when no backend resolves). tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - running - not_running pid: type: number embedding: type: object properties: enabled: type: boolean degraded: type: boolean provider: anyOf: - type: string enum: - local - openai - gemini - ollama - type: "null" model: anyOf: - type: string - type: "null" reason: anyOf: - type: string - type: "null" required: - enabled - degraded - provider - model - reason additionalProperties: false required: - status - embedding additionalProperties: false /v1/memory/worker/stop: post: operationId: memory_worker_stop_post summary: Stop the memory worker description: SIGTERMs the memory worker process if it is running. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: workerWasRunning: type: boolean pid: type: number required: - workerWasRunning additionalProperties: false /v1/messages: get: operationId: messages_get summary: List messages description: Return messages for a conversation, including attachments and interface file metadata. tags: - messages parameters: - name: conversationId in: query required: false schema: type: string description: Conversation UUID. One of conversationId or conversationKey is required. - name: conversationKey in: query required: false schema: type: string description: Channel/external conversation key. One of conversationId or conversationKey is required. - name: page in: query required: false schema: type: string description: When set to 'latest', returns the most recent page of messages with pagination metadata. - name: beforeTimestamp in: query required: false schema: type: integer description: Return messages older than this timestamp (ms since epoch). Used for paging older history. - name: limit in: query required: false schema: type: integer description: Maximum number of messages to return. responses: "200": description: Successful response content: application/json: schema: type: object properties: messages: type: array items: type: object properties: id: type: string mergedMessageIds: type: array items: type: string clientMessageId: type: string role: type: string enum: - user - assistant timestamp: type: string attachments: type: array items: type: object properties: id: type: string filename: type: string mimeType: type: string sizeBytes: type: number kind: type: string data: type: string thumbnailData: type: string fileBacked: type: boolean required: - id - filename - mimeType - sizeBytes - kind additionalProperties: false toolCalls: type: array items: type: object properties: id: type: string name: type: string input: type: object propertyNames: type: string additionalProperties: {} result: type: string isError: type: boolean errorCode: type: string imageData: type: string imageDataList: type: array items: type: string imageAttachmentIds: type: array items: type: string startedAt: type: number previewStartedAt: type: number completedAt: type: number confirmationDecision: type: string enum: - approved - denied - timed_out confirmationLabel: type: string riskLevel: type: string riskReason: type: string matchedTrustRuleId: type: string autoApproved: type: boolean approvalMode: type: string approvalReason: type: string riskThreshold: type: string riskScopeOptions: type: array items: type: object properties: pattern: type: string label: type: string required: - pattern - label additionalProperties: false riskAllowlistOptions: type: array items: type: object properties: label: type: string description: type: string pattern: type: string required: - label - description - pattern additionalProperties: false riskDirectoryScopeOptions: type: array items: type: object properties: scope: type: string label: type: string required: - scope - label additionalProperties: false activityMetadata: type: object properties: webSearch: type: object properties: query: type: string provider: type: string enum: - anthropic-native - brave - perplexity - tavily - keenable - firecrawl resultCount: type: number durationMs: type: number results: type: array items: type: object properties: rank: type: number title: type: string url: type: string domain: type: string faviconUrl: type: string snippet: type: string age: type: string score: type: number required: - rank - title - url - domain additionalProperties: false errorMessage: type: string required: - query - provider - resultCount - durationMs - results additionalProperties: false webFetch: type: object properties: url: type: string finalUrl: type: string provider: type: string enum: - default - firecrawl status: type: number contentType: type: string byteCount: type: number charCount: type: number truncated: type: boolean title: type: string domain: type: string faviconUrl: type: string redirectCount: type: number durationMs: type: number errorMessage: type: string mayRequireJavaScript: type: boolean required: - url - finalUrl - status - byteCount - charCount - truncated - domain - redirectCount - durationMs additionalProperties: false additionalProperties: false scopeOptions: type: array items: type: object properties: label: type: string scope: type: string required: - label - scope additionalProperties: false pendingConfirmation: type: object properties: requestId: type: string title: type: string description: type: string toolName: type: string riskLevel: type: string riskReason: type: string input: type: object propertyNames: type: string additionalProperties: {} allowlistOptions: type: array items: type: object properties: label: type: string description: type: string pattern: type: string required: - label - description - pattern additionalProperties: false scopeOptions: type: array items: type: object properties: label: type: string scope: type: string required: - label - scope additionalProperties: false directoryScopeOptions: type: array items: type: object properties: label: type: string scope: type: string required: - label - scope additionalProperties: false persistentDecisionsAllowed: type: boolean required: - requestId additionalProperties: false pendingQuestion: type: object properties: requestId: type: string entries: type: array items: type: object properties: id: type: string question: type: string description: type: string options: type: array items: type: object properties: id: type: string label: type: string description: type: string required: - id - label additionalProperties: false freeTextPlaceholder: type: string required: - id - question - options additionalProperties: false required: - requestId - entries additionalProperties: false answeredQuestion: type: object properties: requestId: type: string questions: type: array items: type: object properties: id: type: string question: type: string description: type: string options: type: array items: type: object properties: id: type: string label: type: string description: type: string required: - id - label additionalProperties: false freeTextPlaceholder: type: string required: - id - question - options additionalProperties: false responses: type: array items: type: object properties: questionId: type: string decision: type: string enum: - option - free_text - skipped optionId: type: string text: type: string required: - questionId - decision additionalProperties: false overall: type: string enum: - completed - closed required: - requestId - questions - responses - overall additionalProperties: false required: - name - input additionalProperties: false deprecated: true description: "Deprecated: superseded by contentBlocks (the tool_use variant). Flat list of tool calls." surfaces: type: array items: type: object properties: surfaceId: type: string surfaceType: type: string title: type: string data: type: object propertyNames: type: string additionalProperties: {} actions: type: array items: type: object properties: id: type: string label: type: string style: type: string data: type: object propertyNames: type: string additionalProperties: {} required: - id - label additionalProperties: false display: type: string persistent: type: boolean completed: type: boolean completionSummary: type: string toolCallId: type: string required: - surfaceId - surfaceType - data additionalProperties: false deprecated: true description: "Deprecated: superseded by contentBlocks (the surface variant). Flat list of surfaces." textSegments: type: array items: type: string deprecated: true description: "Deprecated: superseded by contentBlocks. Text segments split by tool-call boundaries." thinkingSegments: type: array items: type: string deprecated: true description: "Deprecated: superseded by contentBlocks. Reasoning text extracted from thinking blocks." contentOrder: type: array items: type: string deprecated: true description: 'Deprecated: superseded by contentBlocks. Positional ":" content ordering (e.g. "text:0", "thinking:1").' contentBlocks: type: array items: oneOf: - type: object properties: type: type: string const: text text: type: string required: - type - text additionalProperties: false - type: object properties: type: type: string const: thinking thinking: type: string startedAt: type: number completedAt: type: number required: - type - thinking additionalProperties: false - type: object properties: type: type: string const: tool_use toolCall: type: object properties: id: type: string name: type: string input: type: object propertyNames: type: string additionalProperties: {} result: type: string isError: type: boolean errorCode: type: string imageData: type: string imageDataList: type: array items: type: string imageAttachmentIds: type: array items: type: string startedAt: type: number previewStartedAt: type: number completedAt: type: number confirmationDecision: type: string enum: - approved - denied - timed_out confirmationLabel: type: string riskLevel: type: string riskReason: type: string matchedTrustRuleId: type: string autoApproved: type: boolean approvalMode: type: string approvalReason: type: string riskThreshold: type: string riskScopeOptions: type: array items: type: object properties: pattern: type: string label: type: string required: - pattern - label additionalProperties: false riskAllowlistOptions: type: array items: type: object properties: label: type: string description: type: string pattern: type: string required: - label - description - pattern additionalProperties: false riskDirectoryScopeOptions: type: array items: type: object properties: scope: type: string label: type: string required: - scope - label additionalProperties: false activityMetadata: type: object properties: webSearch: type: object properties: query: type: string provider: type: string enum: - anthropic-native - brave - perplexity - tavily - keenable - firecrawl resultCount: type: number durationMs: type: number results: type: array items: type: object properties: rank: type: number title: type: string url: type: string domain: type: string faviconUrl: type: string snippet: type: string age: type: string score: type: number required: - rank - title - url - domain additionalProperties: false errorMessage: type: string required: - query - provider - resultCount - durationMs - results additionalProperties: false webFetch: type: object properties: url: type: string finalUrl: type: string provider: type: string enum: - default - firecrawl status: type: number contentType: type: string byteCount: type: number charCount: type: number truncated: type: boolean title: type: string domain: type: string faviconUrl: type: string redirectCount: type: number durationMs: type: number errorMessage: type: string mayRequireJavaScript: type: boolean required: - url - finalUrl - status - byteCount - charCount - truncated - domain - redirectCount - durationMs additionalProperties: false additionalProperties: false scopeOptions: type: array items: type: object properties: label: type: string scope: type: string required: - label - scope additionalProperties: false pendingConfirmation: type: object properties: requestId: type: string title: type: string description: type: string toolName: type: string riskLevel: type: string riskReason: type: string input: type: object propertyNames: type: string additionalProperties: {} allowlistOptions: type: array items: type: object properties: label: type: string description: type: string pattern: type: string required: - label - description - pattern additionalProperties: false scopeOptions: type: array items: type: object properties: label: type: string scope: type: string required: - label - scope additionalProperties: false directoryScopeOptions: type: array items: type: object properties: label: type: string scope: type: string required: - label - scope additionalProperties: false persistentDecisionsAllowed: type: boolean required: - requestId additionalProperties: false pendingQuestion: type: object properties: requestId: type: string entries: type: array items: type: object properties: id: type: string question: type: string description: type: string options: type: array items: type: object properties: id: type: string label: type: string description: type: string required: - id - label additionalProperties: false freeTextPlaceholder: type: string required: - id - question - options additionalProperties: false required: - requestId - entries additionalProperties: false answeredQuestion: type: object properties: requestId: type: string questions: type: array items: type: object properties: id: type: string question: type: string description: type: string options: type: array items: type: object properties: id: type: string label: type: string description: type: string required: - id - label additionalProperties: false freeTextPlaceholder: type: string required: - id - question - options additionalProperties: false responses: type: array items: type: object properties: questionId: type: string decision: type: string enum: - option - free_text - skipped optionId: type: string text: type: string required: - questionId - decision additionalProperties: false overall: type: string enum: - completed - closed required: - requestId - questions - responses - overall additionalProperties: false required: - name - input additionalProperties: false required: - type - toolCall additionalProperties: false - type: object properties: type: type: string const: surface surface: type: object properties: surfaceId: type: string surfaceType: type: string title: type: string data: type: object propertyNames: type: string additionalProperties: {} actions: type: array items: type: object properties: id: type: string label: type: string style: type: string data: type: object propertyNames: type: string additionalProperties: {} required: - id - label additionalProperties: false display: type: string persistent: type: boolean completed: type: boolean completionSummary: type: string toolCallId: type: string required: - surfaceId - surfaceType - data additionalProperties: false required: - type - surface additionalProperties: false - type: object properties: type: type: string const: attachment attachment: type: object properties: id: type: string filename: type: string mimeType: type: string sizeBytes: type: number kind: type: string data: type: string thumbnailData: type: string fileBacked: type: boolean required: - id - filename - mimeType - sizeBytes - kind additionalProperties: false required: - type - attachment additionalProperties: false type: object subagentNotification: type: object properties: subagentId: type: string label: type: string status: type: string error: type: string conversationId: type: string objective: type: string required: - subagentId - label - status additionalProperties: false acpNotification: type: object properties: acpSessionId: type: string agent: type: string required: - acpSessionId additionalProperties: false backgroundEventNotification: type: boolean backgroundToolCompletion: type: object properties: id: type: string toolName: type: string conversationId: type: string command: type: string startedAt: type: number status: type: string enum: - completed - failed - cancelled exitCode: anyOf: - type: number - type: "null" output: type: string completedAt: type: number required: - id - toolName - conversationId - command - startedAt - status - exitCode - output - completedAt additionalProperties: false systemCard: type: boolean providerError: type: object properties: code: type: string category: type: string additionalProperties: false slackMessage: type: object properties: channelId: type: string channelName: type: string channelTs: type: string threadTs: type: string sender: type: object properties: displayName: type: string externalUserId: type: string additionalProperties: false messageLink: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false threadLink: type: object properties: appUrl: type: string webUrl: type: string additionalProperties: false eventKind: type: string enum: - message - reaction reaction: type: object properties: emoji: type: string op: type: string enum: - added - removed actorDisplayName: type: string targetChannelTs: type: string required: - emoji - op - targetChannelTs additionalProperties: false required: - channelId - channelTs additionalProperties: false queueStatus: type: string enum: - queued - processing queuePosition: type: number required: - id - role - timestamp - attachments additionalProperties: false description: Array of message objects hasMore: description: Whether older messages exist beyond this page type: boolean oldestTimestamp: description: Timestamp of the oldest message in this page (ms since epoch). Null when page=latest is used on an empty conversation. anyOf: - type: number - type: "null" oldestMessageId: description: ID of the oldest message in this page anyOf: - type: string - type: "null" seq: description: Global SSE `seq` of the last event whose content is durably persisted for this conversation in the current daemon process. A client can align this snapshot with the `/events` stream by applying only events with `seq` greater than this value. Null when no events have been persisted in this process (cold conversation, after a daemon restart, or when the conversation has aged out of the in-memory map) — clients should cold-start in that case. Absent on older daemons that predate this field. anyOf: - type: number - type: "null" processing: description: "Whether the agent is currently mid-turn for this conversation, sourced authoritatively from the persisted `processing_started_at` column. `true` means a turn is in flight; `false` means the conversation is idle. Clients use this to recover from a dropped SSE stream: if a turn appears to be running locally but the server reports `processing: false`, the turn has ended (or died) and the UI should stop waiting rather than spin indefinitely. Absent on older daemons that predate this field." type: boolean required: - messages additionalProperties: false post: operationId: messages_post summary: Send a message description: Send a user message to a conversation and trigger the assistant response. tags: - messages requestBody: required: true content: application/json: schema: type: object properties: conversationId: description: Internal conversation id (0.8.6+ strict lookup). Omit both id and key to mint a new conversation server-side. anyOf: - type: string - type: "null" conversationKey: anyOf: - type: string - type: "null" content: type: string description: Message text content attachments: type: array items: {} description: Optional inline file attachments attachmentIds: type: array items: type: string description: Ids of previously uploaded attachments to attach sourceChannel: type: string description: Originating channel id (e.g. "vellum") interface: type: string description: Originating interface id (e.g. "vellum") conversationType: type: string slashCommand: type: string clientTimezone: type: string clientOs: description: Client OS surface ("web" | "ios" | "macos" | "windows" | "android"), reported separately from `interface`. Drives the per-turn `client_os` context only; does not affect transport/host-proxy capabilities. type: string visibleAppId: description: 'Id of the app the client currently has open on screen (app viewer or the app-editing split). Drives the per-turn `visible_app:` context line so the assistant can resolve "the app" to what the user is looking at. View state only: it never affects transport, routing, or tool gating, and is omitted whenever no app is in view.' type: string clientMessageId: type: string description: Client-generated idempotency nonce. Persisted on the row and echoed back on the message_echo event and the messages snapshot so the client can correlate its optimistic row by identity. Duplicate sends for the same (conversation, clientMessageId) are deduplicated server-side. inferenceProfile: anyOf: - type: string - type: "null" enabledPlugins: description: Plugin ids that scope this conversation to a subset of installed plugins (first-party defaults are always available). When present on a message, it sets/updates the conversation's plugin scope (the web client sends it only on the first message of a new chat). null clears the scope to default (all enabled plugins); omitting the field leaves the existing scope unchanged. anyOf: - type: array items: type: string - type: "null" riskThreshold: type: string enum: - none - low - medium - high bypassSecretCheck: description: When true, skip the secret-ingress scan for this message only. Set exclusively when the user explicitly confirms a client-side blocked send (the composer's "Send anyway" action); it is per-message and never persisted. type: boolean hidden: description: "When true, persist the user message but suppress it from the UI transcript (it stays in LLM-side history and still drives the turn). Used for machine signals the user never typed (proactive-greeting priming, channel-setup wizard close). Suppression covers the queued path too: a hidden send that lands mid-turn returns { queued: true, requestId } but never appears in list-messages queued snapshots, emits no echo, and does not supersede pending interactions. Honored on the standard send path only — slash-command content bypasses it." type: boolean scripted: description: "When true, this turn was auto-sent on the user's behalf rather than typed by them: onboarding research prompts, the personality rewrite message, research corrections, hidden kickoff greetings, the legacy pre-chat bootstrap. Stamped onto the persisted message and forwarded to turn telemetry, where activation metrics exclude it. Send false for a genuine typed message; OMIT the field only if the client genuinely cannot tell, since absent means UNKNOWN and a wrong false is trusted downstream. Independent of `hidden`: a turn can be visible and scripted (the research prompt) or hidden and scripted (the kickoff greeting)." type: boolean onboarding: type: object properties: tools: type: array items: type: string tasks: type: array items: type: string tone: type: string userName: type: string occupation: type: string assistantName: type: string googleConnected: type: boolean googleScopes: type: array items: type: string priorAssistants: type: array items: type: string cohort: type: string websiteUrl: type: string contentSourceUrl: type: string bootstrapTemplate: type: string initialMessage: type: string skills: type: array items: type: string researchFindings: description: Findings from pre-chat onboarding research that the user explicitly kept on the results screen. Written into the persona's onboarding section so the first turn can reference them. type: array items: type: string title: description: Explicit title for the conversation minted on this first message. Persisted as a user-set title (never overwritten by the auto-titler). Used by onboarding flows that mint a conversation behind the scenes. type: string required: - tools - tasks - tone description: PreChat onboarding context, sent on the first message only required: - content - sourceChannel - interface responses: "202": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean conversationId: type: string messageId: type: string queued: type: boolean requestId: type: string required: - accepted additionalProperties: false /v1/messages/{id}/content: get: operationId: messages_by_id_content_get summary: Get message content description: Return the full content of a single message by ID. tags: - messages parameters: - name: id in: path required: true schema: type: string - name: conversationId in: query required: false schema: type: string description: Optional conversation ID filter responses: "200": description: Successful response /v1/messages/{id}/llm-context: get: operationId: messages_by_id_llmcontext_get summary: Get LLM context for a message description: Return request/response logs and memory recall data for a specific message. tags: - messages parameters: - name: id in: path required: true schema: type: string - name: view in: query required: false schema: type: string enum: - full - summary description: Response shape. 'summary' omits per-log request/response sections; defaults to 'full'. responses: "200": description: Successful response content: application/json: schema: type: object properties: messageId: anyOf: - type: string - type: "null" conversationKey: anyOf: - type: string - type: "null" conversationId: anyOf: - type: string - type: "null" conversationKind: type: string conversationTotalEstimatedCostUsd: anyOf: - type: number - type: "null" logs: type: array items: type: object properties: id: type: string createdAt: type: number requestPayload: type: "null" responsePayload: type: "null" provider: anyOf: - type: string - type: "null" summary: anyOf: - type: object properties: provider: anyOf: - type: string - type: "null" model: anyOf: - type: string - type: "null" status: anyOf: - type: string - type: "null" inputTokens: anyOf: - type: number - type: "null" outputTokens: anyOf: - type: number - type: "null" cacheCreationInputTokens: anyOf: - type: number - type: "null" cacheReadInputTokens: anyOf: - type: number - type: "null" stopReason: anyOf: - type: string - type: "null" requestMessageCount: anyOf: - type: number - type: "null" requestToolCount: anyOf: - type: number - type: "null" responseMessageCount: anyOf: - type: number - type: "null" responseToolCallCount: anyOf: - type: number - type: "null" responsePreview: anyOf: - type: string - type: "null" toolCallNames: anyOf: - type: array items: type: string - type: "null" estimatedCostUsd: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" additionalProperties: false - type: "null" requestSections: anyOf: - type: array items: type: object properties: kind: type: string label: anyOf: - type: string - type: "null" role: anyOf: - type: string - type: "null" text: anyOf: - type: string - type: "null" toolName: anyOf: - type: string - type: "null" data: {} language: anyOf: - type: string - type: "null" required: - kind additionalProperties: false - type: "null" responseSections: anyOf: - type: array items: type: object properties: kind: type: string label: anyOf: - type: string - type: "null" role: anyOf: - type: string - type: "null" text: anyOf: - type: string - type: "null" toolName: anyOf: - type: string - type: "null" data: {} language: anyOf: - type: string - type: "null" required: - kind additionalProperties: false - type: "null" agentLoopExitReason: anyOf: - type: string - type: "null" callSite: anyOf: - type: string - type: "null" error: anyOf: - type: object properties: name: anyOf: - type: string - type: "null" message: anyOf: - type: string - type: "null" code: anyOf: - type: string - type: "null" provider: anyOf: - type: string - type: "null" statusCode: anyOf: - type: number - type: "null" retryAfterMs: anyOf: - type: number - type: "null" apiErrorCode: anyOf: - type: string - type: "null" apiErrorType: anyOf: - type: string - type: "null" apiErrorParam: anyOf: - type: string - type: "null" requestId: anyOf: - type: string - type: "null" additionalProperties: false - type: "null" latency: anyOf: - type: object properties: phases: type: array items: type: object properties: key: type: string label: type: string ms: type: number subPhases: type: array items: type: object properties: key: type: string label: type: string ms: type: number required: - key - label - ms additionalProperties: false required: - key - label - ms additionalProperties: false ttftMs: anyOf: - type: number - type: "null" totalToFirstTokenMs: anyOf: - type: number - type: "null" providerDurationMs: anyOf: - type: number - type: "null" firstTokenKind: anyOf: - type: string enum: - thinking - text - type: "null" required: - phases additionalProperties: false - type: "null" required: - id - createdAt - requestPayload - responsePayload additionalProperties: false memoryRecall: anyOf: - type: object properties: enabled: type: boolean degraded: type: boolean provider: anyOf: - type: string - type: "null" model: anyOf: - type: string - type: "null" degradation: anyOf: - type: object properties: reason: type: string semanticUnavailable: type: boolean fallbackSources: type: array items: type: string required: - reason - semanticUnavailable - fallbackSources additionalProperties: false - type: "null" semanticHits: anyOf: - type: number - type: "null" mergedCount: anyOf: - type: number - type: "null" selectedCount: anyOf: - type: number - type: "null" tier1Count: anyOf: - type: number - type: "null" tier2Count: anyOf: - type: number - type: "null" hybridSearchLatencyMs: anyOf: - type: number - type: "null" sparseVectorUsed: anyOf: - type: boolean - type: "null" injectedTokens: anyOf: - type: number - type: "null" latencyMs: anyOf: - type: number - type: "null" topCandidates: type: array items: type: object properties: nodeId: type: string score: type: number semanticSimilarity: type: number recencyBoost: type: number type: type: string required: - nodeId - score - semanticSimilarity - recencyBoost additionalProperties: false injectedText: anyOf: - type: string - type: "null" reason: anyOf: - type: string - type: "null" queryContext: anyOf: - type: string - type: "null" required: - enabled - degraded - provider - model - degradation - topCandidates - injectedText - reason - queryContext additionalProperties: false - type: "null" memoryV2Activation: anyOf: - type: object properties: turn: type: number mode: type: string concepts: type: array items: type: object properties: slug: type: string finalActivation: type: number ownActivation: type: number priorActivation: type: number simUser: type: number simAssistant: type: number simNow: type: number simUserRerankBoost: type: number simAssistantRerankBoost: type: number inRerankPool: type: boolean spreadContribution: type: number source: type: string status: type: string required: - slug - finalActivation - ownActivation - priorActivation - simUser - simAssistant - simNow - spreadContribution - source - status additionalProperties: false config: type: object properties: d: type: number c_user: type: number c_assistant: type: number c_now: type: number k: type: number hops: type: number top_k: type: number epsilon: type: number required: - d - c_user - c_assistant - c_now - k - hops - top_k - epsilon additionalProperties: false required: - turn - mode - concepts - config additionalProperties: false - type: "null" memoryV3Selection: anyOf: - type: object properties: turn: type: number live: type: boolean selections: type: array items: type: object properties: slug: type: string source: type: string pinned: type: boolean sectionOrdinal: anyOf: - type: number - type: "null" sectionHeading: anyOf: - type: string - type: "null" required: - slug - source - pinned additionalProperties: false injectedText: type: string required: - turn - live - selections - injectedText additionalProperties: false - type: "null" required: - conversationKind - logs - memoryRecall - memoryV2Activation additionalProperties: false /v1/messages/lexical/backfill: post: operationId: messages_lexical_backfill_post summary: Enqueue a resumable backfill of messages into the lexical index description: "Enqueues the cursor-checkpointed backfill job that indexes existing messages into the Qdrant lexical (BM25-style) collection in batches. Resumable and idempotent — re-running continues from the last checkpoint. Pass `force: true` to reset the cursor and re-index from the beginning. The same backfill is also auto-enqueued once per instance on upgrade at assistant startup." tags: - memory requestBody: required: true content: application/json: schema: type: object properties: force: type: boolean additionalProperties: false responses: "200": description: Successful response /v1/messages/queued/{id}: delete: operationId: messages_queued_by_id_delete summary: Delete a queued message description: Remove a pending message from the conversation queue before it is processed. Broadcasts `message_queued_deleted` so every client can close out the pending row. tags: - messages parameters: - name: id in: path required: true schema: type: string - name: conversationId in: query required: true schema: type: string description: Conversation ID (required) responses: "200": description: Successful response "403": description: The queued message was enqueued by a different actor principal. "404": description: Conversation or queued message not found. /v1/messages/queued/{id}/steer: post: operationId: messages_queued_by_id_steer_post summary: Steer to a queued message description: Promote a queued message to the head of the queue and abort the current generation so it is processed next. tags: - messages parameters: - name: id in: path required: true schema: type: string - name: conversationId in: query required: true schema: type: string description: Conversation ID (required) responses: "200": description: Successful response "403": description: The queued message was enqueued by a different actor principal. "404": description: Conversation or queued message not found. /v1/migrations/export: post: operationId: migrations_export_post summary: Export a .vbundle archive description: Generate and download a .vbundle archive of the assistant's data. Optional JSON body for metadata. tags: - migrations requestBody: required: true content: application/json: schema: type: object properties: description: type: string description: Human-readable export description required: - description responses: "200": description: Successful response /v1/migrations/export-to-gcs: post: operationId: migrations_exporttogcs_post summary: Start an async export streamed to a GCS signed URL description: Kick off a background export job that PUTs a freshly-built .vbundle archive to the supplied GCS signed URL. Returns 202 with a job_id the caller can poll via the job-status endpoint. Fails fast with 409 if another export job is already pending or running. tags: - migrations requestBody: required: true content: application/json: schema: type: object properties: upload_url: type: string format: uri description: Signed GCS PUT URL that receives the exported bundle. description: description: Human-readable export description. type: string required: - upload_url responses: "202": description: Successful response content: application/json: schema: type: object properties: job_id: type: string status: type: string const: pending type: type: string const: export required: - job_id - status - type additionalProperties: false /v1/migrations/import: post: operationId: migrations_import_post summary: Import a .vbundle archive description: Commit a .vbundle archive import to disk — destructive. Accepts the bundle as raw bytes (application/octet-stream), multipart/form-data, or a JSON body with `{ url }` carrying a signed URL the daemon fetches. tags: - migrations requestBody: required: true content: application/json: schema: type: object properties: url: type: string format: uri description: A signed GCS URL pointing to the .vbundle archive (JSON body path only). required: - url responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean summary: type: object properties: {} additionalProperties: {} files: type: array items: {} manifest: type: object properties: {} additionalProperties: {} warnings: type: array items: {} required: - success - summary - files - manifest - warnings additionalProperties: false "502": description: Upstream fetch failed (URL body only). /v1/migrations/import-from-gcs: post: operationId: migrations_importfromgcs_post summary: Start an async .vbundle import from a signed GCS URL description: Schedule a background import job that fetches the bundle at `bundle_url` and streams it through the importer. Returns 202 with a `job_id`; poll `GET /v1/migrations/jobs/{job_id}` for status. 409 if another import is already in flight. tags: - migrations requestBody: required: true content: application/json: schema: type: object properties: bundle_url: type: string format: uri required: - bundle_url responses: "202": description: Successful response content: application/json: schema: type: object properties: job_id: type: string status: type: string const: pending type: type: string const: import required: - job_id - status - type additionalProperties: false "409": description: Another import job is already pending or running. /v1/migrations/import-preflight: post: operationId: migrations_importpreflight_post summary: Dry-run import analysis description: Validate a .vbundle archive and return a report of what would change on import without modifying data. tags: - migrations responses: "200": description: Successful response content: application/json: schema: type: object properties: can_import: type: boolean summary: type: object properties: {} additionalProperties: {} files: type: array items: {} conflicts: type: array items: {} manifest: type: object properties: {} additionalProperties: {} required: - can_import - summary - files - conflicts - manifest additionalProperties: false /v1/migrations/jobs/{job_id}: get: operationId: migrations_jobs_by_job_id_get summary: Get migration job status description: "Return the current status of an async migration job (export or import). The response discriminates on `status`: `processing` (pending or running), `complete` (with `result`), or `failed` (with `error`, `error_code`, optional `upstream_status`)." tags: - migrations parameters: - name: job_id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: oneOf: - type: object properties: job_id: type: string type: type: string enum: - export - import status: type: string const: processing required: - job_id - type - status additionalProperties: false - type: object properties: job_id: type: string type: type: string enum: - export - import status: type: string const: complete result: {} required: - job_id - type - status - result additionalProperties: false - type: object properties: job_id: type: string type: type: string enum: - export - import status: type: string const: failed error: type: string error_code: type: string upstream_status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - job_id - type - status - error - error_code additionalProperties: false type: object "404": description: No job matches the given id. /v1/migrations/preflight-from-gcs: post: operationId: migrations_preflightfromgcs_post summary: Dry-run import analysis from a signed GCS URL description: Fetch a .vbundle archive from a signed GCS download URL and return a preflight report — what would change if the bundle were imported — without writing anything to disk. Enables `vellum teleport --dry-run` against local and docker targets. tags: - migrations requestBody: required: true content: application/json: schema: type: object properties: bundle_url: type: string format: uri description: Signed GCS GET URL for the bundle. required: - bundle_url responses: "200": description: Successful response content: application/json: schema: type: object properties: can_import: type: boolean summary: type: object properties: {} additionalProperties: {} files: type: array items: {} conflicts: type: array items: {} validation: type: object properties: {} additionalProperties: {} required: - can_import additionalProperties: false /v1/migrations/validate: post: operationId: migrations_validate_post summary: Validate a .vbundle archive description: Upload a .vbundle archive for validation. Accepts raw binary or multipart form data. tags: - migrations responses: "200": description: Successful response content: application/json: schema: type: object properties: is_valid: type: boolean errors: type: array items: {} manifest: type: object properties: {} additionalProperties: {} required: - is_valid - errors - manifest additionalProperties: false /v1/model: get: operationId: model_get summary: Get current model config description: Return the active LLM model ID, provider, and available models. tags: - config responses: "200": description: Successful response /v1/model/image-gen: put: operationId: model_imagegen_put summary: Set image generation model description: Change the active image generation model. tags: - config requestBody: required: true content: application/json: schema: type: object properties: modelId: type: string required: - modelId responses: "200": description: Successful response /v1/monitoring/start: post: operationId: monitoring_start_post summary: Start the resource monitor description: Spawns (or reuses) the resource monitor process as a child of the daemon. The daemon also spawns it at every boot. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: pid: type: number alreadyRunning: type: boolean pidPath: type: string required: - pid - alreadyRunning - pidPath additionalProperties: false /v1/monitoring/status: get: operationId: monitoring_status_get summary: Resource monitor status description: Reports the resource monitor process state, the forensics data directory, and the most recent persisted memory/disk sample. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - running - not_running pid: type: number dataDir: type: string latestSample: anyOf: - type: object properties: ts: type: number memory: anyOf: - type: object properties: currentBytes: type: number limitBytes: anyOf: - type: number - type: "null" peakBytes: anyOf: - type: number - type: "null" ratio: anyOf: - type: number - type: "null" required: - currentBytes - limitBytes - peakBytes - ratio additionalProperties: false - type: "null" memoryStat: anyOf: - type: object properties: anonBytes: anyOf: - type: number - type: "null" fileBytes: anyOf: - type: number - type: "null" inactiveFileBytes: anyOf: - type: number - type: "null" kernelBytes: anyOf: - type: number - type: "null" slabReclaimableBytes: anyOf: - type: number - type: "null" slabUnreclaimableBytes: anyOf: - type: number - type: "null" unevictableBytes: anyOf: - type: number - type: "null" reclaimableBytes: anyOf: - type: number - type: "null" required: - anonBytes - fileBytes - inactiveFileBytes - kernelBytes - slabReclaimableBytes - slabUnreclaimableBytes - unevictableBytes - reclaimableBytes additionalProperties: false - type: "null" reclaim: anyOf: - type: object properties: pgscanDirect: anyOf: - type: number - type: "null" pgstealDirect: anyOf: - type: number - type: "null" workingsetRefaultFile: anyOf: - type: number - type: "null" required: - pgscanDirect - pgstealDirect - workingsetRefaultFile additionalProperties: false - type: "null" cpu: anyOf: - type: object properties: usageUsec: anyOf: - type: number - type: "null" userUsec: anyOf: - type: number - type: "null" systemUsec: anyOf: - type: number - type: "null" nrPeriods: anyOf: - type: number - type: "null" nrThrottled: anyOf: - type: number - type: "null" throttledUsec: anyOf: - type: number - type: "null" required: - usageUsec - userUsec - systemUsec - nrPeriods - nrThrottled - throttledUsec additionalProperties: false - type: "null" events: anyOf: - type: object properties: low: type: number high: type: number max: type: number oom: type: number oomKill: type: number required: - low - high - max - oom - oomKill additionalProperties: false - type: "null" deltas: anyOf: - type: object properties: events: anyOf: - type: object properties: low: anyOf: - type: number - type: "null" high: anyOf: - type: number - type: "null" max: anyOf: - type: number - type: "null" oom: anyOf: - type: number - type: "null" oomKill: anyOf: - type: number - type: "null" required: - low - high - max - oom - oomKill additionalProperties: false - type: "null" reclaim: anyOf: - type: object properties: pgscanDirect: anyOf: - type: number - type: "null" pgstealDirect: anyOf: - type: number - type: "null" workingsetRefaultFile: anyOf: - type: number - type: "null" required: - pgscanDirect - pgstealDirect - workingsetRefaultFile additionalProperties: false - type: "null" cpu: anyOf: - type: object properties: usageUsec: anyOf: - type: number - type: "null" userUsec: anyOf: - type: number - type: "null" systemUsec: anyOf: - type: number - type: "null" nrPeriods: anyOf: - type: number - type: "null" nrThrottled: anyOf: - type: number - type: "null" throttledUsec: anyOf: - type: number - type: "null" required: - usageUsec - userUsec - systemUsec - nrPeriods - nrThrottled - throttledUsec additionalProperties: false - type: "null" required: - events - reclaim - cpu additionalProperties: false - type: "null" disk: anyOf: - type: object properties: path: type: string usedMb: type: number totalMb: type: number freeMb: type: number required: - path - usedMb - totalMb - freeMb additionalProperties: false - type: "null" activeConversations: anyOf: - type: array items: type: object properties: conversationId: type: string title: anyOf: - type: string - type: "null" originChannel: anyOf: - type: string - type: "null" originInterface: anyOf: - type: string - type: "null" processingStartedAt: type: number required: - conversationId - title - originChannel - originInterface - processingStartedAt additionalProperties: false - type: "null" required: - ts - memory - memoryStat - reclaim - cpu - events - deltas - disk - activeConversations additionalProperties: false - type: "null" required: - status - dataDir - latestSample additionalProperties: false /v1/monitoring/stop: post: operationId: monitoring_stop_post summary: Stop the resource monitor description: SIGTERMs the resource monitor process if it is running. The monitor respawns on the next daemon boot. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: monitoringWasRunning: type: boolean pid: type: number required: - monitoringWasRunning additionalProperties: false /v1/notification-intent-result: post: operationId: notificationintentresult_post summary: Report notification delivery result description: Client acknowledgment for local notification delivery outcome. tags: - notifications requestBody: required: true content: application/json: schema: type: object properties: deliveryId: type: string minLength: 1 description: Notification delivery ID success: type: boolean description: Whether delivery succeeded errorMessage: type: string description: Error message if delivery failed errorCode: type: string description: Error code if delivery failed required: - deliveryId responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/notifications/edit: post: operationId: notifications_edit_post summary: Edit an already-sent notification description: Patch the home-feed entry for a notification and, where supported (Slack today), update the delivered message in place. tags: - notifications requestBody: required: true content: application/json: schema: type: object properties: id: type: string minLength: 1 description: Feed item id (notif:) or bare uuid title: description: New title. An empty value is ignored, never cleared. type: string body: type: string urgency: type: string enum: - low - medium - high - critical status: type: string enum: - new - seen - acted_on - dismissed required: - id responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean feedItem: type: object properties: id: type: string type: type: string const: notification priority: type: integer minimum: 0 maximum: 100 title: type: string summary: type: string timestamp: type: string status: default: new type: string enum: - new - seen - acted_on - dismissed expiresAt: type: string actions: type: array items: type: object properties: id: type: string label: type: string prompt: type: string required: - id - label - prompt additionalProperties: false urgency: type: string enum: - low - medium - high - critical conversationId: type: string detailPanel: type: object properties: kind: type: string enum: - emailDraft - documentPreview - permissionChat - paymentAuth - toolPermission - updatesList required: - kind additionalProperties: false category: type: string enum: - security - scheduling - background - email - system noteworthy: type: boolean fromAssistant: type: boolean metadata: type: object propertyNames: type: string additionalProperties: {} sourceType: type: string enum: - heartbeat - memory_consolidation - schedule - auto_analysis - user - other sourceKey: type: string sourceLabel: type: string createdAt: type: string required: - id - type - priority - summary - timestamp - status - createdAt additionalProperties: false channels: type: array items: type: object properties: channel: type: string deliveryId: type: string outcome: type: string enum: - updated - unsupported - skipped - failed reason: type: string required: - channel - deliveryId - outcome additionalProperties: false required: - ok - feedItem - channels additionalProperties: false "404": description: No notification found for the supplied id /v1/notifications/emit: post: operationId: notifications_emit_post summary: Emit a notification signal description: Emit a notification signal into the pipeline for routing and delivery. tags: - notifications requestBody: required: true content: application/json: schema: type: object properties: sourceEventName: type: string minLength: 1 sourceChannel: type: string enum: - assistant_tool - vellum - phone - telegram - whatsapp - slack - email - platform - a2a - discord - plugin - scheduler - watcher sourceContextId: type: string minLength: 1 attentionHints: type: object properties: requiresAction: type: boolean urgency: type: string enum: - low - medium - high - critical deadlineAt: type: number isAsyncBackground: type: boolean visibleInSourceNow: type: boolean required: - requiresAction - urgency - isAsyncBackground - visibleInSourceNow contextPayload: type: object propertyNames: type: string additionalProperties: {} routingIntent: type: string enum: - single_channel - multi_channel - all_channels conversationAffinityHint: type: object propertyNames: type: string additionalProperties: type: string dedupeKey: type: string throwOnError: type: boolean required: - sourceEventName - sourceChannel - sourceContextId - attentionHints responses: "200": description: Successful response content: application/json: schema: type: object properties: signalId: type: string dispatched: type: boolean deduplicated: type: boolean reason: type: string required: - signalId - dispatched - deduplicated - reason additionalProperties: false /v1/notifications/events: post: operationId: notifications_events_post summary: List notification events description: List recent notification events, optionally filtered by source event name. tags: - notifications requestBody: required: true content: application/json: schema: type: object properties: limit: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 sourceEventName: type: string responses: "200": description: Successful response content: application/json: schema: type: array items: type: object properties: id: type: string sourceEventName: type: string sourceChannel: type: string sourceContextId: type: string urgency: type: string dedupeKey: anyOf: - type: string - type: "null" createdAt: type: string required: - id - sourceEventName - sourceChannel - sourceContextId - urgency - dedupeKey - createdAt additionalProperties: false /v1/oauth/apps: get: operationId: oauth_apps_get summary: List OAuth apps description: List OAuth apps filtered by provider_key. tags: - oauth parameters: - name: provider_key in: query required: true schema: type: string description: OAuth provider key to filter by responses: "200": description: Successful response content: application/json: schema: type: object properties: provider: anyOf: - type: object properties: provider_key: type: string display_name: anyOf: - type: string - type: "null" description: anyOf: - type: string - type: "null" dashboard_url: anyOf: - type: string - type: "null" client_id_placeholder: anyOf: - type: string - type: "null" requires_client_secret: type: boolean logo_url: anyOf: - type: string - type: "null" supports_managed_mode: type: boolean managed_service_is_paid: type: boolean feature_flag: anyOf: - type: string - type: "null" acts_as: type: string enum: - user - assistant required: - provider_key - display_name - description - dashboard_url - client_id_placeholder - requires_client_secret - logo_url - supports_managed_mode - managed_service_is_paid - feature_flag - acts_as additionalProperties: false - type: "null" apps: type: array items: type: object properties: id: type: string provider_key: type: string client_id: type: string created_at: type: number updated_at: type: number required: - id - provider_key - client_id - created_at - updated_at additionalProperties: false required: - provider - apps additionalProperties: false post: operationId: oauth_apps_post summary: Create OAuth app description: Register a new OAuth app with client credentials. tags: - oauth requestBody: required: true content: application/json: schema: type: object properties: provider_key: type: string client_id: type: string client_secret: type: string required: - provider_key - client_id - client_secret responses: "201": description: Successful response content: application/json: schema: type: object properties: app: type: object properties: id: type: string provider_key: type: string client_id: type: string created_at: type: number updated_at: type: number required: - id - provider_key - client_id - created_at - updated_at additionalProperties: false required: - app additionalProperties: false /v1/oauth/apps/{appId}/connect: post: operationId: oauth_apps_by_appId_connect_post summary: Start OAuth connect description: Start an OAuth connect flow for an app. tags: - oauth parameters: - name: appId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: scopes: type: array items: type: string callback_transport: type: string enum: - loopback - gateway responses: "200": description: Successful response content: application/json: schema: anyOf: - type: object properties: auth_url: type: string state: type: string required: - auth_url - state additionalProperties: false - type: object properties: ok: type: boolean const: true required: - ok additionalProperties: false /v1/oauth/apps/{appId}/connections: get: operationId: oauth_apps_by_appId_connections_get summary: List OAuth connections description: List connections for an OAuth app. tags: - oauth parameters: - name: appId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: connections: type: array items: type: object properties: id: type: string provider_key: type: string account_info: anyOf: - type: string - type: "null" granted_scopes: type: array items: type: string status: type: string has_refresh_token: type: boolean expires_at: anyOf: - type: number - type: "null" created_at: type: number updated_at: type: number required: - id - provider_key - account_info - granted_scopes - status - has_refresh_token - expires_at - created_at - updated_at additionalProperties: false required: - connections additionalProperties: false /v1/oauth/apps/{id}: delete: operationId: oauth_apps_by_id_delete summary: Delete OAuth app description: Delete an OAuth app and disconnect all its connections. tags: - oauth parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/oauth/apps/lookup: get: operationId: oauth_apps_lookup_get summary: Get OAuth app description: Look up a single OAuth app by ID, provider + client_id, or provider (most recent). tags: - oauth parameters: - name: id in: query required: false schema: type: string description: App UUID - name: provider in: query required: false schema: type: string description: Provider key - name: client_id in: query required: false schema: type: string description: OAuth client ID (requires provider) responses: "200": description: Successful response content: application/json: schema: type: object properties: app: type: object properties: id: type: string provider_key: type: string client_id: type: string created_at: type: number updated_at: type: number required: - id - provider_key - client_id - created_at - updated_at additionalProperties: false required: - app additionalProperties: false /v1/oauth/apps/upsert: post: operationId: oauth_apps_upsert_post summary: Upsert OAuth app description: Create or return an existing OAuth app registration. Updates client secret if provided. tags: - oauth requestBody: required: true content: application/json: schema: type: object properties: provider_key: type: string client_id: type: string client_secret: type: string client_secret_credential_path: type: string required: - provider_key - client_id responses: "200": description: Successful response content: application/json: schema: type: object properties: app: type: object properties: id: type: string provider_key: type: string client_id: type: string created_at: type: number updated_at: type: number required: - id - provider_key - client_id - created_at - updated_at additionalProperties: false required: - app additionalProperties: false /v1/oauth/connection-changed: post: operationId: oauth_connectionchanged_post summary: Notify the assistant that an OAuth connection changed description: Invalidates the config cache so the assistant picks up mode and credential changes immediately. tags: - oauth responses: "200": description: Successful response content: application/json: schema: type: object properties: refreshed: type: boolean required: - refreshed additionalProperties: false /v1/oauth/connections/{id}: delete: operationId: oauth_connections_by_id_delete summary: Disconnect OAuth connection description: Disconnect a single OAuth connection. tags: - oauth parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/oauth/disconnect: post: operationId: oauth_disconnect_post summary: Disconnect OAuth provider description: Disconnect an OAuth provider and remove associated credentials (BYO or managed). tags: - oauth responses: "200": description: Successful response /v1/oauth/managed-connect/poll: get: operationId: oauth_managedconnect_poll_get summary: Poll managed OAuth connections description: Fetch active platform connections for a provider (used to detect new connections after managed connect). tags: - oauth parameters: - name: provider in: query required: true schema: type: string description: Provider key responses: "200": description: Successful response /v1/oauth/managed-connect/start: post: operationId: oauth_managedconnect_start_post summary: Start managed OAuth connect description: Start a managed (platform) OAuth connect flow and return the connect URL. tags: - oauth responses: "200": description: Successful response /v1/oauth/mode: get: operationId: oauth_mode_get summary: Get OAuth mode description: Get the current OAuth mode (managed or your-own) for a provider. tags: - oauth parameters: - name: provider in: query required: true schema: type: string description: Provider key responses: "200": description: Successful response post: operationId: oauth_mode_post summary: Set OAuth mode description: Set the OAuth mode (managed or your-own) for a provider. tags: - oauth responses: "200": description: Successful response /v1/oauth/ping: post: operationId: oauth_ping_post summary: Ping OAuth provider description: Verify an OAuth token is valid by hitting the provider's configured health-check endpoint. tags: - oauth responses: "200": description: Successful response /v1/oauth/providers: get: operationId: oauth_providers_get summary: List OAuth providers description: List all registered OAuth providers with optional filtering. tags: - oauth parameters: - name: supports_managed_mode in: query required: false schema: type: string description: Filter by managed mode support (true/false) responses: "200": description: Successful response content: application/json: schema: type: object properties: providers: type: array items: type: object properties: provider_key: type: string display_name: anyOf: - type: string - type: "null" description: anyOf: - type: string - type: "null" dashboard_url: anyOf: - type: string - type: "null" client_id_placeholder: anyOf: - type: string - type: "null" requires_client_secret: type: boolean logo_url: anyOf: - type: string - type: "null" supports_managed_mode: type: boolean managed_service_is_paid: type: boolean feature_flag: anyOf: - type: string - type: "null" acts_as: type: string enum: - user - assistant required: - provider_key - display_name - description - dashboard_url - client_id_placeholder - requires_client_secret - logo_url - supports_managed_mode - managed_service_is_paid - feature_flag - acts_as additionalProperties: false required: - providers additionalProperties: false post: operationId: oauth_providers_post summary: Register OAuth provider description: Register a new OAuth provider configuration. tags: - oauth responses: "201": description: Successful response /v1/oauth/providers/{providerKey}: delete: operationId: oauth_providers_by_providerKey_delete summary: Delete OAuth provider description: Delete a custom OAuth provider and optionally cascade-delete its apps and connections. tags: - oauth parameters: - name: providerKey in: path required: true schema: type: string responses: "200": description: Successful response get: operationId: oauth_providers_by_providerKey_get summary: Get OAuth provider description: Get a single OAuth provider by key. tags: - oauth parameters: - name: providerKey in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: provider: type: object propertyNames: type: string additionalProperties: {} oauth_callback_url: anyOf: - type: string - type: "null" required: - provider - oauth_callback_url additionalProperties: false patch: operationId: oauth_providers_by_providerKey_patch summary: Update OAuth provider description: Update an existing custom OAuth provider configuration. tags: - oauth parameters: - name: providerKey in: path required: true schema: type: string responses: "200": description: Successful response /v1/oauth/request: post: operationId: oauth_request_post summary: Make authenticated OAuth request description: Make an authenticated HTTP request through an OAuth connection (supports curl-like interface). tags: - oauth responses: "200": description: Successful response /v1/oauth/start: post: operationId: oauth_start_post summary: Start OAuth flow description: Initiate an OAuth authorization flow for a third-party service. tags: - oauth requestBody: required: true content: application/json: schema: type: object properties: service: type: string requestedScopes: type: array items: {} required: - service - requestedScopes responses: "200": description: Successful response /v1/oauth/status: get: operationId: oauth_status_get summary: Get OAuth status description: Show OAuth connection status for a specified provider (BYO or managed). tags: - oauth parameters: - name: provider in: query required: true schema: type: string description: Provider key responses: "200": description: Successful response /v1/oauth/token: post: operationId: oauth_token_post summary: Get OAuth token description: Retrieve a valid OAuth access token for a BYO-mode provider. tags: - oauth responses: "200": description: Successful response /v1/onboarding/checkin: post: operationId: onboarding_checkin_post summary: Schedule the onboarding Day 2 check-in description: "Find the first open 15-minute slot between 12pm and 5pm tomorrow (widening to 8am–8pm if booked) on the user's Google Calendar and create the Day 2 Check-in event. Best-effort: returns scheduled=false when no calendar is connected or the calendar scope wasn't granted." tags: - onboarding requestBody: required: true content: application/json: schema: type: object properties: userName: type: string assistantName: type: string timezone: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: scheduled: type: boolean reason: type: string eventId: type: string htmlLink: anyOf: - type: string - type: "null" start: type: string end: type: string timeZone: type: string required: - scheduled additionalProperties: false /v1/pages/{appId}: get: operationId: pages_by_appId_get summary: Serve app page description: Render and serve a shareable app page as HTML. tags: - apps parameters: - name: appId in: path required: true schema: type: string responses: "200": description: Successful response /v1/pending-interactions: get: operationId: pendinginteractions_get summary: List pending interactions description: Return pending interactions. When conversationKey or conversationId is provided, returns details for that conversation. When neither is provided, returns all pending interactions. tags: - approvals parameters: - name: conversationKey in: query required: false schema: type: string description: Conversation key (optional) - name: conversationId in: query required: false schema: type: string description: Conversation ID (optional) responses: "200": description: Successful response content: application/json: schema: type: object properties: pendingConfirmation: type: object properties: {} additionalProperties: {} description: Pending confirmation details or null pendingSecret: anyOf: - type: object properties: requestId: type: string service: type: string field: type: string label: type: string description: type: string placeholder: type: string purpose: type: string allowedTools: type: array items: type: string allowedDomains: type: array items: type: string allowOneTimeSend: type: boolean required: - requestId additionalProperties: {} - type: "null" description: Pending secret request or null pendingQuestion: anyOf: - type: object properties: requestId: type: string entries: type: array items: type: object properties: id: type: string question: type: string description: type: string options: type: array items: type: object properties: id: type: string label: type: string description: type: string required: - id - label additionalProperties: false freeTextPlaceholder: type: string required: - id - question - options additionalProperties: false required: - requestId - entries additionalProperties: false - type: "null" description: Outstanding ask_question prompt or null interactions: type: array items: type: object properties: requestId: type: string conversationId: type: string kind: type: string toolName: type: string riskLevel: type: string required: - requestId - kind additionalProperties: false description: All pending interactions (returned when no filters given) additionalProperties: false /v1/platform/callback-routes: get: operationId: platform_callbackroutes_get summary: List registered platform callback routes description: Lists all callback routes registered with the platform for this assistant. tags: - platform responses: "200": description: Successful response content: application/json: schema: type: object properties: routes: type: array items: type: object properties: id: type: string assistant_id: type: string type: type: string callback_path: type: string callback_url: type: string source_identifier: anyOf: - type: string - type: "null" required: - id - assistant_id - type - callback_path - callback_url - source_identifier additionalProperties: false required: - routes additionalProperties: false /v1/platform/callback-routes/register: post: operationId: platform_callbackroutes_register_post summary: Register a platform callback route description: Registers a callback route with the platform gateway for inbound provider webhooks. tags: - platform requestBody: required: true content: application/json: schema: type: object properties: path: type: string type: type: string required: - path - type responses: "200": description: Successful response content: application/json: schema: type: object properties: callbackUrl: type: string callbackPath: type: string type: type: string required: - callbackUrl - callbackPath - type additionalProperties: false /v1/platform/connect: post: operationId: platform_connect_post summary: Connect to the Vellum Platform description: Checks existing credentials and emits the show_platform_login signal for connected clients to show a login UI. tags: - platform responses: "200": description: Successful response content: application/json: schema: type: object properties: alreadyConnected: type: boolean baseUrl: type: string showPlatformLogin: type: boolean additionalProperties: false /v1/platform/credits: get: operationId: platform_credits_get summary: Get the organization's remaining credit balance description: Fetches the org's settled, pending, and effective (remaining) credit balance in USD from the platform billing summary. tags: - platform responses: "200": description: Successful response content: application/json: schema: type: object properties: remaining: type: number settled: type: number pending: type: number unit: type: string const: USD stale: type: boolean as_of: type: string required: - remaining - settled - pending - unit - stale - as_of additionalProperties: false /v1/platform/disconnect: post: operationId: platform_disconnect_post summary: Disconnect from the Vellum Platform description: Deletes stored platform credentials and emits platform_disconnected signal to connected clients. tags: - platform responses: "200": description: Successful response content: application/json: schema: type: object properties: disconnected: type: boolean const: true previousBaseUrl: anyOf: - type: string - type: "null" required: - disconnected - previousBaseUrl additionalProperties: false /v1/platform/invoices: get: operationId: platform_invoices_get summary: List one page of the organization's Stripe invoices description: Fetches one page of the org's Stripe invoice history (newest first) from the platform billing invoices endpoint. Amounts are in the currency's minor units. When has_more is true, pass the last invoice's id as starting_after to fetch the next page. tags: - platform parameters: - name: starting_after in: query required: false schema: type: string description: "Cursor: return invoices older than the invoice with this id (from the previous page's last entry)." responses: "200": description: Successful response content: application/json: schema: type: object properties: invoices: type: array items: type: object properties: id: type: string number: anyOf: - type: string - type: "null" status: anyOf: - type: string - type: "null" currency: type: string amount_due: type: number amount_paid: type: number amount_remaining: type: number created: type: number hosted_invoice_url: anyOf: - type: string - type: "null" invoice_pdf: anyOf: - type: string - type: "null" required: - id - number - status - currency - amount_due - amount_paid - amount_remaining - created - hosted_invoice_url - invoice_pdf additionalProperties: false has_more: type: boolean required: - invoices - has_more additionalProperties: false /v1/platform/invoices/{id}: get: operationId: platform_invoices_by_id_get summary: Get a single Stripe invoice by ID description: Pages through the org's invoice list from the platform and returns the invoice matching the given Stripe invoice ID (e.g. in_xxx). 404 if no such invoice. tags: - platform parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string number: anyOf: - type: string - type: "null" status: anyOf: - type: string - type: "null" currency: type: string amount_due: type: number amount_paid: type: number amount_remaining: type: number created: type: number hosted_invoice_url: anyOf: - type: string - type: "null" invoice_pdf: anyOf: - type: string - type: "null" required: - id - number - status - currency - amount_due - amount_paid - amount_remaining - created - hosted_invoice_url - invoice_pdf additionalProperties: false /v1/platform/plans: get: operationId: platform_plans_get summary: Get the plan catalog with pricing description: "Fetches the platform plan catalog: base and pro plans with pricing (in cents), machine/storage/credit tiers, and packages." tags: - platform responses: "200": description: Successful response content: application/json: schema: type: object properties: plans: type: array items: type: object propertyNames: type: string additionalProperties: {} required: - plans additionalProperties: false /v1/platform/status: get: operationId: platform_status_get summary: Get platform deployment context and connection status description: Aggregates platform context, credentials, assistant ID, and webhook secret. Velay tunnel status is reported separately by gateway_status. tags: - platform responses: "200": description: Successful response content: application/json: schema: type: object properties: isPlatform: type: boolean baseUrl: type: string assistantId: type: string hasAssistantApiKey: type: boolean hasWebhookSecret: type: boolean clientInstallationId: anyOf: - type: string - type: "null" available: type: boolean organizationId: anyOf: - type: string - type: "null" userId: anyOf: - type: string - type: "null" required: - isPlatform - baseUrl - assistantId - hasAssistantApiKey - hasWebhookSecret - clientInstallationId - available - organizationId - userId additionalProperties: false /v1/platform/subscription: get: operationId: platform_subscription_get summary: Get the organization's current plan and subscription state description: Fetches the org's plan (base or pro), subscription status, renewal/period-end dates, cancellation state, selected credit tier, package, and plan-gated entitlements from the platform. tags: - platform responses: "200": description: Successful response content: application/json: schema: type: object properties: planId: type: string enum: - base - pro status: anyOf: - type: string - type: "null" renewalDate: anyOf: - type: string - type: "null" currentPeriodEnd: anyOf: - type: string - type: "null" cancelAtPeriodEnd: type: boolean cancelAt: anyOf: - type: string - type: "null" selectedCreditTier: anyOf: - type: string - type: "null" package: anyOf: - type: object properties: key: type: string name: type: string version: type: number customized: type: boolean required: - key - name - version - customized additionalProperties: false - type: "null" entitlements: type: object properties: managedEmail: type: boolean phoneNumber: type: boolean required: - managedEmail - phoneNumber additionalProperties: false required: - planId - status - renewalDate - currentPeriodEnd - cancelAtPeriodEnd - cancelAt - selectedCreditTier - package - entitlements additionalProperties: false /v1/playground/seed-conversation: post: operationId: playground_seedconversation_post summary: Create a synthetic seeded conversation for compaction testing tags: - playground requestBody: required: true content: application/json: schema: type: object properties: turns: type: integer exclusiveMinimum: 0 maximum: 500 avgTokensPerTurn: default: 500 type: integer exclusiveMinimum: 0 maximum: 5000 title: type: string maxLength: 120 required: - turns responses: "200": description: Successful response /v1/playground/seeded-conversations: delete: operationId: playground_seededconversations_delete summary: Delete every seeded playground conversation (prefix-gated) tags: - playground responses: "200": description: Successful response get: operationId: playground_seededconversations_get summary: List conversations created by the seed-conversation endpoint tags: - playground responses: "200": description: Successful response /v1/playground/seeded-conversations/{id}: delete: operationId: playground_seededconversations_by_id_delete summary: Delete a single seeded conversation (prefix-gated) tags: - playground parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response /v1/plugins: get: operationId: plugins_get summary: List installed plugins description: Return one entry per directory under `/plugins/`, sorted alphabetically. Matches the CLI's `assistant plugins list`. Supports `?q=` for case-insensitive substring matching across plugin id, name, and description. Each entry carries a `category` (marketplace slug from the Skills taxonomy, or `null` for non-marketplace installs); the response also reports `categoryCounts` (per-category totals, computed before the category filter) and `totalCount`. `?category=` filters the returned plugins by category server-side while leaving the counts unfiltered. A marketplace outage degrades `category` to `null` without failing the list. tags: - plugins parameters: - name: q in: query required: false schema: type: string description: Optional substring filter applied to plugin id, name, and description. - name: category in: query required: false schema: type: string description: Filter installed plugins by category slug (Skills taxonomy). responses: "200": description: Successful response content: application/json: schema: type: object properties: plugins: type: array items: type: object properties: id: type: string description: Plugin's directory name (kebab-case). Matches `assistant plugins install `. name: type: string description: Display name. Equal to `id` today. enabled: type: boolean description: Whether the plugin is active in this workspace. `false` when a `.disabled` sentinel is present under its directory; `true` otherwise. description: anyOf: - type: string - type: "null" description: From `package.json#description`; `null` when unknown. version: anyOf: - type: string - type: "null" description: From `package.json#version`; `null` when unknown. path: description: Absolute path to the plugin directory on the assistant host. type: string issues: description: Non-fatal issues with this entry (missing `package.json`, malformed JSON, ...). Omitted when clean. type: array items: type: string category: description: Marketplace category slug (Skills taxonomy); null when origin/category is unknown, e.g. non-marketplace installs. anyOf: - type: string - type: "null" icon: description: Author-declared emoji icon from the plugin's package.json vellum.icon; absent when none. type: string hasIcon: description: Whether the plugin ships a valid author-bundled `icon.png` (PNG magic + dimensions + size validated). Drives whether a client fetches the bundled icon. type: boolean iconVersion: description: Content hash of the validated `icon.png`; present only when `hasIcon` is true. Use it as a cache-buster for the bundled-icon endpoint. type: string required: - id - name - enabled - description - version additionalProperties: false categoryCounts: description: Installed plugins per category (before the category filter is applied). type: object propertyNames: type: string additionalProperties: type: number totalCount: description: Total installed plugins matching non-category filters. type: number required: - plugins additionalProperties: false /v1/plugins/{name}: delete: operationId: plugins_by_name_delete summary: Uninstall a plugin description: Remove the directory at `/plugins//`. Mirrors the CLI's `assistant plugins uninstall ` (without the interactive confirmation — the API caller is responsible for any prompt). The plugin name is sanitized by the same regex the CLI uses; `../escape`-style values, hidden names, and absolute paths return 400. Missing plugins return 404. The plugin is dropped from the running runtime live on the next read (no restart required). tags: - plugins parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: name: type: string description: Directory name that was removed. Echoes the request's `:name` path parameter after sanitization. target: type: string description: Absolute path that was removed on the assistant host. Useful for audit logs and confirmation toasts. required: - name - target additionalProperties: false "400": description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters). "404": description: No plugin directory exists with the given name. get: operationId: plugins_by_name_get summary: Get a plugin's detail view description: Resolve a single plugin's tracked metadata (description, homepage, license, version, source) plus its README markdown. Unions the locally installed copy, the marketplace manifest, and the plugin's repository at the pinned ref — preferring the installed copy. Names that are neither installed nor present in the catalog return 404. Powers the web plugin detail page; mirrors `GET /v1/skills/:id`. tags: - plugins parameters: - name: name in: path required: true schema: type: string - name: ref in: query required: false schema: type: string description: Optional git ref to read catalog metadata / README at. Defaults to the CLI's `DEFAULT_PLUGIN_REF`. responses: "200": description: Successful response content: application/json: schema: type: object properties: name: type: string description: Install name. Matches `assistant plugins install `. installed: type: boolean description: Whether a copy is materialized under `/plugins//`. description: anyOf: - type: string - type: "null" description: Short description, best-effort across disk, manifest, and repo. homepage: anyOf: - type: string - type: "null" description: Project homepage URL, when known. license: anyOf: - type: string - type: "null" description: SPDX license expression, when known. version: anyOf: - type: string - type: "null" description: Resolved version (installed copy first, then repo `package.json`). source: anyOf: - type: object properties: kind: type: string const: github repo: type: string description: "`owner/repo` of the external plugin repository." path: description: Directory within the repo, when the plugin is not at the root. type: string ref: type: string description: Pinned git ref the plugin is fetched from. required: - kind - repo - ref additionalProperties: false description: "Origin of the match: a whitelisted external plugin repository." - type: "null" description: Pinned origin from the marketplace entry, or null when an installed copy has no catalog entry. readme: anyOf: - type: string - type: "null" description: README markdown, or null when the plugin ships none. ref: type: string description: Git ref the catalog metadata / README were resolved at. artifact: anyOf: - type: object properties: url: type: string description: HTTPS URL the prebuilt client artifact is downloaded from. sha256: type: string description: Lowercase 64-char hex SHA-256 the download is verified against. label: description: Optional human label for the download (e.g. "Download for macOS"); absent when the plugin doesn't name it. type: string required: - url - sha256 additionalProperties: false - type: "null" description: Prebuilt client artifact from `package.json` `vellum.artifact`, or null when the plugin ships none or its descriptor is incomplete (e.g. a placeholder sha256). icon: anyOf: - type: string - type: "null" description: Author-declared emoji icon from the plugin's `package.json` `vellum.icon`, or null when none. hasIcon: type: boolean description: Whether the locally installed copy ships a valid author-bundled `icon.png` (PNG magic + dimensions + size validated). Always false when the plugin is not installed. iconVersion: anyOf: - type: string - type: "null" description: Content hash of the validated `icon.png`; null when `hasIcon` is false. Use it as a cache-buster for the bundled-icon endpoint. required: - name - installed - description - homepage - license - version - source - readme - ref - artifact - icon - hasIcon - iconVersion additionalProperties: false "400": description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters). "404": description: No installed copy and no catalog entry claims the given name. /v1/plugins/{name}/diff: post: operationId: plugins_by_name_diff_post summary: Diff a plugin against its install commit description: "Show a unified diff of local edits to an installed plugin against the exact commit it was installed at (recorded in its `install-meta.json`). Computing the diff re-materializes the baseline through the install pipeline — a network clone plus a temp-dir write — so this is a POST: it is not a safe, cacheable GET even though it leaves persistent state untouched (requires only `settings.read`). Drift is classified against the install-time fingerprint so an adapter overlay that moved since install never reads as a local change. Returns the baseline `commit`, a `clean` flag, and a `files` array of `{ path, status, diff, binary, reconstructed }` for each modified/added/removed file. The baseline is the install commit, not the marketplace pin — comparing against the current pin is `POST /v1/plugins/:name/upgrade` with `dryRun`. A name with no installed copy returns 404; an install that recorded no commit or fingerprint returns 409; an unreachable source returns 503. Mirrors the CLI's `assistant plugins diff `." tags: - plugins parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: name: type: string description: Install name. Matches `assistant plugins install `. target: type: string description: Absolute path to the installed plugin directory on the host. commit: type: string description: Commit the baseline was re-materialized from (the recorded install SHA). committedAt: anyOf: - type: string - type: "null" description: ISO-8601 committer timestamp (UTC) of `commit`; null when not recorded. clean: type: boolean description: True when the on-disk tree exactly matches the re-materialized baseline. files: type: array items: type: object properties: path: type: string description: POSIX-relative path within the plugin root. status: type: string enum: - modified - added - removed description: Whether the file was edited, newly added, or deleted since install. diff: type: string description: Unified diff (`--- a/… / +++ b/…`) of the file. A short `Binary files differ` marker for binary files, or a `Baseline unavailable` marker when `reconstructed` is false. binary: type: boolean description: True when either side was detected as binary (NUL byte present). reconstructed: type: boolean description: True when the install-time baseline for this file was faithfully recovered (re-materialized bytes hash-match the install fingerprint). False when it could not be reconstructed (e.g. the curated adapter overlay changed since install), in which case `diff` is a marker, not a patch. Always true for added files. required: - path - status - diff - binary - reconstructed additionalProperties: false description: Unified diff of a single drifted file. description: One entry per drifted file, sorted by path. Empty when `clean`. required: - name - target - commit - committedAt - clean - files additionalProperties: false "400": description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters). "404": description: No copy of the plugin is installed, or its recorded commit resolves to nothing. "409": description: The install recorded no commit or no fingerprint to re-materialize and verify a baseline from. "503": description: The plugin source (GitHub) was temporarily unavailable; the diff is retryable. /v1/plugins/{name}/disable: post: operationId: plugins_by_name_disable_post summary: Disable a plugin description: Disable a plugin in this workspace by dropping a `.disabled` sentinel, mirroring the CLI's `assistant plugins disable `. The change is honored live at read time by every tool / injector / hook gate — no restart required. Broadcasts a `sync_changed` invalidation carrying the `plugins:list` tag so other clients refetch `GET /v1/plugins`. An already-disabled plugin returns 409; a user plugin with no directory returns 404 (default plugins are stubbed on demand via the `default-` prefix); a malformed name returns 400. tags: - plugins parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false "400": description: The plugin name failed validation (not kebab-case alphanumerics). "404": description: No plugin directory exists with the given name (user plugins must already be installed). "409": description: The plugin is already disabled. /v1/plugins/{name}/enable: post: operationId: plugins_by_name_enable_post summary: Enable a plugin description: Enable a plugin in this workspace by removing its `.disabled` sentinel, mirroring the CLI's `assistant plugins enable `. The change is honored live at read time by every tool / injector / hook gate — no restart required. Broadcasts a `sync_changed` invalidation carrying the `plugins:list` tag so other clients refetch `GET /v1/plugins`. An already-enabled plugin returns 409; a name with no plugin directory returns 404 (prefix a default plugin with `default-`); a malformed name returns 400. tags: - plugins parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false "400": description: The plugin name failed validation (not kebab-case alphanumerics). "404": description: No plugin directory exists with the given name. "409": description: The plugin is already enabled. /v1/plugins/{name}/icon: get: operationId: plugins_by_name_icon_get summary: Serve a plugin's bundled icon description: Serve the installed plugin's validated author-bundled `icon.png` as `image/png`. The PNG is re-validated on read (magic bytes + IHDR dimensions + size) and served with an immutable `Cache-Control` plus a content-hash `ETag` — the `iconVersion` reported by `GET /v1/plugins` and `GET /v1/plugins/:name` — so clients cache aggressively and only refetch when the hash changes. A plugin with no valid bundled icon returns 404; a malformed name returns 400. Pair with the `hasIcon` / `iconVersion` fields on the list and detail responses to decide whether to fetch. tags: - plugins parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: image/png: schema: type: string format: binary "404": description: No installed plugin with the given name has an icon. /v1/plugins/{name}/inspect: get: operationId: plugins_by_name_inspect_get summary: Inspect a plugin's install drift description: 'Compare the locally installed copy of a plugin against the marketplace''s current pinned commit and report whether an upgrade is available. Returns a six-way `status` (`up-to-date`, `update-available`, `not-installed`, `not-in-marketplace`, `unknown-provenance`, `remote-unavailable`) plus the local provenance (installed commit, version, source, and any local edits vs the install-time fingerprint) and the remote pin. An unreachable marketplace for an installed plugin is not fatal — it returns 200 with `status: "remote-unavailable"`. A name that is neither installed nor in the catalog returns 404. Powers the web upgrade affordance; mirrors the CLI''s `assistant plugins inspect ` and `GET /v1/skills/:id/inspect`.' tags: - plugins parameters: - name: name in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: name: type: string description: Install name. Matches `assistant plugins install `. installed: type: boolean description: Whether a copy is materialized under `/plugins/`. status: type: string enum: - up-to-date - update-available - not-installed - not-in-marketplace - unknown-provenance - remote-unavailable description: Drift classification between the installed copy and the marketplace pin. local: anyOf: - type: object properties: target: type: string description: Absolute path to the installed plugin directory. commit: anyOf: - type: string - type: "null" description: Resolved commit the copy was installed at; null when no provenance was recorded. committedAt: anyOf: - type: string - type: "null" description: ISO-8601 committer timestamp (UTC) of the installed commit — the human-readable version; null for installs predating commit-timestamp capture. Distinct from `installedAt`. version: anyOf: - type: string - type: "null" description: Installed `package.json#version`. description: anyOf: - type: string - type: "null" description: Installed `package.json#description`. installedAt: anyOf: - type: string - type: "null" description: ISO-8601 install timestamp from the sidecar; null when absent. source: anyOf: - type: object properties: kind: type: string description: Source kind. Only `github` is written today. owner: type: string repo: type: string path: description: Repo-relative directory holding the plugin root; absent = repo root. type: string ref: type: string description: Ref the install resolved through (the pinned commit SHA for marketplace installs). required: - kind - owner - repo - ref additionalProperties: false description: Source coordinates recorded in the install-time provenance sidecar. - type: "null" description: Source recorded at install time; null when no sidecar exists. localChanges: anyOf: - type: object properties: modified: type: array items: type: string description: Tracked files whose content changed since install. added: type: array items: type: string description: Files present on disk but absent from the install baseline. removed: type: array items: type: string description: Files recorded at install but missing from the on-disk copy. clean: type: boolean description: True when no files were added, removed, or modified. required: - modified - added - removed - clean additionalProperties: false description: Local-edit comparison of the on-disk tree against the install-time fingerprint. - type: "null" description: Local-edit state vs the install-time fingerprint; null when no baseline was recorded (older/manual install). issues: type: array items: type: string description: Non-fatal issues with the installed copy (e.g. malformed `package.json`). required: - target - commit - committedAt - version - description - installedAt - source - localChanges - issues additionalProperties: false description: The locally installed copy of the plugin. - type: "null" description: Locally installed copy; null when the plugin is not installed. remote: anyOf: - type: object properties: repo: type: string description: "`owner/repo` of the external plugin repository." path: type: string description: Repo-relative directory holding the plugin root; `""` = repo root. commit: type: string description: Pinned commit SHA the marketplace currently resolves installs to. committedAt: anyOf: - type: string - type: "null" description: ISO-8601 committer timestamp (UTC) of the pinned commit, resolved from GitHub; null when the commit metadata could not be fetched. description: anyOf: - type: string - type: "null" homepage: anyOf: - type: string - type: "null" license: anyOf: - type: string - type: "null" category: anyOf: - type: string - type: "null" marketplaceRef: type: string description: Ref of the canonical repo the marketplace manifest was read from. required: - repo - path - commit - committedAt - description - homepage - license - category - marketplaceRef additionalProperties: false description: The marketplace's current pin and advertised metadata. - type: "null" description: Marketplace pin + metadata; null when no entry claims the name or it was unreachable. remoteError: anyOf: - type: string - type: "null" description: Marketplace fetch error message, when the catalog could not be read. surfaces: anyOf: - type: object properties: skills: type: array items: type: string description: Skill ids shipped at `skills//SKILL.md`. hooks: type: array items: type: string description: Lifecycle hook names from `hooks/.{ts,js}` (e.g. `pre-model-call`). tools: type: array items: type: string description: Registered tool names from `tools/.{ts,js}` (filenames derived to tool names, e.g. `create-issue` → `create_issue`). schedules: type: array items: type: object properties: name: type: string description: "Schedule name: the declaration directory's name." cadence: type: string description: Raw schedule `expression` string from the declaration's config. mode: type: string enum: - execute - script description: "`execute` for a markdown prompt entrypoint, `script` for `index.sh`." required: - name - cadence - mode additionalProperties: false description: Schedules declared under `schedules/`, each a `/` directory with `config.json` plus one entrypoint. Display surface only; files directly under `schedules/` and unsupported declarations are omitted. required: - skills - hooks - tools - schedules additionalProperties: false description: Surfaces the installed copy contributes, read from its on-disk tree. - type: "null" description: Surfaces the installed copy contributes (skills, hooks, tools, schedules); null when the plugin is not installed. required: - name - installed - status - local - remote - remoteError - surfaces additionalProperties: false "400": description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters). "404": description: No installed copy and no catalog entry claims the given name. /v1/plugins/{name}/upgrade: post: operationId: plugins_by_name_upgrade_post summary: Upgrade a plugin to its source's current revision description: 'Move an installed plugin to its source''s current revision, re-materializing it under `/plugins//`. A marketplace plugin advances to the curated pin; a plugin installed directly from a GitHub URL (untrusted, not in the marketplace) advances to whatever its recorded ref now resolves to — a pinned SHA is immutable (a no-op), a branch/tag/HEAD moves as upstream does — re-materialized verbatim with no curated adapter overlay, exactly as the original untrusted install was. The target ref is never taken from the request (no caller-supplied ref), mirroring `plugins install`''s curation boundary. A no-op (`outcome: "already-up-to-date"`) when the installed commit already equals the target; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching the install. Installs lacking provenance are re-pinned to the current SHA. The upgraded code is picked up live on the next read (no restart required). `strategy` controls how local edits are reconciled: `overwrite` (default) discards them and re-installs the target wholesale; `ours`/`theirs`/`assistant` perform a three-way merge against the re-materialized install commit, carrying non-conflicting edits from both sides forward and resolving conflicting hunks toward the local edit (`ours`) or the target (`theirs`), or writing git conflict markers into the file and reporting them in `conflicts`/`binaryConflicts` for the assistant to resolve (`assistant`). A merge strategy whose install-time baseline cannot be reconstructed returns 409. Pass `marketplaceOnly` to refuse the untrusted direct path outright (409), which is what the unattended auto-update sweep does. Mirrors the CLI''s `assistant plugins upgrade [--strategy ]`.' tags: - plugins parameters: - name: name in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: dryRun: description: Report what would change without modifying the install. Defaults to false. type: boolean strategy: description: How to reconcile local edits with the pin. `overwrite` (default) discards local edits and re-installs the pin; `ours`/`theirs` three-way merge, resolving conflicting hunks toward the local edit or the pin respectively; `assistant` is not yet supported. type: string enum: - ours - theirs - overwrite - assistant marketplaceOnly: description: Refuse the upgrade (409) when the marketplace does not claim this plugin, instead of advancing it to whatever its recorded GitHub ref now resolves to. Set by unattended callers such as the automatic update sweep, for which running code no curator reviewed is never an acceptable outcome. Defaults to false. type: boolean responses: "200": description: Successful response content: application/json: schema: type: object properties: name: type: string description: Install name that was (or would be) upgraded. outcome: type: string enum: - upgraded - already-up-to-date - would-upgrade description: "`upgraded` moved the install to the pin; `already-up-to-date` was a no-op; `would-upgrade` is a dry-run that found drift." fromCommit: anyOf: - type: string - type: "null" description: Installed commit before the upgrade; null when no provenance was recorded. fromTimestamp: anyOf: - type: string - type: "null" description: ISO-8601 committer timestamp (UTC) of `fromCommit` — the version moved from; null when not recorded. toCommit: type: string description: Marketplace-pinned commit the install was (or would be) moved to. toTimestamp: anyOf: - type: string - type: "null" description: ISO-8601 committer timestamp (UTC) of `toCommit` — the version moved to; null when it could not be resolved. target: type: string description: Absolute path to the installed plugin directory on the host. fileCount: anyOf: - type: number - type: "null" description: Files materialized by the upgrade; null for a no-op or dry run. dryRun: type: boolean description: Whether this was a dry run (no changes made). strategy: type: string enum: - ours - theirs - overwrite - assistant description: Conflict-resolution strategy the upgrade applied. conflicts: type: array items: type: string description: "Paths left for the assistant to resolve under the `assistant` strategy: text files carry git conflict markers, modify/delete divergences keep the surviving content. Empty for other strategies." binaryConflicts: type: array items: type: string description: Binary files that conflicted under the `assistant` strategy; the local copy was kept since markers cannot be written into binary content. Empty for other strategies. provenanceWasUnknown: type: boolean description: Whether the install lacked resolvable provenance before the upgrade; such installs are re-pinned to record it going forward. required: - name - outcome - fromCommit - fromTimestamp - toCommit - toTimestamp - target - fileCount - dryRun - strategy - conflicts - binaryConflicts - provenanceWasUnknown additionalProperties: false "400": description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters). "404": description: No copy of the plugin is installed, or its source resolves to nothing. "409": description: The install has neither a marketplace entry nor a recorded GitHub source to advance to, a `marketplaceOnly` upgrade was requested for an install the marketplace does not claim, or a merge strategy was requested whose install-time baseline cannot be reconstructed. "503": description: The plugin source (GitHub) was temporarily unavailable; the upgrade is retryable. /v1/plugins/{name}/versions: get: operationId: plugins_by_name_versions_get summary: List a plugin's reviewed marketplace pins description: Report the distinct marketplace pins a plugin has been promoted to over time, newest first (the first entry is the current pin), capped at `limit` (default 5). The curated `marketplace.json` stores only the current pin, so this is reconstructed from the manifest's own commit history on the default branch — every entry is therefore a reviewed, known-good revision. Pair with `POST /v1/plugins/install`'s `pin` field to roll a plugin back to an older reviewed version. An unknown name (never in the manifest) returns an empty array, not 404. tags: - plugins parameters: - name: name in: path required: true schema: type: string - name: limit in: query required: false schema: type: string description: Maximum number of pins to return (positive integer; default 5). responses: "200": description: Successful response content: application/json: schema: type: array items: type: object properties: pin: type: string description: Plugin commit SHA pinned at this point in marketplace history. marketplaceCommit: type: string description: Marketplace-manifest commit to install this pin from (the newest commit carrying it). promotedAt: anyOf: - type: string - type: "null" description: ISO-8601 committer date (UTC) of the marketplace commit that promoted this pin; null when unreadable. current: type: boolean description: True for the pin currently active on the default branch. required: - pin - marketplaceCommit - promotedAt - current additionalProperties: false description: Distinct marketplace pins a plugin has been promoted to, newest first; the first entry is the current pin. Empty when the plugin has no resolvable history. "400": description: The plugin name failed sanitization, or `limit` was not a positive integer. "503": description: The marketplace pin history could not be read from GitHub (rate-limited or upstream error); retryable. /v1/plugins/install: post: operationId: plugins_install_post summary: Install a plugin description: "Install a plugin by name from the canonical source — a whitelisted `plugins/marketplace.json` entry. Always resolves against the curated default git ref (no caller-supplied ref): installing from an unreviewed revision would bypass the marketplace curation boundary and let attacker-controlled code be loaded. Materializes the plugin under `/plugins//`; the plugin is picked up live on the next read (no restart required). Mirrors the CLI's `assistant plugins install `. An already-installed name without `force` returns 409; a name that resolves to nothing returns 404. Sibling to `POST /v1/skills/install`." tags: - plugins requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Install name to resolve against the marketplace catalog. force: description: Overwrite an existing install in place. Defaults to false. type: boolean pin: description: Install a specific reviewed marketplace pin (full commit SHA) instead of the current one. The pin is validated against the plugin's marketplace pin history (`GET /v1/plugins/:name/versions`) and installed from the marketplace revision that introduced it; an unreviewed SHA is rejected. Use this to roll a plugin back to an older reviewed version. type: string required: - name responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean const: true name: type: string description: Install name that was materialized. target: type: string description: Absolute path the plugin was materialized into on the host. fileCount: type: number description: Number of files written for the installed plugin. ref: type: string description: Git ref the plugin was fetched from. required: - ok - name - target - fileCount - ref additionalProperties: false "400": description: The request body was missing `name` or the name failed sanitization. "404": description: No plugin resolves to the given name at the requested ref. "409": description: A plugin with the same name is already installed and `force` was not set. /v1/plugins/search: get: operationId: plugins_search_get summary: Search the plugin catalog description: List installable plugins from the curated `plugins/marketplace.json` catalog. The query is an ECMAScript regex matched case-insensitively against the plugin name (e.g. `memory`, `^simple`). Empty query returns every entry. Mirrors the CLI's `assistant plugins search`. tags: - plugins parameters: - name: q in: query required: false schema: type: string description: ECMAScript regex pattern matched case-insensitively against catalog directory names. Empty/missing matches everything. - name: ref in: query required: false schema: type: string description: Accepted for backward compatibility. The catalog is resolved from the Vellum platform (or the bundled manifest when platform features are disabled); this ref does not select a git revision — it is echoed back and used as the cache key. Defaults to the CLI's `DEFAULT_PLUGIN_REF` (typically `main`). responses: "200": description: Successful response content: application/json: schema: type: object properties: query: type: string description: Echo of the requested query (ECMAScript regex source). ref: type: string description: Git ref the catalog was listed at. matches: type: array items: type: object properties: name: type: string description: Install name. Matches `assistant plugins install `. path: type: string description: "Human-readable origin: a `github:owner/repo@ref` locator for the external plugin." description: description: Short description, when known (external entries only today). type: string icon: description: "Plugin icon: a curated emoji from the marketplace entry, or an icon URL served by the platform catalog when the plugin ships a bundled image." type: string category: anyOf: - type: string - type: "null" description: Marketplace category slug (Skills taxonomy); null when the entry declares none. source: type: object properties: kind: type: string const: github repo: type: string description: "`owner/repo` of the external plugin repository." path: description: Directory within the repo, when the plugin is not at the root. type: string ref: type: string description: Pinned git ref the plugin is fetched from. required: - kind - repo - ref additionalProperties: false description: "Origin of the match: a whitelisted external plugin repository." required: - name - path - category - source additionalProperties: false description: Directory matches, sorted alphabetically by name. required: - query - ref - matches additionalProperties: false /v1/profiler/runs: get: operationId: profiler_runs_get summary: List profiler runs description: Enumerate all profiler run directories with manifest metadata, sorted newest-first. tags: - profiler responses: "200": description: Successful response content: application/json: schema: type: object properties: runs: type: array items: type: object properties: runId: type: string status: type: string enum: - active - completed createdAt: type: string updatedAt: type: string totalBytes: type: number completedAt: type: string required: - runId - status - createdAt - updatedAt - totalBytes additionalProperties: false totalRuns: type: number activeRunId: anyOf: - type: string - type: "null" required: - runs - totalRuns - activeRunId additionalProperties: false /v1/profiler/runs/{runId}: delete: operationId: profiler_runs_by_runId_delete summary: Delete profiler run description: Delete a completed profiler run and recalculate disk-budget state. Rejects deletion of the currently active run. tags: - profiler parameters: - name: runId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: deleted: type: boolean runId: type: string remainingRuns: type: number activeRunOverBudget: type: boolean required: - deleted - runId - remainingRuns - activeRunOverBudget additionalProperties: false get: operationId: profiler_runs_by_runId_get summary: Get profiler run detail description: Return manifest metadata, Bun-generated markdown summary, and current retention state for a single profiler run. tags: - profiler parameters: - name: runId in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: runId: type: string status: type: string enum: - active - completed createdAt: type: string updatedAt: type: string totalBytes: type: number completedAt: type: string summary: anyOf: - type: string - type: "null" isActive: type: boolean budget: type: object properties: maxBytes: type: number totalBytesAllRuns: type: number remainingBytes: type: number overBudget: type: boolean required: - maxBytes - totalBytesAllRuns - remainingBytes - overBudget additionalProperties: false required: - runId - status - createdAt - updatedAt - totalBytes - summary - isActive - budget additionalProperties: false /v1/profiler/runs/{runId}/export: post: operationId: profiler_runs_by_runId_export_post summary: Export profiler run description: Package a single profiler run directory as a tar.gz bundle, subject to the same archive size limits used by runtime log exports. tags: - profiler parameters: - name: runId in: path required: true schema: type: string responses: "200": description: Successful response /v1/ps: get: operationId: ps_get summary: Process status description: "Returns the daemon's process tree: every descendant process parented to the assistant runtime, built from the native OS process table." tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: processes: type: array items: $ref: "#/components/schemas/ProcessEntry" required: - processes additionalProperties: false /v1/question-response: post: operationId: questionresponse_post summary: Resolve a pending ask-question prompt description: Submit the user's batched response (or close the card) for a pending question prompt by requestId. Legacy single-question payloads remain accepted as syntactic sugar for a one-element batch. tags: - approvals requestBody: required: true content: application/json: schema: oneOf: - type: object properties: requestId: type: string kind: type: string const: submit responses: minItems: 1 type: array items: oneOf: - type: object properties: questionId: type: string kind: type: string const: option optionId: type: string required: - questionId - kind - optionId - type: object properties: questionId: type: string kind: type: string const: free_text text: type: string required: - questionId - kind - text - type: object properties: questionId: type: string kind: type: string const: skip required: - questionId - kind type: object required: - requestId - kind - responses - type: object properties: requestId: type: string kind: type: string const: close required: - requestId - kind - type: object properties: requestId: type: string kind: type: string const: option optionId: type: string required: - requestId - kind - optionId - type: object properties: requestId: type: string kind: type: string const: free_text text: type: string required: - requestId - kind - text type: object responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false /v1/recordings/pause: post: operationId: recordings_pause_post summary: Pause recording description: Pause the active screen recording. tags: - recordings requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: recordingId: type: string paused: type: boolean required: - recordingId - paused additionalProperties: false /v1/recordings/resume: post: operationId: recordings_resume_post summary: Resume recording description: Resume a paused screen recording. tags: - recordings requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: recordingId: type: string resumed: type: boolean required: - recordingId - resumed additionalProperties: false /v1/recordings/start: post: operationId: recordings_start_post summary: Start recording description: Start a screen recording for a conversation. tags: - recordings requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string options: type: object properties: {} additionalProperties: {} description: Recording options required: - conversationId responses: "201": description: Successful response content: application/json: schema: type: object properties: recordingId: type: string required: - recordingId additionalProperties: false /v1/recordings/status: get: operationId: recordings_status_get summary: Get recording status description: Return the current recording state. tags: - recordings responses: "200": description: Successful response content: application/json: schema: type: object properties: idle: type: boolean restartInProgress: type: boolean required: - idle - restartInProgress additionalProperties: false post: operationId: recordings_status_post summary: Post recording status description: Recording lifecycle callback from the client. tags: - recordings requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string status: type: string description: started, stopped, failed, restart_cancelled, paused, resumed filePath: type: string durationMs: type: number error: type: string attachToConversationId: type: string operationToken: type: string required: - conversationId - status responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/recordings/stop: post: operationId: recordings_stop_post summary: Stop recording description: Stop the active screen recording. tags: - recordings requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: recordingId: type: string stopped: type: boolean required: - recordingId - stopped additionalProperties: false /v1/resolve_contact_prompt: post: operationId: resolve_contact_prompt_post summary: "Gateway callback: resolve a pending contact prompt" description: Called by the gateway after it writes the contact and channel. Unblocks the waiting contacts/prompt IPC call. tags: - contacts responses: "200": description: Successful response /v1/resource-pressure/status: get: operationId: resourcepressure_status_get summary: Get resource pressure status description: Return the current resource pressure status snapshot. Off-platform the guard does not run, so a disabled status is returned. tags: - resource-pressure responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: object properties: enabled: type: boolean state: type: string enum: - disabled - ok - elevated - unknown cpuPercent: anyOf: - type: number - type: "null" memoryPercent: anyOf: - type: number - type: "null" cpuElevated: type: boolean memoryElevated: type: boolean cpuThresholdPercent: type: number memoryThresholdPercent: type: number lastCheckedAt: anyOf: - type: string - type: "null" error: anyOf: - type: string - type: "null" required: - enabled - state - cpuPercent - memoryPercent - cpuElevated - memoryElevated - cpuThresholdPercent - memoryThresholdPercent - lastCheckedAt - error additionalProperties: false required: - status additionalProperties: false /v1/retrospective/config: get: operationId: retrospective_config_get summary: Get memory retrospective config description: Return the memory retrospective configuration. Retrospectives are event-driven background passes triggered per conversation after activity (time/message thresholds, pre-compaction) — there is no global schedule, so `nextRunAt` is always null and no run-now endpoint exists. `intervalMs` is the per-conversation time threshold (`memory.retrospective.timeThresholdMs`), `lastRunAt` is the `createdAt` of the most recent retrospective conversation across both legacy and fork sources, `available` gates on `memory.enabled` (not `memory.v2.enabled`), and `enabled` narrows that by `memory.retrospective.enabled`, the per-pass kill switch that stops retrospectives without disabling the rest of memory. tags: - retrospective responses: "200": description: Successful response content: application/json: schema: type: object properties: available: type: boolean enabled: type: boolean intervalMs: type: number nextRunAt: anyOf: - type: number - type: "null" lastRunAt: anyOf: - type: number - type: "null" success: type: boolean required: - available - enabled - intervalMs - nextRunAt - lastRunAt - success additionalProperties: false /v1/retrospective/runs: get: operationId: retrospective_runs_get summary: List memory retrospective runs description: "Return recent memory retrospective conversations as run records, merged across both sources (`memory-retrospective` → kind `legacy`, `memory-retrospective-fork` → kind `fork`) and sorted newest first. Each retrospective dispatch creates exactly one background conversation; that conversation IS the run. Shape mirrors `consolidation/runs` (synthetic `id`/`scheduledFor`/`startedAt` from the conversation row, `finishedAt`/`status` from assistant-message presence, `skipReason`/`error` always null) plus `kind` and `title` (fork runs are titled ' (Retrospective)', which identifies what was reviewed). For fork runs, copied source messages keep their original timestamps, so only assistant messages at or after the fork's creation count as agent output. NOTE: superseded runs are garbage-collected by default (`memory.retrospective.keepSupersededRuns: false` deletes the prior run when a newer one succeeds), so this lists what currently exists — typically the most recent run per source conversation unless the operator retains history." tags: - retrospective parameters: - name: limit in: query required: false schema: type: integer description: Max runs to return (default 20, max 100) - name: before in: query required: false schema: type: integer description: "Cursor for older runs: pass the previous page's `nextCursor` to return runs strictly older than it." responses: "200": description: Successful response content: application/json: schema: type: object properties: runs: type: array items: type: object properties: id: type: string scheduledFor: type: number startedAt: anyOf: - type: number - type: "null" finishedAt: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" status: type: string enum: - ok - running skipReason: anyOf: - type: string - type: "null" error: anyOf: - type: string - type: "null" conversationId: anyOf: - type: string - type: "null" conversationExists: type: boolean conversationArchivedAt: anyOf: - type: number - type: "null" estimatedCostUsd: type: number createdAt: type: number kind: type: string enum: - legacy - fork title: anyOf: - type: string - type: "null" required: - id - scheduledFor - startedAt - finishedAt - durationMs - status - skipReason - error - conversationId - conversationExists - conversationArchivedAt - estimatedCostUsd - createdAt - kind - title additionalProperties: false description: Retrospective run records nextCursor: anyOf: - type: number - type: "null" description: Cursor for fetching older runs (pass as `before`); null when no older runs exist required: - runs - nextCursor additionalProperties: false /v1/routes/worker/start: post: operationId: routes_worker_start_post summary: Start the route host description: Spawns (or reuses) the route host process as a child of the daemon. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: pid: type: number alreadyRunning: type: boolean pidPath: type: string required: - pid - alreadyRunning - pidPath additionalProperties: false /v1/routes/worker/status: get: operationId: routes_worker_status_get summary: Route host status description: Reports the route host process liveness. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - running - not_running pid: type: number required: - status additionalProperties: false /v1/routes/worker/stop: post: operationId: routes_worker_stop_post summary: Stop the route host description: SIGTERMs the route host process if it is running; the next request respawns it. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: workerWasRunning: type: boolean pid: type: number required: - workerWasRunning additionalProperties: false /v1/sanity/connect: post: operationId: sanity_connect_post summary: Finalise Sanity connection and write sidecar file tags: - sanity requestBody: required: true content: application/json: schema: type: object properties: projectId: type: string dataset: type: string required: - projectId - dataset responses: "200": description: Successful response /v1/sanity/discover: post: operationId: sanity_discover_post summary: Discover Sanity projects and datasets using the stored API token tags: - sanity requestBody: required: true content: application/json: schema: type: object properties: projectId: type: string responses: "200": description: Successful response /v1/schedules: get: operationId: schedules_get summary: List schedules description: Return all scheduled jobs. tags: - schedules parameters: - name: include_all in: query required: false schema: type: string description: When 'true', include deferred schedules that are normally hidden. - name: inference_profile in: query required: false schema: type: string description: Return only schedules pinned to this inference profile (llm.profiles key). responses: "200": description: Successful response content: application/json: schema: type: object properties: schedules: type: array items: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: Schedule objects required: - schedules additionalProperties: false post: operationId: schedules_post summary: Create schedule description: Create a new recurring schedule (execute, script, or workflow mode). tags: - schedules requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: Display name description: type: string description: Authored schedule description. Defaults to the schedule name when omitted for backward compatibility. expression: type: string description: Cron or RRULE expression message: type: string description: Message body to execute on each fire. Required for execute mode; ignored for workflow mode (which triggers workflowName/workflowArgs). timezone: anyOf: - type: string - type: "null" description: IANA timezone, e.g. America/New_York enabled: type: boolean description: Whether the schedule starts active (default true) mode: type: string description: "'execute' (default), 'script', or 'workflow' (flag-gated)" workflowName: type: string description: Saved workflow to trigger (required for workflow mode) workflowArgs: description: Args passed to the workflow run (workflow mode) script: type: string description: Shell command run on each fire (required for script mode) timeoutMs: anyOf: - type: number - type: "null" description: Script execution timeout override in ms (script mode) inferenceProfile: anyOf: - type: string - type: "null" description: Inference profile (llm.profiles key) the schedule's runs use. Omitted or null pins the schedule to the currently resolved default profile, so its model does not move when that default changes. Workflow-mode schedules resolve a model per workflow step, so the pin is recorded but does not govern their runs. required: - name - expression responses: "200": description: Successful response content: application/json: schema: type: object properties: schedule: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: The created schedule required: - schedule additionalProperties: false /v1/schedules/{id}: delete: operationId: schedules_by_id_delete summary: Delete schedule description: Remove a schedule by ID. tags: - schedules parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: schedules: type: array items: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: Updated schedule list required: - schedules additionalProperties: false get: operationId: schedules_by_id_get summary: Get schedule description: Return a single schedule by ID. tags: - schedules parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: schedule: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: Schedule object required: - schedule additionalProperties: false patch: operationId: schedules_by_id_patch summary: Update schedule description: Partially update fields on a schedule. tags: - schedules parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: type: string expression: type: string timezone: type: string message: type: string script: anyOf: - type: string - type: "null" description: Shell command for script mode mode: type: string description: notify, execute, script, wake, or workflow workflowName: anyOf: - type: string - type: "null" description: Saved workflow to trigger (workflow mode) workflowArgs: description: Args passed to the workflow run (workflow mode) routingIntent: type: string description: single_channel, multi_channel, or all_channels quiet: type: boolean reuseConversation: type: boolean maxRetries: type: number description: Maximum retry attempts retryBackoffMs: type: number description: Retry backoff in milliseconds timeoutMs: anyOf: - type: number - type: "null" description: Script-mode execution timeout in ms; null = use default inferenceProfile: anyOf: - type: string - type: "null" description: Inference profile (llm.profiles key) the schedule's runs use; null re-pins the schedule to the currently resolved default profile. Workflow-mode schedules resolve a model per workflow step, so the pin is recorded but does not govern their runs. responses: "200": description: Successful response content: application/json: schema: type: object properties: schedules: type: array items: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: Updated schedule list required: - schedules additionalProperties: false /v1/schedules/{id}/cancel: post: operationId: schedules_by_id_cancel_post summary: Cancel schedule description: Cancel a pending schedule. tags: - schedules parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: schedules: type: array items: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: Updated schedule list required: - schedules additionalProperties: false /v1/schedules/{id}/run: post: operationId: schedules_by_id_run_post summary: Run schedule now description: Trigger an immediate execution of a schedule. A plugin-sourced schedule is rejected with a 400 when its plugin is disabled or no longer declares it. tags: - schedules parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: schedules: type: array items: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: Updated schedule list required: - schedules additionalProperties: false /v1/schedules/{id}/runs: get: operationId: schedules_by_id_runs_get summary: List schedule runs description: Return recent invocation history for a schedule. tags: - schedules parameters: - name: id in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer description: Max runs to return (default 10, max 100) - name: before in: query required: false schema: type: integer description: "Cursor for older runs: pass the previous page's `nextCursor` to return runs strictly older than it." responses: "200": description: Successful response content: application/json: schema: type: object properties: runs: type: array items: type: object properties: id: type: string jobId: type: string status: type: string startedAt: type: number finishedAt: anyOf: - type: number - type: "null" durationMs: anyOf: - type: number - type: "null" output: anyOf: - type: string - type: "null" error: anyOf: - type: string - type: "null" conversationId: anyOf: - type: string - type: "null" conversationExists: type: boolean conversationArchivedAt: anyOf: - type: number - type: "null" conversations: type: array items: type: object properties: id: type: string title: anyOf: - type: string - type: "null" exists: type: boolean archivedAt: anyOf: - type: number - type: "null" required: - id - title - exists - archivedAt additionalProperties: false estimatedCostUsd: type: number createdAt: type: number required: - id - jobId - status - startedAt - finishedAt - durationMs - output - error - conversationId - conversationExists - conversationArchivedAt - conversations - estimatedCostUsd - createdAt additionalProperties: false description: Schedule run objects nextCursor: anyOf: - type: number - type: "null" description: Cursor for fetching older runs (pass as `before`); null when no older runs exist required: - runs - nextCursor additionalProperties: false /v1/schedules/{id}/toggle: post: operationId: schedules_by_id_toggle_post summary: Toggle schedule description: Enable or disable a schedule. On a plugin-managed schedule this records the user's override (userEnabled). tags: - schedules parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: enabled: type: boolean description: New enabled state required: - enabled responses: "200": description: Successful response content: application/json: schema: type: object properties: schedules: type: array items: type: object properties: id: type: string name: type: string enabled: type: boolean syntax: type: string enum: - cron - rrule expression: anyOf: - type: string - type: "null" cronExpression: anyOf: - type: string - type: "null" timezone: anyOf: - type: string - type: "null" message: type: string script: anyOf: - type: string - type: "null" nextRunAt: type: number lastRunAt: anyOf: - type: number - type: "null" lastStatus: anyOf: - type: string - type: "null" retryCount: type: number maxRetries: type: number retryBackoffMs: type: number timeoutMs: anyOf: - type: number - type: "null" inferenceProfile: anyOf: - type: string - type: "null" groupId: anyOf: - type: string - type: "null" createdFromConversationId: anyOf: - type: string - type: "null" createdFromConversationExists: type: boolean createdFromConversationArchivedAt: anyOf: - type: number - type: "null" description: type: string cadenceDescription: type: string mode: type: string enum: - notify - execute - script - wake - workflow status: type: string enum: - active - firing - fired - cancelled routingIntent: type: string enum: - single_channel - multi_channel - all_channels reuseConversation: type: boolean wakeConversationId: anyOf: - type: string - type: "null" workflowName: anyOf: - type: string - type: "null" sourceKey: anyOf: - type: string - type: "null" description: Plugin declaration this schedule mirrors (plugin:/); null for user-created schedules userEnabled: anyOf: - type: boolean - type: "null" description: User enable/disable override on a plugin-sourced schedule; null when the declaration's own enabled value applies. Always null for user-created schedules. disarmReason: anyOf: - type: string enum: - user_disabled - plugin_removed - plugin_disabled - declaration_removed - declaration_disabled - type: "null" description: "Why a plugin-sourced schedule is off: the user turned it off, the plugin is gone, the plugin is disabled, the declaration is gone, or the plugin's own files turned it off. Null whenever the schedule is on, and always null for user-created schedules." isOneShot: type: boolean isDeferred: type: boolean required: - id - name - enabled - syntax - expression - cronExpression - timezone - message - script - nextRunAt - lastRunAt - lastStatus - retryCount - maxRetries - retryBackoffMs - timeoutMs - inferenceProfile - groupId - createdFromConversationId - createdFromConversationExists - createdFromConversationArchivedAt - description - cadenceDescription - mode - status - routingIntent - reuseConversation - wakeConversationId - workflowName - sourceKey - userEnabled - disarmReason - isOneShot - isDeferred additionalProperties: false description: Updated schedule list required: - schedules additionalProperties: false /v1/schedules/reassign-profile: post: operationId: schedules_reassignprofile_post summary: Reassign schedules to another inference profile description: Move schedules onto one inference profile. Pass 'from' to move only the schedules pinned to that profile, so deleting a profile does not leave its schedules pointing at a name that no longer exists. Omit 'from' to move every schedule, which re-pins the whole set onto one profile. Schedules already pinned to the target are skipped. tags: - schedules requestBody: required: true content: application/json: schema: type: object properties: from: description: Inference profile key the schedules are pinned to now; omit to select every schedule type: string to: type: string description: Inference profile key to move them to; must be configured required: - to responses: "200": description: Successful response content: application/json: schema: type: object properties: reassigned: type: number description: Number of schedules moved required: - reassigned additionalProperties: false /v1/schedules/usage-summary: get: operationId: schedules_usagesummary_get summary: Get schedule usage summaries description: Return per-schedule run counts and usage totals for a time range. tags: - schedules parameters: - name: from in: query required: true schema: type: integer description: Start epoch millis (required) - name: to in: query required: true schema: type: integer description: End epoch millis (required) responses: "200": description: Successful response content: application/json: schema: type: object properties: summaries: type: array items: type: object properties: scheduleId: type: string runCount: type: number totalEstimatedCostUsd: type: number eventCount: type: number required: - scheduleId - runCount - totalEstimatedCostUsd - eventCount additionalProperties: false description: Schedule usage summary rows required: - summaries additionalProperties: false /v1/schedules/worker/start: post: operationId: schedules_worker_start_post summary: Start the schedule worker description: Spawns (or reuses) the schedule worker process as a child of the daemon. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: pid: type: number alreadyRunning: type: boolean pidPath: type: string required: - pid - alreadyRunning - pidPath additionalProperties: false /v1/schedules/worker/status: get: operationId: schedules_worker_status_get summary: Schedule worker status description: Reports the schedule worker process liveness. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: status: type: string enum: - running - not_running pid: type: number required: - status additionalProperties: false /v1/schedules/worker/stop: post: operationId: schedules_worker_stop_post summary: Stop the schedule worker description: SIGTERMs the schedule worker process if it is running. tags: - system responses: "200": description: Successful response content: application/json: schema: type: object properties: workerWasRunning: type: boolean pid: type: number required: - workerWasRunning additionalProperties: false /v1/search: get: operationId: search_get summary: Search conversations description: Full-text search across all conversations. tags: - conversations responses: "200": description: Successful response content: application/json: schema: type: object properties: query: type: string results: type: array items: {} required: - query - results additionalProperties: false /v1/search/global: get: operationId: search_global_get summary: Global search description: Federated search across conversations, memories, schedules, and contacts. tags: - search parameters: - name: q in: query required: true schema: type: string description: Search query (required) - name: limit in: query required: false schema: type: integer description: Max results per category (1–100, default 20) - name: categories in: query required: false schema: type: string description: Comma-separated categories to search - name: deep in: query required: false schema: type: string description: Enable semantic search for memories (true/false) responses: "200": description: Successful response content: application/json: schema: type: object properties: query: type: string queryTokens: type: array items: type: string results: type: object properties: conversations: type: array items: type: object properties: id: type: string title: anyOf: - type: string - type: "null" updatedAt: type: number excerpt: type: string matchCount: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - id - title - updatedAt - excerpt - matchCount additionalProperties: false memories: type: array items: type: object properties: id: type: string kind: type: string text: type: string subject: anyOf: - type: string - type: "null" confidence: type: number updatedAt: type: number source: type: string enum: - lexical - semantic required: - id - kind - text - subject - confidence - updatedAt - source additionalProperties: false schedules: type: array items: type: object properties: id: type: string name: type: string expression: anyOf: - type: string - type: "null" message: type: string enabled: type: boolean nextRunAt: anyOf: - type: number - type: "null" required: - id - name - expression - message - enabled - nextRunAt additionalProperties: false contacts: type: array items: type: object properties: id: type: string displayName: type: string notes: anyOf: - type: string - type: "null" lastInteraction: anyOf: - type: number - type: "null" required: - id - displayName - notes - lastInteraction additionalProperties: false required: - conversations - memories - schedules - contacts additionalProperties: false required: - query - queryTokens - results additionalProperties: false /v1/secret: post: operationId: secret_post summary: Resolve a pending secret request description: Provide a secret value for a pending secret request. tags: - approvals requestBody: required: true content: application/json: schema: type: object properties: requestId: type: string description: Pending interaction request ID value: type: string description: Secret value delivery: type: string description: "Delivery mode: store or transient_send" required: - requestId responses: "200": description: Successful response content: application/json: schema: type: object properties: accepted: type: boolean required: - accepted additionalProperties: false /v1/secrets: delete: operationId: secrets_delete summary: Delete a secret description: Remove a secret from the credential vault by name. Refused with CREDENTIAL_IN_USE while an LLM provider connection resolves its auth through the credential, unless `force` is set. tags: - secrets requestBody: required: true content: application/json: schema: type: object properties: type: type: string description: "Secret type: 'api_key' or 'credential'" name: type: string description: Name of the secret to delete force: description: Delete even when provider connections depend on the credential type: boolean required: - type - name responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean type: type: string name: type: string required: - success - type - name additionalProperties: false get: operationId: secrets_get summary: List secrets description: Return the names (not values) of all stored secrets. tags: - secrets responses: "200": description: Successful response content: application/json: schema: type: object properties: secrets: type: array items: type: object properties: type: type: string enum: - api_key - credential name: type: string required: - type - name additionalProperties: false description: List of secret metadata entries, each with type and name accounts: type: array items: type: object properties: type: type: string enum: - api_key - credential name: type: string required: - type - name additionalProperties: false description: Alias for secrets (same data) required: - secrets - accounts additionalProperties: false post: operationId: secrets_post summary: Add a secret description: Store a new secret (API key, OAuth token, etc.) in the credential vault. tags: - secrets requestBody: required: true content: application/json: schema: type: object properties: type: type: string description: "Secret type: 'api_key' or 'credential'" name: type: string description: Unique name for the secret value: type: string description: Secret value to store required: - type - name - value responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean type: type: string name: type: string error: description: Why the secret was not stored (e.g. provider-side API key validation failed). Present only when success is false. type: string required: - success additionalProperties: false /v1/secrets/read: post: operationId: secrets_read_post summary: Read a secret value description: Retrieve the decrypted value of a stored secret by name. tags: - secrets requestBody: required: true content: application/json: schema: type: object properties: type: type: string description: "Secret type: 'api_key' or 'credential'" name: type: string description: Name of the secret to read reveal: type: boolean description: If true, return the decrypted value; otherwise return a masked version required: - type - name responses: "200": description: Successful response content: application/json: schema: type: object properties: found: type: boolean value: type: string description: Decrypted value (only when reveal=true and found) masked: type: string description: Masked value (when reveal=false and found) unreachable: type: boolean required: - found - value - masked - unreachable additionalProperties: false /v1/sequences/cancel-enrollment: post: operationId: sequences_cancelenrollment_post summary: Cancel a specific enrollment description: Cancel a specific enrollment, stopping all future step deliveries for that contact. tags: - sequences requestBody: required: true content: application/json: schema: type: object properties: enrollmentId: type: string minLength: 1 required: - enrollmentId additionalProperties: false responses: "200": description: Successful response /v1/sequences/get: post: operationId: sequences_get_post summary: Get sequence details description: Get sequence details with enrollment stats, including step-by-step breakdown and enrollment status counts. tags: - sequences requestBody: required: true content: application/json: schema: type: object properties: id: type: string minLength: 1 required: - id additionalProperties: false responses: "200": description: Successful response /v1/sequences/guardrails: get: operationId: sequences_guardrails_get summary: Show guardrail configuration description: "Display the current guardrail configuration: daily send cap, hourly rate, step delay, max enrollments, duplicate check, and cooldown period." tags: - sequences responses: "200": description: Successful response post: operationId: sequences_guardrails_post summary: Update a guardrail setting description: "Update a single guardrail setting by key. Valid keys: dailySendCap, perSequenceHourlyRate, minimumStepDelaySec, maxActiveEnrollments, duplicateEnrollmentCheck, cooldownPeriodMs, cooldown_days." tags: - sequences requestBody: required: true content: application/json: schema: type: object properties: key: type: string minLength: 1 value: type: string minLength: 1 required: - key - value additionalProperties: false responses: "200": description: Successful response /v1/sequences/list: post: operationId: sequences_list_post summary: List sequences description: List all sequences, optionally filtered by status (active, paused, archived). tags: - sequences requestBody: required: true content: application/json: schema: type: object properties: status: type: string enum: - active - paused - archived additionalProperties: false responses: "200": description: Successful response /v1/sequences/pause: post: operationId: sequences_pause_post summary: Pause a sequence description: Pause a sequence, halting all scheduled step deliveries. No-op if already paused. tags: - sequences requestBody: required: true content: application/json: schema: type: object properties: id: type: string minLength: 1 required: - id additionalProperties: false responses: "200": description: Successful response /v1/sequences/resume: post: operationId: sequences_resume_post summary: Resume a paused sequence description: Resume a paused sequence, re-enabling scheduled step deliveries. No-op if already active. tags: - sequences requestBody: required: true content: application/json: schema: type: object properties: id: type: string minLength: 1 required: - id additionalProperties: false responses: "200": description: Successful response /v1/sequences/stats: get: operationId: sequences_stats_get summary: Overall sequence stats description: "Returns aggregate statistics: total/active sequence counts and total/active enrollment counts." tags: - sequences responses: "200": description: Successful response /v1/settings/avatar/generate: post: operationId: settings_avatar_generate_post summary: Generate avatar description: Generate an AI avatar image from a text description. tags: - settings requestBody: required: true content: application/json: schema: type: object properties: description: type: string required: - description responses: "200": description: Successful response /v1/settings/client: put: operationId: settings_client_put summary: Update client setting description: Set a single client-side setting key/value pair. tags: - settings requestBody: required: true content: application/json: schema: type: object properties: key: type: string value: type: string required: - key - value responses: "200": description: Successful response /v1/settings/voice: put: operationId: settings_voice_put summary: Update voice activation key description: Validate and normalize a voice activation key. tags: - settings requestBody: required: true content: application/json: schema: type: object properties: activationKey: type: string required: - activationKey responses: "200": description: Successful response /v1/skills: get: operationId: skills_get summary: List all skills description: "Return all installed skills. Pass ?include=catalog to also include available catalog skills. Supports optional filter params: origin, kind, q, category." tags: - skills parameters: - name: include in: query required: false schema: type: string enum: - catalog description: Optional inclusion flag. Use 'catalog' to merge available Vellum catalog skills into the response. - name: origin in: query required: false schema: type: string description: Filter by skill origin (e.g. 'vellum', 'clawhub', 'skillssh', 'custom', 'assistant-memory'). - name: kind in: query required: false schema: type: string description: "Filter by kind: 'installed' (includes bundled), 'available', or pass through as skill.kind." - name: q in: query required: false schema: type: string description: Text search across skill name, description, id, and origin label. - name: category in: query required: false schema: type: string description: Filter by inferred category (e.g. 'communication', 'productivity'). responses: "200": description: Successful response content: application/json: schema: type: object properties: skills: type: array items: oneOf: - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: vellum required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: clawhub slug: type: string author: type: string stars: type: number installs: type: number reports: type: number publishedAt: type: string version: type: string required: - id - name - description - kind - status - category - origin - slug - author - stars - installs - reports - version additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: skillssh slug: type: string sourceRepo: type: string installs: type: number audit: type: object propertyNames: type: string additionalProperties: type: object properties: risk: type: string enum: - safe - low - medium - high - critical - unknown alerts: type: number score: type: number analyzedAt: type: string required: - risk - analyzedAt additionalProperties: false required: - id - name - description - kind - status - category - origin - slug - sourceRepo - installs additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: custom required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: assistant-memory required: - id - name - description - kind - status - category - origin additionalProperties: false type: object description: Skill objects categoryCounts: description: Count of skills per category (before category filter is applied) type: object propertyNames: type: string additionalProperties: type: number totalCount: description: Total number of skills matching non-category filters type: number required: - skills additionalProperties: false post: operationId: skills_post summary: Create skill description: Create a new skill. tags: - skills requestBody: required: true content: application/json: schema: type: object properties: skillId: type: string name: type: string description: type: string bodyMarkdown: type: string required: - skillId - name - description - bodyMarkdown responses: "201": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/skills/{id}: delete: operationId: skills_by_id_delete summary: Uninstall skill description: Remove an installed skill. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "204": description: Successful response get: operationId: skills_by_id_get summary: Get skill description: Return a single skill by ID with enriched detail fields. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: skill: oneOf: - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: vellum required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string origin: type: string const: clawhub slug: type: string author: type: string stars: type: number installs: type: number reports: type: number publishedAt: type: string version: type: string owner: anyOf: - type: object properties: handle: type: string displayName: type: string image: type: string required: - handle - displayName additionalProperties: false - type: "null" stats: anyOf: - type: object properties: stars: type: number installs: type: number downloads: type: number versions: type: number required: - stars - installs - downloads - versions additionalProperties: false - type: "null" latestVersion: anyOf: - type: object properties: version: type: string changelog: type: string required: - version additionalProperties: false - type: "null" createdAt: anyOf: - type: number - type: "null" updatedAt: anyOf: - type: number - type: "null" required: - id - name - description - kind - status - category - origin - slug - author - stars - installs - reports - version additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string origin: type: string const: skillssh slug: type: string sourceRepo: type: string installs: type: number audit: type: object propertyNames: type: string additionalProperties: type: object properties: risk: type: string enum: - safe - low - medium - high - critical - unknown alerts: type: number score: type: number analyzedAt: type: string required: - risk - analyzedAt additionalProperties: false required: - id - name - description - kind - status - category - origin - slug - sourceRepo - installs additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: custom required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: assistant-memory sourceConversationId: description: Conversation whose trace the retrospective distilled this skill from. Present only when recorded in install-meta. type: string required: - id - name - description - kind - status - category - origin additionalProperties: false description: Skill detail object type: object required: - skill additionalProperties: false /v1/skills/{id}/config: patch: operationId: skills_by_id_config_patch summary: Configure skill description: Update skill configuration (env, apiKey, config). tags: - skills parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: env: type: object properties: {} additionalProperties: {} description: Environment variables apiKey: type: string config: type: object properties: {} additionalProperties: {} description: Arbitrary config required: - env - apiKey - config responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/skills/{id}/disable: post: operationId: skills_by_id_disable_post summary: Disable skill description: Disable an installed skill. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/skills/{id}/enable: post: operationId: skills_by_id_enable_post summary: Enable skill description: Enable an installed skill. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/skills/{id}/files: get: operationId: skills_by_id_files_get summary: Get skill files description: Return skill metadata and directory contents. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: skill: oneOf: - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: vellum required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: clawhub slug: type: string author: type: string stars: type: number installs: type: number reports: type: number publishedAt: type: string version: type: string required: - id - name - description - kind - status - category - origin - slug - author - stars - installs - reports - version additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: skillssh slug: type: string sourceRepo: type: string installs: type: number audit: type: object propertyNames: type: string additionalProperties: type: object properties: risk: type: string enum: - safe - low - medium - high - critical - unknown alerts: type: number score: type: number analyzedAt: type: string required: - risk - analyzedAt additionalProperties: false required: - id - name - description - kind - status - category - origin - slug - sourceRepo - installs additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: custom required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: assistant-memory required: - id - name - description - kind - status - category - origin additionalProperties: false description: Skill metadata type: object files: type: array items: type: object properties: path: type: string name: type: string size: type: integer minimum: -9007199254740991 maximum: 9007199254740991 mimeType: type: string isBinary: type: boolean content: anyOf: - type: string - type: "null" required: - path - name - size - mimeType - isBinary - content additionalProperties: false description: Directory contents required: - skill - files additionalProperties: false /v1/skills/{id}/files/content: get: operationId: skills_by_id_files_content_get summary: Get skill file content description: Return the content of a single file belonging to an installed or catalog skill. tags: - skills parameters: - name: id in: path required: true schema: type: string - name: path in: query required: true schema: type: string description: Relative path of the file within the skill directory responses: "200": description: Successful response content: application/json: schema: type: object properties: path: type: string name: type: string size: type: integer minimum: -9007199254740991 maximum: 9007199254740991 mimeType: type: string isBinary: type: boolean content: anyOf: - type: string - type: "null" required: - path - name - size - mimeType - isBinary - content additionalProperties: false /v1/skills/{id}/history: get: operationId: skills_by_id_history_get summary: Get skill revision history description: "Return a skill's recent updates, newest first, each with a combined diff across the skill directory. Read-only: revisions come from the workspace git repository, which already retains prior content. Commits whose only in-skill change is the `lastUsedAt` usage stamp are omitted, so entries are edits rather than loads." tags: - skills parameters: - name: id in: path required: true schema: type: string - name: limit in: query required: false schema: type: integer description: Maximum revisions to return, newest first. Defaults to 20 and is clamped to 100. responses: "200": description: Successful response content: application/json: schema: type: object properties: skillId: type: string description: The skill these revisions belong to revisions: type: array items: type: object properties: id: type: string description: Opaque revision identifier changedAt: type: string description: ISO-8601 time of the update files: type: array items: type: string description: Paths changed, relative to the skill directory diff: type: string description: Unified diff of this update, scoped to the skill required: - id - changedAt - files - diff additionalProperties: false description: Recent updates, newest first truncatedByCompaction: type: boolean description: Older history was squashed away, so the oldest entry is a floor rather than the skill's creation required: - skillId - revisions - truncatedByCompaction additionalProperties: false /v1/skills/{id}/inspect: get: operationId: skills_by_id_inspect_get summary: Inspect skill description: Return detailed skill information. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response /v1/skills/{id}/local-inspect: get: operationId: skills_by_id_localinspect_get summary: Local skill inspect description: Return full local detail for an installed or bundled skill, including featureFlag, toolManifest, installMeta, configEntry, and directoryPath. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response /v1/skills/{id}/update: post: operationId: skills_by_id_update_post summary: Update skill description: Update an installed skill to the latest version. tags: - skills parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/skills/categories: get: operationId: skills_categories_get summary: List skill categories description: Return all skill category definitions with labels, icons, and descriptions. tags: - skills responses: "200": description: Successful response content: application/json: schema: type: object properties: categories: type: array items: type: object properties: slug: type: string label: type: string description: type: string icon: type: string required: - slug - label - description - icon additionalProperties: false required: - categories additionalProperties: false /v1/skills/check-updates: post: operationId: skills_checkupdates_post summary: Check skill updates description: Check for available updates to installed skills. tags: - skills responses: "200": description: Successful response content: application/json: schema: type: object properties: data: type: object properties: {} additionalProperties: {} description: Update availability info required: - data additionalProperties: false /v1/skills/draft: post: operationId: skills_draft_post summary: Draft a skill description: Generate a skill draft from source text. tags: - skills requestBody: required: true content: application/json: schema: type: object properties: sourceText: type: string description: Source text for drafting required: - sourceText responses: "200": description: Successful response /v1/skills/install: post: operationId: skills_install_post summary: Install skill description: Install a skill by slug, URL, or spec. tags: - skills requestBody: required: true content: application/json: schema: type: object properties: slug: description: Skill slug. One of slug, url, or spec is required. type: string url: description: Skill URL. One of slug, url, or spec is required. type: string spec: description: Skill spec. One of slug, url, or spec is required. type: string version: description: Specific version to install type: string origin: description: Which registry to install from. When omitted, the install flow auto-detects based on slug format. type: string enum: - clawhub - skillssh overwrite: description: Replace an existing install. Defaults to true for back-compat with the legacy in-process API. type: boolean catalogOnly: description: When true, restrict to bundled and Vellum catalog skills only — do not fall through to community registries. type: boolean responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean skillId: type: string required: - ok additionalProperties: false /v1/skills/search: get: operationId: skills_search_get summary: Search skill catalog description: Search the skill catalog by query string. tags: - skills parameters: - name: q in: query required: false schema: type: string description: Search query (required) - name: limit in: query required: false schema: type: string description: Max community results to fetch (default 25) responses: "200": description: Successful response content: application/json: schema: type: object properties: skills: type: array items: oneOf: - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: vellum required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: clawhub slug: type: string author: type: string stars: type: number installs: type: number reports: type: number publishedAt: type: string version: type: string required: - id - name - description - kind - status - category - origin - slug - author - stars - installs - reports - version additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: skillssh slug: type: string sourceRepo: type: string installs: type: number audit: type: object propertyNames: type: string additionalProperties: type: object properties: risk: type: string enum: - safe - low - medium - high - critical - unknown alerts: type: number score: type: number analyzedAt: type: string required: - risk - analyzedAt additionalProperties: false required: - id - name - description - kind - status - category - origin - slug - sourceRepo - installs additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: custom required: - id - name - description - kind - status - category - origin additionalProperties: false - type: object properties: id: type: string name: type: string description: type: string icon: type: string emoji: type: string kind: type: string enum: - bundled - installed - catalog status: type: string enum: - enabled - disabled - available category: type: string owner: type: object properties: kind: type: string enum: - skill - mcp - plugin - workspace id: type: string required: - kind - id additionalProperties: false origin: type: string const: assistant-memory required: - id - name - description - kind - status - category - origin additionalProperties: false type: object description: Skill objects matching the search query required: - skills additionalProperties: false /v1/slack/channels: get: operationId: slack_channels_get summary: List Slack channels description: List Slack channels, groups, and DMs for the channel picker. tags: - integrations parameters: - name: memberOnly in: query required: false schema: type: string enum: - "true" - "false" description: "When 'true', only return rooms the connected identity is in: channels with is_member plus group DMs. 1:1 DMs are excluded — they are person-scoped, and Slack materializes IM rows without any conversation happening." responses: "200": description: Successful response content: application/json: schema: type: object properties: channels: type: array items: type: object properties: id: type: string name: type: string type: type: string enum: - channel - group - dm isPrivate: type: boolean isMember: type: boolean memberCount: anyOf: - type: number - type: "null" topic: anyOf: - type: string - type: "null" imageUrl: anyOf: - type: string - type: "null" required: - id - name - type - isPrivate - isMember - memberCount - topic - imageUrl additionalProperties: false required: - channels additionalProperties: false /v1/slack/share: post: operationId: slack_share_post summary: Share to Slack channel description: Post an app link directly to a Slack channel. tags: - integrations requestBody: required: true content: application/json: schema: type: object properties: appId: type: string description: App to share channelId: type: string description: Target Slack channel ID message: description: Optional accompanying message type: string required: - appId - channelId responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean ts: type: string channel: type: string required: - ok - ts - channel additionalProperties: false /v1/slack/users: get: operationId: slack_users_get summary: List Slack workspace users description: List human members of the connected Slack workspace for the contact account-linking picker. Deleted users and bots are excluded. tags: - integrations responses: "200": description: Successful response content: application/json: schema: type: object properties: users: type: array items: type: object properties: id: type: string username: type: string displayName: type: string imageUrl: anyOf: - type: string - type: "null" required: - id - username - displayName - imageUrl additionalProperties: false required: - users additionalProperties: false /v1/sounds/available: get: operationId: sounds_available_get summary: List available sound files description: Return audio files in data/sounds/ that can be assigned to sound events. tags: - sounds responses: "200": description: Successful response content: application/json: schema: type: object properties: sounds: type: array items: type: object properties: label: type: string filename: type: string required: - label - filename additionalProperties: false required: - sounds additionalProperties: false /v1/sounds/config: get: operationId: sounds_config_get summary: Get sounds configuration description: Return the sounds configuration from data/sounds/config.json, normalised with defaults. tags: - sounds responses: "200": description: Successful response content: application/json: schema: type: object properties: globalEnabled: type: boolean volume: type: number events: type: object propertyNames: type: string additionalProperties: type: object properties: enabled: type: boolean sounds: type: array items: type: string required: - enabled - sounds additionalProperties: false required: - globalEnabled - volume - events additionalProperties: false put: operationId: sounds_config_put summary: Update sounds configuration description: Replace the sounds configuration in data/sounds/config.json. tags: - sounds requestBody: required: true content: application/json: schema: type: object properties: globalEnabled: type: boolean volume: type: number events: type: object propertyNames: type: string additionalProperties: type: object properties: enabled: type: boolean sounds: type: array items: type: string required: - enabled - sounds required: - globalEnabled - volume - events responses: "200": description: Successful response content: application/json: schema: type: object properties: globalEnabled: type: boolean volume: type: number events: type: object propertyNames: type: string additionalProperties: type: object properties: enabled: type: boolean sounds: type: array items: type: string required: - enabled - sounds additionalProperties: false required: - globalEnabled - volume - events additionalProperties: false /v1/stt/providers: get: operationId: stt_providers_get summary: List STT providers description: Return the catalog of available STT providers with client-facing metadata. tags: - stt responses: "200": description: Successful response content: application/json: schema: type: object properties: providers: type: array items: type: object properties: id: type: string displayName: type: string subtitle: type: string setupMode: type: string setupHint: type: string apiKeyProviderName: type: string conversationStreamingMode: type: string languageSelection: type: string enum: - manual - auto credentialsGuide: type: string required: - id - displayName additionalProperties: false required: - providers additionalProperties: false /v1/stt/transcribe: post: operationId: stt_transcribe_post summary: Transcribe audio to text description: Transcribe base64-encoded audio to text using the configured STT provider. tags: - stt requestBody: required: true content: application/json: schema: type: object properties: audioBase64: type: string description: Base64-encoded audio data to transcribe mimeType: type: string description: MIME type of the audio data (must start with "audio/", e.g. "audio/wav", "audio/ogg") source: description: Optional source identifier for analytics (e.g. 'dictation', 'voice-mode') type: string required: - audioBase64 - mimeType responses: "200": description: Successful response content: application/json: schema: type: object properties: text: type: string providerId: type: string boundaryId: type: string required: - text - providerId additionalProperties: false /v1/stt/transcribe-file: post: operationId: stt_transcribefile_post summary: Transcribe audio/video file to text description: Transcribe an audio or video file to text using the configured STT provider. Handles ffmpeg conversion, large-file chunking, and sequential chunk transcription. tags: - stt requestBody: required: true content: application/json: schema: type: object properties: filePath: type: string description: Absolute path to the audio or video file required: - filePath responses: "200": description: Successful response content: application/json: schema: type: object properties: transcript: type: string provider: type: string durationSeconds: type: number required: - transcript - provider - durationSeconds additionalProperties: false /v1/subagents/{id}: get: operationId: subagents_by_id_get summary: Get subagent detail description: Return subagent objective and event history. tags: - subagents parameters: - name: id in: path required: true schema: type: string - name: conversationId in: query required: false schema: type: string description: "The subagent's own conversation ID. Fallback only: when the assistant knows the subagent (live, rehydrated, or in its durable records), it resolves the conversation itself and this parameter is ignored." responses: "200": description: Successful response content: application/json: schema: type: object properties: subagentId: type: string objective: type: string status: type: string enum: - pending - running - awaiting_input - completed - failed - aborted - interrupted usage: type: object properties: inputTokens: type: number outputTokens: type: number estimatedCost: type: number required: - inputTokens - outputTokens - estimatedCost additionalProperties: false events: type: array items: type: object properties: type: type: string content: type: string toolName: type: string isError: type: boolean messageId: type: string toolUseId: type: string input: type: object propertyNames: type: string additionalProperties: {} required: - type - content additionalProperties: false label: type: string parentToolUseId: type: string conversationId: type: string required: - subagentId - events additionalProperties: false /v1/subagents/{id}/abort: post: operationId: subagents_by_id_abort_post summary: Abort subagent description: Abort a running subagent. tags: - subagents parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: subagentId: type: string aborted: type: boolean required: - subagentId - aborted additionalProperties: false /v1/subagents/{id}/message: post: operationId: subagents_by_id_message_post summary: Send message to subagent description: Send a text message to a running subagent. tags: - subagents parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string content: type: string required: - conversationId - content responses: "200": description: Successful response content: application/json: schema: type: object properties: subagentId: type: string sent: type: boolean required: - subagentId - sent additionalProperties: false /v1/subagents/reconcile: get: operationId: subagents_reconcile_get summary: Reconcile subagent live status description: "Returns the subagents the assistant knows for a given parent conversation (live, rehydrated, and durably recorded), including recently finished runs whose in-memory metadata the retention sweep has already evicted. Durable records live as long as the conversation, so the snapshot is bounded: every subagent not in a terminal state is always returned, plus the 20 most recently finished ones. Each entry carries enough detail (child conversation id, label, objective, token usage, failure reason) for a client to rebuild its subagent list from scratch, not just refresh statuses. A subagent absent from the response is one the assistant no longer reports, so a client may settle its own stuck-active entries against this snapshot. Only `status` is guaranteed to be present; every other field is optional." tags: - subagents parameters: - name: parentConversationId in: query required: false schema: type: string description: Parent conversation ID responses: "200": description: Successful response content: application/json: schema: type: object properties: subagents: type: object propertyNames: type: string additionalProperties: type: object properties: status: type: string conversationId: type: string label: type: string objective: type: string isFork: type: boolean parentToolUseId: type: string usage: type: object properties: inputTokens: type: number outputTokens: type: number estimatedCost: type: number required: - inputTokens - outputTokens - estimatedCost additionalProperties: false error: type: string required: - status additionalProperties: false required: - subagents additionalProperties: false /v1/suggestion: get: operationId: suggestion_get summary: Get reply suggestion description: Return an LLM-generated follow-up suggestion for the most recent assistant message. tags: - messages parameters: - name: conversationId in: query required: false schema: type: string description: Conversation ID to fetch a suggestion for. Either this or conversationKey is required. - name: conversationKey in: query required: false schema: type: string description: Legacy conversation key. Either this or conversationId is required. - name: messageId in: query required: false schema: type: string description: Optional. Latest assistant message ID the client has seen — used to detect staleness. responses: "200": description: Successful response content: application/json: schema: type: object properties: suggestion: anyOf: - type: string - type: "null" messageId: anyOf: - type: string - type: "null" source: type: string stale: type: boolean required: - suggestion - messageId - source additionalProperties: false /v1/surface-actions: post: operationId: surfaceactions_post summary: Trigger a surface action description: Execute an interactive action on a surface (e.g. button click, form submit). tags: - surfaces requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string description: Conversation that owns the surface surfaceId: type: string description: Surface to act on actionId: type: string description: Action identifier data: type: object properties: {} additionalProperties: {} description: Action-specific payload required: - surfaceId - actionId responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean conversationId: type: string description: Id of a newly launched conversation when the action dispatched one. Omitted otherwise. applied: type: boolean description: Whether the action was applied. Present only for guardian decision actions (apr:*). False when the request was already resolved, expired, or the actor lacks permission. reason: type: string description: Explanation when applied is false (e.g. 'already_resolved', 'expired', 'principal_mismatch'). replyText: type: string description: Guardian-facing reply from the resolver (e.g. verification code for access-request approvals). Present only when applied is true and the resolver produced a reply. decidedAction: type: string description: The action to present on the resolved card — the resolved outcome, not necessarily the raw button (an access-request 'reject' resolves to the 'leave_unverified' park). Present only when applied is true; lets a client completing the card optimistically render the correct tone. required: - ok additionalProperties: false /v1/surfaces/{id}/undo: post: operationId: surfaces_by_id_undo_post summary: Undo last surface action description: Revert the most recent action on a surface. tags: - surfaces parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string description: Conversation that owns the surface required: - conversationId responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean required: - ok additionalProperties: false /v1/surfaces/{surfaceId}: get: operationId: surfaces_by_surfaceId_get summary: Get surface content description: Return the full surface payload from the conversation's in-memory surface state. tags: - surfaces parameters: - name: surfaceId in: path required: true schema: type: string - name: conversationId in: query required: true schema: type: string description: Conversation that owns the surface responses: "200": description: Successful response content: application/json: schema: type: object properties: surfaceId: type: string surfaceType: type: string title: anyOf: - type: string - type: "null" data: type: object properties: {} additionalProperties: {} description: Surface data payload required: - surfaceId - surfaceType - title - data additionalProperties: false /v1/telemetry/flush: post: operationId: telemetry_flush_post summary: Flush pending telemetry events description: Force-flush the telemetry events owned by the assistant process (turn events) to the platform. Other event types are flushed on their own cycle by the resource monitor process. tags: - telemetry responses: "200": description: Successful response content: application/json: schema: anyOf: - type: object properties: flushed: type: boolean const: true sent: type: number description: Events POSTed to the platform persisted: type: number description: Events the platform confirmed written dropped: type: number description: Events that did not land (sent - persisted) required: - flushed - sent - persisted - dropped additionalProperties: false - type: object properties: flushed: type: boolean const: false reason: type: string required: - flushed - reason additionalProperties: false /v1/telemetry/ingest: post: operationId: telemetry_ingest_post summary: Record an outbox-backed telemetry event description: Record any outbox-backed telemetry event by its wire `type` + `fields`. For events a client observes and the daemon can't detect on its own (e.g. onboarding_research). The type must be an outbox-backed event — the watermark types (turn, llm_usage, tool_executed) have no variant — and the payload must pass the platform wire schema. Gated on share_analytics consent like every other outbox-backed event; the platform re-checks the owner's consent server-side at ingest. tags: - telemetry requestBody: required: true content: application/json: schema: oneOf: - type: object properties: type: type: string const: lifecycle fields: type: object properties: event_name: type: string minLength: 1 maxLength: 64 required: - event_name description: Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at, assistant_version). daemon_event_id: description: "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh per-row id." type: string minLength: 1 maxLength: 128 required: - type - fields - type: object properties: type: type: string const: onboarding fields: type: object properties: screen: type: string minLength: 1 maxLength: 64 tools: type: array items: type: string minLength: 1 maxLength: 128 tasks: type: array items: type: string minLength: 1 maxLength: 128 tone: type: string minLength: 1 maxLength: 64 google_connected: type: boolean google_scopes: type: array items: type: string minLength: 1 maxLength: 256 ab_variant: type: string minLength: 1 maxLength: 64 session_id: type: string minLength: 1 maxLength: 128 step_name: type: string minLength: 1 maxLength: 128 step_index: type: integer minimum: 0 maximum: 9007199254740991 completed_at: type: string minLength: 1 maxLength: 64 funnel_version: type: string minLength: 1 maxLength: 128 user_id: anyOf: - type: string minLength: 1 maxLength: 64 - type: "null" outcome: type: string minLength: 1 maxLength: 32 description: Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at, assistant_version). daemon_event_id: description: "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh per-row id." type: string minLength: 1 maxLength: 128 required: - type - fields - type: object properties: type: type: string const: auth_fallback fields: type: object properties: guard: type: string minLength: 1 maxLength: 64 failure_kind: type: string minLength: 1 maxLength: 64 path: type: string minLength: 1 maxLength: 2048 count: type: integer minimum: 0 maximum: 9007199254740991 window_start: type: integer minimum: 0 maximum: 9007199254740991 window_end: type: integer minimum: 0 maximum: 9007199254740991 required: - guard - failure_kind - path - count - window_start - window_end description: Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at, assistant_version). daemon_event_id: description: "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh per-row id." type: string minLength: 1 maxLength: 128 required: - type - fields - type: object properties: type: type: string const: skill_loaded fields: type: object properties: provider: anyOf: - type: string minLength: 1 maxLength: 64 - type: "null" model: anyOf: - type: string minLength: 1 maxLength: 128 - type: "null" inference_profile: anyOf: - type: string minLength: 1 maxLength: 255 - type: "null" inference_profile_source: anyOf: - type: string minLength: 1 maxLength: 255 - type: "null" skill_name: type: string minLength: 1 maxLength: 255 skill_updated_at: anyOf: - type: string minLength: 1 maxLength: 64 - type: "null" conversation_id: anyOf: - type: string minLength: 1 maxLength: 128 - type: "null" required: - skill_name description: Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at, assistant_version). daemon_event_id: description: "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh per-row id." type: string minLength: 1 maxLength: 128 required: - type - fields - type: object properties: type: type: string const: watchdog fields: type: object properties: check_name: type: string minLength: 1 maxLength: 128 value: anyOf: - type: number - type: "null" detail: anyOf: - $ref: "#/components/schemas/TelemetryJsonValue" - type: "null" required: - check_name description: Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at, assistant_version). daemon_event_id: description: "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh per-row id." type: string minLength: 1 maxLength: 128 required: - type - fields - type: object properties: type: type: string const: config_setting fields: type: object properties: config_key: type: string minLength: 1 maxLength: 128 config_value: type: string minLength: 1 maxLength: 256 required: - config_key - config_value description: Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at, assistant_version). daemon_event_id: description: "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh per-row id." type: string minLength: 1 maxLength: 128 required: - type - fields - type: object properties: type: type: string const: onboarding_research fields: type: object properties: conversation_id: anyOf: - type: string minLength: 1 maxLength: 64 - type: "null" status: type: string minLength: 1 maxLength: 32 self_reported_occupation: anyOf: - type: string maxLength: 256 - type: "null" self_reported_hobbies: maxItems: 32 type: array items: type: string minLength: 1 maxLength: 128 self_reported_timezone: anyOf: - type: string maxLength: 64 - type: "null" claims: maxItems: 20 type: array items: $ref: "#/components/schemas/TelemetryJsonValue" claim_count: type: integer minimum: 0 maximum: 9007199254740991 claims_confident: type: integer minimum: 0 maximum: 9007199254740991 claims_maybe: type: integer minimum: 0 maximum: 9007199254740991 claims_guessing: type: integer minimum: 0 maximum: 9007199254740991 suggestions: maxItems: 20 type: array items: $ref: "#/components/schemas/TelemetryJsonValue" suggestion_count: type: integer minimum: 0 maximum: 9007199254740991 plugins: maxItems: 20 type: array items: type: string minLength: 1 maxLength: 128 installed_plugins: maxItems: 20 type: array items: type: string minLength: 1 maxLength: 128 required: - status - claims - claim_count - claims_confident - claims_maybe - claims_guessing - suggestions - suggestion_count - plugins - installed_plugins description: Wire event fields, excluding the daemon-stamped base fields (type, daemon_event_id, recorded_at, assistant_version). daemon_event_id: description: "Optional collapse key: rows sharing an id collapse downstream (e.g. a retried report). Defaults to a fresh per-row id." type: string minLength: 1 maxLength: 128 required: - type - fields type: object responses: "200": description: Successful response content: application/json: schema: anyOf: - type: object properties: id: type: string description: Event ID required: - id additionalProperties: false - type: object properties: skipped: type: boolean const: true description: "Event skipped: usage data collection is disabled or the telemetry database is unavailable" required: - skipped additionalProperties: false /v1/telemetry/lifecycle: post: operationId: telemetry_lifecycle_post summary: Record lifecycle event description: Record a telemetry lifecycle event (app_open, hatch). tags: - telemetry requestBody: required: true content: application/json: schema: type: object properties: event_name: type: string description: "Event name: app_open or hatch" required: - event_name responses: "200": description: Successful response content: application/json: schema: anyOf: - type: object properties: id: type: string description: Event ID event_name: type: string required: - id - event_name additionalProperties: false - type: object properties: skipped: type: boolean const: true description: Event skipped due to usage data collection being disabled required: - skipped additionalProperties: false /v1/tools: get: operationId: tools_get summary: List registered tools with metadata and schemas description: "Return registered tools. Without `conversationId`, returns every tool in the global registry; `tools` carries per-tool metadata (description, author-asserted risk level, category, and contributing source: default (built-in), skill, plugin, or MCP server) and `names`/`schemas` additionally cover skill tools whose manifests are present but not yet loaded, for the permission-simulator catalog. With `conversationId`, scopes the result to the tools available to that conversation as of its most recent turn (including skill/MCP tools registered over its lifecycle); 404 if no such conversation is active. With `agent`, simulates the subagent tool projection for a given role or resolves a live subagent's conversation." tags: - tools parameters: - name: conversationId in: query required: false schema: type: string description: When set, scope the tool inventory to this conversation's most recent turn instead of the global registry. - name: agent in: query required: false schema: type: string description: A subagent role name or a live subagent id. Simulates the subagent tool projection for that role or resolves the live subagent's conversation. responses: "200": description: Successful response content: application/json: schema: type: object properties: names: type: array items: type: string schemas: type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: {} tools: type: array items: type: object properties: name: type: string description: type: string riskLevel: type: string category: type: string source: type: string description: Tool origin as ":" (e.g. "default:default" for built-ins, "plugin:echo", "skill:my-skill", "mcp:server"). required: - name - description - riskLevel - category - source additionalProperties: false required: - names - schemas - tools additionalProperties: false /v1/tools/simulate-permission: post: operationId: tools_simulatepermission_post summary: Simulate tool permission check description: Dry-run a permission check for a tool invocation without executing it. tags: - tools requestBody: required: true content: application/json: schema: type: object properties: toolName: type: string input: type: object properties: {} additionalProperties: {} workingDir: type: string isInteractive: type: boolean required: - toolName - input - workingDir - isInteractive responses: "200": description: Successful response /v1/transfers/{transferId}/content: get: operationId: transfers_by_transferId_content_get summary: Get transfer content description: "Serve raw file bytes for a to_host transfer. Single-use: returns 404 after first consumption." tags: - host-transfer parameters: - name: transferId in: path required: true schema: type: string responses: "200": description: Successful response "400": description: x-vellum-client-id header is missing for a targeted transfer. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. put: operationId: transfers_by_transferId_content_put summary: Put transfer content description: Receive raw file bytes for a to_sandbox transfer. Verifies SHA-256 integrity via the X-Transfer-SHA256 header. tags: - host-transfer parameters: - name: transferId in: path required: true schema: type: string responses: "200": description: Successful response "400": description: x-vellum-client-id header is missing for a targeted transfer. "403": description: Submitting client does not match the targeted client, or the submitting actor's principal does not match the target client's actor. /v1/trust-rules: get: operationId: trustrules_get summary: List trust rules description: List trust rules, optionally filtered by tool, origin, or include_all. tags: - trust-rules parameters: - name: tool in: query required: false schema: type: string description: Filter by tool name - name: origin in: query required: false schema: type: string description: Filter by origin - name: include_all in: query required: false schema: type: string description: Include unmodified defaults responses: "200": description: Successful response content: application/json: schema: type: object properties: rules: type: array items: type: object properties: id: type: string tool: type: string pattern: type: string risk: type: string enum: - low - medium - high description: type: string origin: type: string enum: - default - user_defined userModified: type: boolean deleted: type: boolean createdAt: type: string updatedAt: type: string required: - id - tool - pattern - risk - description - origin - userModified - deleted - createdAt - updatedAt additionalProperties: false required: - rules additionalProperties: false /v1/trust-rules/suggest: post: operationId: trustrules_suggest_post summary: Suggest a trust rule description: Use an LLM to suggest a trust rule pattern, risk level, and scope for a given action. tags: - trust requestBody: required: true content: application/json: schema: type: object properties: tool: type: string minLength: 1 command: type: string minLength: 1 riskAssessment: type: object properties: risk: type: string reasoning: type: string reasonDescription: type: string required: - risk - reasoning - reasonDescription scopeOptions: type: array items: type: object properties: pattern: type: string label: type: string required: - pattern - label directoryScopeOptions: type: array items: type: object properties: scope: type: string label: type: string required: - scope - label currentThreshold: type: string intent: type: string enum: - auto_approve - escalate existingRule: type: object properties: id: type: string pattern: type: string risk: type: string required: - id - pattern - risk required: - tool - command - riskAssessment - scopeOptions - currentThreshold - intent responses: "200": description: Successful response content: application/json: schema: type: object properties: pattern: type: string risk: type: string scope: type: string description: type: string scopeOptions: type: array items: type: object properties: pattern: type: string label: type: string required: - pattern - label additionalProperties: false directoryScopeOptions: type: array items: type: object properties: scope: type: string label: type: string required: - scope - label additionalProperties: false required: - pattern - risk - description - scopeOptions additionalProperties: false /v1/tts/managed-voices: get: operationId: tts_managedvoices_get summary: List managed TTS voices description: Return the voices offered by Vellum managed TTS, fetched live from the platform. Only currently-usable voices are returned; defaultModel is always one of them (null when none are offered). tags: - tts responses: "200": description: Successful response content: application/json: schema: type: object properties: voices: type: array items: type: object properties: model: type: string label: type: string description: type: string sampleUrl: type: string source: type: string required: - model - label - description - sampleUrl - source additionalProperties: false defaultModel: anyOf: - type: string - type: "null" required: - voices - defaultModel additionalProperties: false /v1/tts/providers: get: operationId: tts_providers_get summary: List TTS providers description: Return the catalog of available TTS providers with client-facing metadata. tags: - tts responses: "200": description: Successful response content: application/json: schema: type: object properties: providers: type: array items: type: object properties: id: type: string displayName: type: string subtitle: type: string supportsVoiceSelection: type: boolean apiKeyPlaceholder: type: string credentialsGuide: type: object properties: description: type: string url: type: string linkLabel: type: string required: - description - url - linkLabel additionalProperties: false required: - id - displayName - subtitle - supportsVoiceSelection - apiKeyPlaceholder - credentialsGuide additionalProperties: false required: - providers additionalProperties: false /v1/tts/synthesize: post: operationId: tts_synthesize_post summary: Synthesize text to speech description: Synthesize arbitrary text to audio using the configured TTS provider. tags: - tts requestBody: required: true content: application/json: schema: type: object properties: text: type: string description: Text to synthesize into speech context: description: Optional context hint for output policy or capability selection. type: string conversationId: description: Optional conversation ID for scoping or analytics. type: string required: - text responses: "200": description: Successful response /v1/tts/synthesize-cli: post: operationId: tts_synthesizecli_post summary: Synthesize text to speech (CLI) description: Synthesize arbitrary text to audio. Returns base64-encoded audio + content type for CLI consumption. tags: - tts requestBody: required: true content: application/json: schema: type: object properties: text: type: string description: Text to synthesize into speech useCase: default: message-playback type: string enum: - message-playback - phone-call voiceId: description: Provider-specific voice identifier override type: string required: - text responses: "200": description: Successful response content: application/json: schema: type: object properties: audioBase64: type: string description: Base64-encoded audio bytes contentType: type: string description: MIME type of the audio (e.g. audio/mpeg) required: - audioBase64 - contentType additionalProperties: false /v1/ui/request: post: operationId: ui_request_post summary: Present an interactive UI surface description: Present an interactive UI surface to the user and await their response. tags: - ui requestBody: required: true content: application/json: schema: type: object properties: conversationId: type: string minLength: 1 surfaceType: type: string enum: - confirmation - form title: type: string data: type: object propertyNames: type: string additionalProperties: {} actions: type: array items: type: object properties: id: type: string minLength: 1 label: type: string minLength: 1 variant: type: string enum: - primary - danger - secondary required: - id - label timeoutMs: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 required: - conversationId - surfaceType - data responses: "200": description: Successful response /v1/ui/snapshot: post: operationId: ui_snapshot_post summary: Capture a staged UI snapshot description: Ask the connected desktop client to render a staged view of the app (sampler or chat) with the current workspace-theme tokens applied and return a PNG capture. The staged views contain only fixed generic content. Blocks until the client responds or the timeout elapses. tags: - host requestBody: required: true content: application/json: schema: type: object properties: view: default: sampler description: Which staged composition to capture type: string enum: - sampler - chat timeoutMs: description: How long to wait for the client capture type: integer exclusiveMinimum: 0 maximum: 120000 responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean pngBase64: type: string description: Base64 PNG capture of the staged view widthPx: type: number heightPx: type: number themeSource: type: string enum: - workspace - invalid - none themeIssues: type: array items: type: string timedOut: type: boolean error: type: string required: - ok - themeSource - themeIssues additionalProperties: false /v1/usage/breakdown: get: operationId: usage_breakdown_get summary: Get usage breakdown description: Return grouped usage breakdown. Prefer call_site for user-facing task breakdowns; actor is a legacy/internal dimension. tags: - usage parameters: - name: from in: query required: false schema: type: integer description: Start epoch millis (required) - name: to in: query required: false schema: type: integer description: End epoch millis (required) - name: groupBy in: query required: false schema: type: string description: "Group by: actor, provider, model, conversation, call_site, inference_profile, schedule (required)" - name: scheduleId in: query required: false schema: type: string description: Optional schedule id. When set, usage is attributed by cron run windows for that schedule. responses: "200": description: Successful response content: application/json: schema: type: object properties: breakdown: type: array items: type: object properties: group: type: string groupId: anyOf: - type: string - type: "null" groupKey: anyOf: - type: string - type: "null" totalInputTokens: type: number totalOutputTokens: type: number totalCacheCreationTokens: type: number totalCacheReadTokens: type: number totalEstimatedCostUsd: type: number eventCount: type: number turnCount: anyOf: - type: number - type: "null" required: - group - groupId - totalInputTokens - totalOutputTokens - totalCacheCreationTokens - totalCacheReadTokens - totalEstimatedCostUsd - eventCount - turnCount additionalProperties: false description: Grouped usage entries required: - breakdown additionalProperties: false /v1/usage/daily: get: operationId: usage_daily_get summary: Get daily usage description: Return per-day usage buckets for a time range. tags: - usage parameters: - name: from in: query required: false schema: type: integer description: Start epoch millis (required) - name: to in: query required: false schema: type: integer description: End epoch millis (required) - name: granularity in: query required: false schema: type: string enum: - daily - hourly description: 'Bucket granularity: "daily" (default) or "hourly"' - name: tz in: query required: false schema: type: string description: IANA timezone identifier (e.g. "America/Los_Angeles"). Bucket boundaries and display labels are computed in this timezone. Defaults to "UTC" for backwards compatibility. - name: scheduleId in: query required: false schema: type: string description: Optional schedule id. When set, usage is attributed by cron run windows for that schedule. responses: "200": description: Successful response content: application/json: schema: type: object properties: buckets: type: array items: type: object properties: bucketId: type: string date: type: string displayLabel: type: string totalInputTokens: type: number totalOutputTokens: type: number totalEstimatedCostUsd: type: number eventCount: type: number required: - bucketId - date - totalInputTokens - totalOutputTokens - totalEstimatedCostUsd - eventCount additionalProperties: false description: Usage bucket objects required: - buckets additionalProperties: false /v1/usage/series: get: operationId: usage_series_get summary: Get grouped usage series description: Return usage buckets with per-group values for stacked charts. Prefer call_site for user-facing task stacks. tags: - usage parameters: - name: from in: query required: false schema: type: integer description: Start epoch millis (required) - name: to in: query required: false schema: type: integer description: End epoch millis (required) - name: granularity in: query required: false schema: type: string enum: - daily - hourly description: 'Bucket granularity: "daily" (default) or "hourly"' - name: groupBy in: query required: false schema: type: string description: "Group by: actor, provider, model, call_site, inference_profile, schedule (required)" - name: tz in: query required: false schema: type: string description: IANA timezone identifier (e.g. "America/Los_Angeles"). Bucket boundaries and display labels are computed in this timezone. Defaults to "UTC". - name: scheduleId in: query required: false schema: type: string description: Optional schedule id. When set, usage is attributed by cron run windows for that schedule. responses: "200": description: Successful response content: application/json: schema: type: object properties: buckets: type: array items: type: object properties: bucketId: type: string date: type: string displayLabel: type: string totalInputTokens: type: number totalOutputTokens: type: number totalEstimatedCostUsd: type: number eventCount: type: number groups: type: object propertyNames: type: string additionalProperties: type: object properties: group: type: string groupKey: anyOf: - type: string - type: "null" totalInputTokens: type: number totalOutputTokens: type: number totalEstimatedCostUsd: type: number eventCount: type: number required: - group - groupKey - totalInputTokens - totalOutputTokens - totalEstimatedCostUsd - eventCount additionalProperties: false required: - bucketId - date - totalInputTokens - totalOutputTokens - totalEstimatedCostUsd - eventCount - groups additionalProperties: false description: Grouped usage bucket objects required: - buckets additionalProperties: false /v1/usage/totals: get: operationId: usage_totals_get summary: Get usage totals description: Return aggregate usage totals for a time range. tags: - usage parameters: - name: from in: query required: false schema: type: integer description: Start epoch millis (required) - name: to in: query required: false schema: type: integer description: End epoch millis (required) - name: scheduleId in: query required: false schema: type: string description: Optional schedule id. When set, usage is attributed by cron run windows for that schedule. responses: "200": description: Successful response content: application/json: schema: type: object properties: totalInputTokens: type: number totalOutputTokens: type: number totalCacheCreationTokens: type: number totalCacheReadTokens: type: number totalEstimatedCostUsd: type: number eventCount: type: number pricedEventCount: type: number unpricedEventCount: type: number required: - totalInputTokens - totalOutputTokens - totalCacheCreationTokens - totalCacheReadTokens - totalEstimatedCostUsd - eventCount - pricedEventCount - unpricedEventCount additionalProperties: false /v1/user-routes/inspect: post: operationId: userroutes_inspect_post summary: Inspect a user-defined route handler description: Load a specific handler file and return its exported methods, description, file path, public URL, and metadata. tags: - user-routes requestBody: required: true content: application/json: schema: type: object properties: path: type: string minLength: 1 required: - path additionalProperties: false responses: "200": description: Successful response /v1/user-routes/list: get: operationId: userroutes_list_get summary: List user-defined route handlers description: Scan workspace routes directory for handler files and return discovered routes with methods and public URLs. tags: - user-routes responses: "200": description: Successful response /v1/watchers/create: post: operationId: watchers_create_post summary: Create a watcher description: Create a new watcher with a provider and action prompt. tags: - watchers requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 provider: type: string minLength: 1 action_prompt: type: string minLength: 1 poll_interval_ms: type: integer minimum: 15000 maximum: 9007199254740991 config: type: object propertyNames: type: string additionalProperties: {} credential_service: type: string required: - name - provider - action_prompt responses: "200": description: Successful response content: application/json: schema: type: object properties: {} additionalProperties: {} /v1/watchers/delete: post: operationId: watchers_delete_post summary: Delete a watcher description: Delete a watcher by ID. tags: - watchers requestBody: required: true content: application/json: schema: type: object properties: watcher_id: type: string minLength: 1 required: - watcher_id responses: "200": description: Successful response content: application/json: schema: type: object properties: {} additionalProperties: {} /v1/watchers/digest: post: operationId: watchers_digest_post summary: Get watcher event digest description: Get recent watcher events, optionally filtered by watcher ID. tags: - watchers requestBody: required: true content: application/json: schema: type: object properties: watcher_id: type: string hours: default: 24 type: number exclusiveMinimum: 0 limit: default: 50 type: integer exclusiveMinimum: 0 maximum: 9007199254740991 responses: "200": description: Successful response content: application/json: schema: type: object properties: {} additionalProperties: {} /v1/watchers/list: post: operationId: watchers_list_post summary: List watchers description: List all watchers, or get details for a specific watcher by ID. tags: - watchers requestBody: required: true content: application/json: schema: type: object properties: watcher_id: type: string enabled_only: default: false type: boolean responses: "200": description: Successful response content: application/json: schema: type: object properties: {} additionalProperties: {} /v1/watchers/update: post: operationId: watchers_update_post summary: Update a watcher description: Update an existing watcher's configuration. tags: - watchers requestBody: required: true content: application/json: schema: type: object properties: watcher_id: type: string minLength: 1 name: type: string action_prompt: type: string poll_interval_ms: type: integer minimum: 15000 maximum: 9007199254740991 enabled: type: boolean config: type: object propertyNames: type: string additionalProperties: {} required: - watcher_id responses: "200": description: Successful response content: application/json: schema: type: object properties: {} additionalProperties: {} /v1/webhooks: get: operationId: webhooks_get summary: List registered webhook callback routes description: Lists all webhook callback routes registered with the platform for this assistant. tags: - webhooks responses: "200": description: Successful response content: application/json: schema: type: object properties: routes: type: array items: type: object properties: id: type: string assistant_id: type: string type: type: string callback_path: type: string callback_url: type: string source_identifier: anyOf: - type: string - type: "null" required: - id - assistant_id - type - callback_path - callback_url - source_identifier additionalProperties: false required: - routes additionalProperties: false /v1/webhooks/register: post: operationId: webhooks_register_post summary: Register a webhook callback URL description: Resolves a stable callback URL for a webhook type. On platform-managed assistants, registers the route with the platform gateway. Otherwise uses the configured ingress.publicBaseUrl, falling back to the platform gateway when no ingress is configured and the assistant is connected to the platform. tags: - webhooks requestBody: required: true content: application/json: schema: type: object properties: type: type: string path: type: string source: type: string required: - type responses: "200": description: Successful response content: application/json: schema: type: object properties: callbackUrl: type: string type: type: string path: type: string mode: type: string enum: - platform - self-hosted required: - callbackUrl - type - path - mode additionalProperties: false /v1/workflows: get: operationId: workflows_get summary: List saved workflows description: Return the saved (named) workflows the assistant can run. tags: - workflows responses: "200": description: Successful response content: application/json: schema: type: object properties: workflows: type: array items: type: object properties: name: type: string description: type: string path: type: string required: - name - description - path additionalProperties: false description: Saved workflow entries required: - workflows additionalProperties: false /v1/workflows/runs: get: operationId: workflows_runs_get summary: List workflow runs description: Return recent workflow runs, newest first. tags: - workflows parameters: - name: limit in: query required: false schema: type: integer description: Max runs to return (default 50, max 200) - name: status in: query required: false schema: type: string description: Filter by run status (running, completed, failed, aborted, cap_exceeded, interrupted). responses: "200": description: Successful response content: application/json: schema: type: object properties: runs: type: array items: type: object properties: id: type: string name: anyOf: - type: string - type: "null" scriptHash: type: string status: type: string enum: - running - completed - failed - aborted - cap_exceeded - interrupted conversationId: anyOf: - type: string - type: "null" agentsSpawned: type: number inputTokens: type: number outputTokens: type: number error: anyOf: - type: string - type: "null" createdAt: anyOf: - type: number - type: "null" updatedAt: anyOf: - type: number - type: "null" finishedAt: anyOf: - type: number - type: "null" required: - id - name - scriptHash - status - conversationId - agentsSpawned - inputTokens - outputTokens - error - createdAt - updatedAt - finishedAt additionalProperties: false description: Workflow run objects required: - runs additionalProperties: false /v1/workflows/runs/{id}: get: operationId: workflows_runs_by_id_get summary: Get workflow run description: Return a single workflow run by ID. tags: - workflows parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: id: type: string name: anyOf: - type: string - type: "null" scriptHash: type: string status: type: string enum: - running - completed - failed - aborted - cap_exceeded - interrupted conversationId: anyOf: - type: string - type: "null" agentsSpawned: type: number inputTokens: type: number outputTokens: type: number error: anyOf: - type: string - type: "null" createdAt: anyOf: - type: number - type: "null" updatedAt: anyOf: - type: number - type: "null" finishedAt: anyOf: - type: number - type: "null" required: - id - name - scriptHash - status - conversationId - agentsSpawned - inputTokens - outputTokens - error - createdAt - updatedAt - finishedAt additionalProperties: false "404": description: Run not found /v1/workflows/runs/{id}/abort: post: operationId: workflows_runs_by_id_abort_post summary: Abort workflow run description: Signal an in-flight workflow run to abort. tags: - workflows parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean runId: type: string required: - ok - runId additionalProperties: false "404": description: Run not found /v1/workflows/runs/{id}/journal: get: operationId: workflows_runs_by_id_journal_get summary: Get workflow run journal description: Return a workflow run's leaf journal as bounded per-leaf summaries (one entry per finished leaf). tags: - workflows parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: runId: type: string status: type: string enum: - running - completed - failed - aborted - cap_exceeded - interrupted agentsSpawned: type: number inputTokens: type: number outputTokens: type: number phase: type: string leaves: type: array items: type: object properties: seq: type: number kind: type: string enum: - agent - workflow label: type: string phase: type: string promptSummary: type: string status: type: string resultSummary: type: string inputTokens: type: number outputTokens: type: number createdAt: anyOf: - type: number - type: "null" required: - seq - kind - status - createdAt additionalProperties: false required: - runId - leaves additionalProperties: false "404": description: Run not found /v1/workflows/runs/{id}/resume: post: operationId: workflows_runs_by_id_resume_post summary: Resume workflow run description: Resume an interrupted workflow run (one orphaned by an assistant restart), replaying its journaled prefix and continuing from the first unfinished step. tags: - workflows parameters: - name: id in: path required: true schema: type: string responses: "200": description: Successful response content: application/json: schema: type: object properties: ok: type: boolean runId: type: string required: - ok - runId additionalProperties: false "404": description: Run not found "409": description: Run is not resumable (not interrupted) "429": description: Concurrent-run cap reached /v1/workspace-files: get: operationId: workspacefiles_get summary: List workspace files description: Return an array of files in the workspace directory. tags: - workspace responses: "200": description: Successful response /v1/workspace-files/read: get: operationId: workspacefiles_read_get summary: Read a workspace file description: Return the contents of a single file by path. tags: - workspace parameters: - name: path in: query required: true schema: type: string description: File path to read responses: "200": description: Successful response /v1/workspace/delete: post: operationId: workspace_delete_post summary: Delete workspace entry description: Delete a file or directory from the workspace. tags: - workspace requestBody: required: true content: application/json: schema: type: object properties: path: type: string description: Relative path to delete required: - path responses: "200": description: Successful response content: application/json: schema: type: object properties: success: type: boolean required: - success additionalProperties: false /v1/workspace/file: get: operationId: workspace_file_get summary: Get workspace file metadata description: Return file metadata and inline text content (if small enough). tags: - workspace parameters: - name: path in: query required: false schema: type: string description: Relative file path (required) - name: showHidden in: query required: false schema: type: string description: Allow hidden files (true/false) responses: "200": description: Successful response content: application/json: schema: type: object properties: path: type: string name: type: string size: type: number mimeType: type: string modifiedAt: type: string content: type: string description: Inline text content or null isBinary: type: boolean required: - path - name - size - mimeType - modifiedAt - content - isBinary additionalProperties: false /v1/workspace/file/content: get: operationId: workspace_file_content_get summary: Get workspace file content description: Return raw file bytes with HTTP range support. tags: - workspace parameters: - name: path in: query required: true schema: type: string description: Relative file path - name: showHidden in: query required: false schema: type: string description: Allow hidden files (true/false) responses: "200": description: Successful response content: application/octet-stream: schema: type: string format: binary "416": description: Range Not Satisfiable /v1/workspace/mkdir: post: operationId: workspace_mkdir_post summary: Create workspace directory description: Create directories recursively in the workspace. tags: - workspace requestBody: required: true content: application/json: schema: type: object properties: path: type: string description: Relative directory path required: - path responses: "200": description: Successful response content: application/json: schema: type: object properties: path: type: string required: - path additionalProperties: false /v1/workspace/rename: post: operationId: workspace_rename_post summary: Rename workspace entry description: Rename or move a file or directory in the workspace. tags: - workspace requestBody: required: true content: application/json: schema: type: object properties: oldPath: type: string description: Current relative path newPath: type: string description: New relative path required: - oldPath - newPath responses: "200": description: Successful response content: application/json: schema: type: object properties: oldPath: type: string newPath: type: string required: - oldPath - newPath additionalProperties: false /v1/workspace/theme: get: operationId: workspace_theme_get summary: Get workspace theme description: "Return validated design-token overrides from the workspace ui/theme.json. Absent or rejected files yield theme: null with the rejection reasons in issues; clients fall back to built-in theme defaults." tags: - workspace responses: "200": description: Successful response content: application/json: schema: type: object properties: theme: anyOf: - type: object properties: version: type: number const: 1 base: type: string enum: - light - dark - velvet - system tokens: type: object properties: accent: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ background: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ surface: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ surfaceRaised: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ border: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ text: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ textMuted: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ assistantBubbleBackground: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ assistantBubbleText: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ userBubbleBackground: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ userBubbleText: type: string pattern: ^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$ additionalProperties: false required: - version additionalProperties: false - type: "null" source: type: string enum: - workspace - invalid - none issues: type: array items: type: string required: - theme - source - issues additionalProperties: false /v1/workspace/tree: get: operationId: workspace_tree_get summary: List workspace directory description: Return directory entries for a workspace path. tags: - workspace parameters: - name: path in: query required: false schema: type: string description: Relative path (default root) - name: showHidden in: query required: false schema: type: string description: Include dotfiles (true/false) - name: includeDirSizes in: query required: false schema: type: string description: "Compute recursive byte size for each directory entry (true/false). Budget-bounded — large subtrees may return size: null." responses: "200": description: Successful response content: application/json: schema: type: object properties: path: type: string entries: type: array items: type: object properties: name: type: string path: type: string type: type: string enum: - file - directory size: anyOf: - type: number - type: "null" mimeType: anyOf: - type: string - type: "null" modifiedAt: type: string required: - name - path - type - size - mimeType - modifiedAt additionalProperties: false description: Directory entry objects required: - path - entries additionalProperties: false /v1/workspace/write: post: operationId: workspace_write_post summary: Write workspace file description: Create or overwrite a file in the workspace. tags: - workspace requestBody: required: true content: application/json: schema: type: object properties: path: type: string description: Relative file path content: type: string description: File content encoding: type: string description: Content encoding (base64 or utf-8) required: - path responses: "200": description: Successful response content: application/json: schema: type: object properties: path: type: string size: type: number required: - path - size additionalProperties: false /v1/x/{path}: delete: operationId: x_by_path_delete summary: User-defined DELETE route description: Dispatches DELETE requests to user-defined handler files in the workspace routes directory. tags: - user-routes parameters: - name: path in: path required: true schema: type: string responses: "200": description: Successful response get: operationId: x_by_path_get summary: User-defined GET route description: Dispatches GET requests to user-defined handler files in the workspace routes directory. tags: - user-routes parameters: - name: path in: path required: true schema: type: string responses: "200": description: Successful response head: operationId: x_by_path_head summary: User-defined HEAD route description: Dispatches HEAD requests to user-defined handler files in the workspace routes directory. tags: - user-routes parameters: - name: path in: path required: true schema: type: string responses: "200": description: Successful response options: operationId: x_by_path_options summary: User-defined OPTIONS route description: Dispatches OPTIONS requests to user-defined handler files in the workspace routes directory. tags: - user-routes parameters: - name: path in: path required: true schema: type: string responses: "200": description: Successful response patch: operationId: x_by_path_patch summary: User-defined PATCH route description: Dispatches PATCH requests to user-defined handler files in the workspace routes directory. tags: - user-routes parameters: - name: path in: path required: true schema: type: string responses: "200": description: Successful response post: operationId: x_by_path_post summary: User-defined POST route description: Dispatches POST requests to user-defined handler files in the workspace routes directory. tags: - user-routes parameters: - name: path in: path required: true schema: type: string responses: "200": description: Successful response put: operationId: x_by_path_put summary: User-defined PUT route description: Dispatches PUT requests to user-defined handler files in the workspace routes directory. tags: - user-routes parameters: - name: path in: path required: true schema: type: string responses: "200": description: Successful response components: schemas: ConfigPatchRequest: type: object properties: llm: type: object properties: default: anyOf: - type: object properties: provider: anyOf: - $ref: "#/components/schemas/LLMProvider" - type: "null" model: anyOf: - type: string minLength: 1 - type: "null" maxTokens: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: "null" effort: anyOf: - type: string enum: - none - low - medium - high - xhigh - max - type: "null" speed: anyOf: - type: string enum: - standard - fast - type: "null" verbosity: anyOf: - type: string enum: - low - medium - high - type: "null" temperature: anyOf: - anyOf: - type: number minimum: 0 maximum: 2 - type: "null" - type: "null" topP: anyOf: - anyOf: - type: number minimum: 0 maximum: 1 - type: "null" - type: "null" thinking: anyOf: - type: object properties: enabled: type: boolean streamThinking: type: boolean level: type: string enum: - minimal - low - medium - high - type: "null" contextWindow: anyOf: - type: object properties: enabled: type: boolean maxInputTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 targetBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 compactThreshold: type: number exclusiveMinimum: 0 maximum: 1 summaryBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 overflowRecovery: type: object properties: enabled: type: boolean safetyMarginRatio: type: number exclusiveMinimum: 0 exclusiveMaximum: 1 maxAttempts: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 interactiveLatestTurnCompression: type: string enum: - truncate - summarize - drop nonInteractiveLatestTurnCompression: type: string enum: - truncate - summarize - drop - type: "null" openrouter: anyOf: - type: object properties: only: type: array items: type: string minLength: 1 - type: "null" logitBias: anyOf: - type: string enum: - suppress-cjk - type: "null" disableCache: anyOf: - type: boolean - type: "null" provider_connection: anyOf: - type: string - type: "null" additionalProperties: {} - type: "null" profiles: type: object propertyNames: type: string additionalProperties: anyOf: - $ref: "#/components/schemas/ProfilePatchEntry" - type: "null" profileOrder: type: array items: type: string activeProfile: anyOf: - type: string - type: "null" advisorProfile: anyOf: - type: string - type: "null" callSites: type: object propertyNames: type: string additionalProperties: anyOf: - $ref: "#/components/schemas/CallSiteOverrideDraft" - type: "null" profileSession: anyOf: - type: object properties: defaultTtlSeconds: type: number maxTtlSeconds: type: number - type: "null" additionalProperties: {} memory: anyOf: - $ref: "#/components/schemas/MemoryConfig" - type: "null" services: type: object properties: web-search: anyOf: - type: object properties: provider: type: string additionalProperties: {} - type: "null" web-fetch: anyOf: - type: object properties: provider: type: string additionalProperties: {} - type: "null" image-generation: anyOf: - type: object properties: provider: type: string model: type: string additionalProperties: {} - type: "null" inference: anyOf: - type: object properties: mode: $ref: "#/components/schemas/ServiceMode" additionalProperties: {} - type: "null" additionalProperties: {} additionalProperties: {} LLMProvider: type: string minLength: 1 ProfilePatchEntry: type: object properties: provider: anyOf: - $ref: "#/components/schemas/LLMProvider" - type: "null" model: anyOf: - type: string minLength: 1 - type: "null" maxTokens: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: "null" effort: anyOf: - type: string enum: - none - low - medium - high - xhigh - max - type: "null" speed: anyOf: - type: string enum: - standard - fast - type: "null" verbosity: anyOf: - type: string enum: - low - medium - high - type: "null" temperature: anyOf: - anyOf: - type: number minimum: 0 maximum: 2 - type: "null" - type: "null" topP: anyOf: - anyOf: - type: number minimum: 0 maximum: 1 - type: "null" - type: "null" thinking: anyOf: - type: object properties: enabled: type: boolean streamThinking: type: boolean level: type: string enum: - minimal - low - medium - high - type: "null" contextWindow: anyOf: - type: object properties: enabled: type: boolean maxInputTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 targetBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 compactThreshold: type: number exclusiveMinimum: 0 maximum: 1 summaryBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 overflowRecovery: type: object properties: enabled: type: boolean safetyMarginRatio: type: number exclusiveMinimum: 0 exclusiveMaximum: 1 maxAttempts: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 interactiveLatestTurnCompression: type: string enum: - truncate - summarize - drop nonInteractiveLatestTurnCompression: type: string enum: - truncate - summarize - drop - type: "null" openrouter: anyOf: - type: object properties: only: type: array items: type: string minLength: 1 - type: "null" logitBias: anyOf: - type: string enum: - suppress-cjk - type: "null" disableCache: anyOf: - type: boolean - type: "null" source: anyOf: - type: string enum: - managed - user - type: "null" label: anyOf: - anyOf: - type: string minLength: 1 - type: "null" - type: "null" description: anyOf: - type: string - type: "null" provider_connection: anyOf: - type: string minLength: 1 - type: "null" status: anyOf: - anyOf: - $ref: "#/components/schemas/ProfileStatus" - type: "null" - type: "null" mix: anyOf: - minItems: 2 type: array items: type: object properties: profile: type: string minLength: 1 weight: type: number exclusiveMinimum: 0 required: - profile - weight - type: "null" additionalProperties: {} ProfileStatus: type: string enum: - active - disabled CallSiteOverrideDraft: type: object properties: provider: anyOf: - $ref: "#/components/schemas/LLMProvider" - type: "null" model: anyOf: - type: string minLength: 1 - type: "null" maxTokens: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: "null" effort: anyOf: - type: string enum: - none - low - medium - high - xhigh - max - type: "null" speed: anyOf: - type: string enum: - standard - fast - type: "null" verbosity: anyOf: - type: string enum: - low - medium - high - type: "null" temperature: anyOf: - anyOf: - type: number minimum: 0 maximum: 2 - type: "null" - type: "null" topP: anyOf: - anyOf: - type: number minimum: 0 maximum: 1 - type: "null" - type: "null" thinking: anyOf: - type: object properties: enabled: type: boolean streamThinking: type: boolean level: type: string enum: - minimal - low - medium - high - type: "null" contextWindow: anyOf: - type: object properties: enabled: type: boolean maxInputTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 targetBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 compactThreshold: type: number exclusiveMinimum: 0 maximum: 1 summaryBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 overflowRecovery: type: object properties: enabled: type: boolean safetyMarginRatio: type: number exclusiveMinimum: 0 exclusiveMaximum: 1 maxAttempts: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 interactiveLatestTurnCompression: type: string enum: - truncate - summarize - drop nonInteractiveLatestTurnCompression: type: string enum: - truncate - summarize - drop - type: "null" openrouter: anyOf: - type: object properties: only: type: array items: type: string minLength: 1 - type: "null" logitBias: anyOf: - type: string enum: - suppress-cjk - type: "null" disableCache: anyOf: - type: boolean - type: "null" profile: anyOf: - type: string - type: "null" additionalProperties: {} MemoryConfig: type: object properties: enabled: type: boolean v2: type: object properties: enabled: type: boolean additionalProperties: {} additionalProperties: {} ServiceMode: type: string enum: - managed - your-own ConnectionProvider: type: string enum: - anthropic - openai - gemini - ollama - fireworks - together - openrouter - vercel-ai-gateway - litellm - openai-compatible - minimax - atlascloud - baseten - poolside - vellum - chatgpt Auth: oneOf: - type: object properties: type: type: string const: api_key credential: type: string minLength: 1 required: - type - credential - type: object properties: type: type: string const: platform required: - type - type: object properties: type: type: string const: none required: - type - type: object properties: type: type: string const: oauth_subscription credential: type: string minLength: 1 required: - type - credential - type: object properties: type: type: string const: service_account credential: type: string minLength: 1 required: - type - credential type: object ConnectionModel: type: object properties: id: type: string minLength: 1 displayName: type: string minLength: 1 required: - id TelemetryJsonValue: anyOf: - type: string - type: number - type: boolean - type: "null" - type: array items: $ref: "#/components/schemas/TelemetryJsonValue" - type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/TelemetryJsonValue" ConfigGetResponse: type: object properties: llm: type: object properties: default: type: object properties: provider: $ref: "#/components/schemas/LLMProvider" model: type: string minLength: 1 maxTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 effort: type: string enum: - none - low - medium - high - xhigh - max speed: type: string enum: - standard - fast verbosity: type: string enum: - low - medium - high temperature: anyOf: - type: number minimum: 0 maximum: 2 - type: "null" topP: anyOf: - type: number minimum: 0 maximum: 1 - type: "null" thinking: type: object properties: enabled: type: boolean streamThinking: type: boolean level: type: string enum: - minimal - low - medium - high additionalProperties: false contextWindow: type: object properties: enabled: type: boolean maxInputTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 targetBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 compactThreshold: type: number exclusiveMinimum: 0 maximum: 1 summaryBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 overflowRecovery: type: object properties: enabled: type: boolean safetyMarginRatio: type: number exclusiveMinimum: 0 exclusiveMaximum: 1 maxAttempts: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 interactiveLatestTurnCompression: type: string enum: - truncate - summarize - drop nonInteractiveLatestTurnCompression: type: string enum: - truncate - summarize - drop additionalProperties: false additionalProperties: false openrouter: type: object properties: only: type: array items: type: string minLength: 1 additionalProperties: false logitBias: type: string enum: - suppress-cjk disableCache: type: boolean provider_connection: type: string additionalProperties: false defaultProvider: type: object properties: provider: type: string enum: - anthropic - openai - gemini - fireworks - openrouter - chatgpt - vellum - together - vercel-ai-gateway - minimax - atlascloud - baseten - poolside connectionName: type: string minLength: 1 required: - provider additionalProperties: false profiles: type: object propertyNames: type: string additionalProperties: $ref: "#/components/schemas/ProfileEntry" profileOrder: type: array items: type: string activeProfile: type: string advisorProfile: type: string callSites: type: object propertyNames: type: string additionalProperties: anyOf: - type: object properties: provider: $ref: "#/components/schemas/LLMProvider" model: type: string minLength: 1 maxTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 effort: type: string enum: - none - low - medium - high - xhigh - max speed: type: string enum: - standard - fast verbosity: type: string enum: - low - medium - high temperature: anyOf: - type: number minimum: 0 maximum: 2 - type: "null" topP: anyOf: - type: number minimum: 0 maximum: 1 - type: "null" thinking: type: object properties: enabled: type: boolean streamThinking: type: boolean level: type: string enum: - minimal - low - medium - high additionalProperties: false contextWindow: type: object properties: enabled: type: boolean maxInputTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 targetBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 compactThreshold: type: number exclusiveMinimum: 0 maximum: 1 summaryBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 overflowRecovery: type: object properties: enabled: type: boolean safetyMarginRatio: type: number exclusiveMinimum: 0 exclusiveMaximum: 1 maxAttempts: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 interactiveLatestTurnCompression: type: string enum: - truncate - summarize - drop nonInteractiveLatestTurnCompression: type: string enum: - truncate - summarize - drop additionalProperties: false additionalProperties: false openrouter: type: object properties: only: type: array items: type: string minLength: 1 additionalProperties: false logitBias: type: string enum: - suppress-cjk disableCache: type: boolean profile: type: string additionalProperties: false - type: "null" profileSession: type: object properties: defaultTtlSeconds: type: number maxTtlSeconds: type: number additionalProperties: false pricingOverrides: type: array items: {} additionalProperties: {} memory: $ref: "#/components/schemas/MemoryConfig" services: type: object properties: web-search: type: object properties: provider: type: string additionalProperties: {} web-fetch: type: object properties: provider: type: string additionalProperties: {} image-generation: type: object properties: provider: type: string model: type: string additionalProperties: {} inference: type: object properties: mode: $ref: "#/components/schemas/ServiceMode" additionalProperties: {} additionalProperties: {} additionalProperties: {} ProfileEntry: type: object properties: provider: $ref: "#/components/schemas/LLMProvider" model: type: string minLength: 1 maxTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 effort: type: string enum: - none - low - medium - high - xhigh - max speed: type: string enum: - standard - fast verbosity: type: string enum: - low - medium - high temperature: anyOf: - type: number minimum: 0 maximum: 2 - type: "null" topP: anyOf: - type: number minimum: 0 maximum: 1 - type: "null" thinking: type: object properties: enabled: type: boolean streamThinking: type: boolean level: type: string enum: - minimal - low - medium - high additionalProperties: false contextWindow: type: object properties: enabled: type: boolean maxInputTokens: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 targetBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 compactThreshold: type: number exclusiveMinimum: 0 maximum: 1 summaryBudgetRatio: type: number exclusiveMinimum: 0 maximum: 1 overflowRecovery: type: object properties: enabled: type: boolean safetyMarginRatio: type: number exclusiveMinimum: 0 exclusiveMaximum: 1 maxAttempts: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 interactiveLatestTurnCompression: type: string enum: - truncate - summarize - drop nonInteractiveLatestTurnCompression: type: string enum: - truncate - summarize - drop additionalProperties: false additionalProperties: false openrouter: type: object properties: only: type: array items: type: string minLength: 1 additionalProperties: false logitBias: type: string enum: - suppress-cjk disableCache: type: boolean source: type: string enum: - managed - user label: anyOf: - type: string minLength: 1 - type: "null" description: type: string provider_connection: type: string minLength: 1 status: anyOf: - $ref: "#/components/schemas/ProfileStatus" - type: "null" mix: minItems: 2 type: array items: type: object properties: profile: type: string minLength: 1 weight: type: number exclusiveMinimum: 0 required: - profile - weight additionalProperties: false supportsVision: type: boolean invariant: type: boolean additionalProperties: {} DefaultProviderStatus: type: object properties: provider: anyOf: - type: string enum: - anthropic - openai - gemini - fireworks - openrouter - chatgpt - vellum - together - vercel-ai-gateway - minimax - atlascloud - baseten - poolside - type: "null" connectionName: type: string resolvedConnectionName: anyOf: - type: string - type: "null" availability: type: object properties: status: type: string enum: - ok - incomplete - missing_connection - missing_credential - provider_mismatch - unsupported_auth - vellum_unauthenticated - unknown - missing_default message: type: string required: - status additionalProperties: false required: - provider - resolvedConnectionName - availability additionalProperties: false CallSiteResolutionSummary: type: object properties: callSite: type: string profile: anyOf: - type: string - type: "null" label: anyOf: - type: string - type: "null" source: type: string enum: - override - active - call_site - default provider: type: string model: type: string effort: type: string maxTokens: type: number maxInputTokens: type: number required: - callSite - profile - label - source - provider - model - effort - maxTokens additionalProperties: false CallSiteResolutionDetail: type: object properties: callSite: type: string winner: type: object properties: profile: anyOf: - type: string - type: "null" label: anyOf: - type: string - type: "null" source: type: string enum: - override - active - call_site - default required: - profile - label - source additionalProperties: false resolved: type: object properties: provider: type: string model: type: string maxTokens: type: number effort: type: string temperature: anyOf: - type: number - type: "null" maxInputTokens: type: number required: - provider - model - maxTokens - effort - temperature additionalProperties: false resolutionChain: type: array items: type: object properties: requested: type: string reason: type: string enum: - missing - disabled - incomplete required: - requested - reason additionalProperties: false shippedDefault: type: object propertyNames: type: string additionalProperties: {} userPin: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: "null" resolutionError: type: object properties: reason: type: string message: type: string required: - reason - message additionalProperties: false required: - callSite - winner - resolved - resolutionChain - shippedDefault - userPin additionalProperties: false CatalogModel: type: object properties: provider: type: string id: type: string displayName: type: string contextWindowTokens: type: number maxOutputTokens: type: number supportsThinking: type: boolean supportsVision: type: boolean supportsToolUse: type: boolean featureFlag: type: string required: - provider - id - displayName additionalProperties: false InferenceProfileSummary: type: object properties: name: type: string label: anyOf: - type: string - type: "null" provider: anyOf: - type: string - type: "null" model: anyOf: - type: string - type: "null" status: type: string enum: - active - disabled source: type: string enum: - managed - user provider_connection: type: string availability: anyOf: - $ref: "#/components/schemas/ProfileConnectionAvailability" - type: "null" required: - name - label - provider - model - status - source - availability additionalProperties: false ProfileConnectionAvailability: type: object properties: status: type: string enum: - ok - incomplete - missing_connection - missing_credential - provider_mismatch - unsupported_auth - vellum_unauthenticated - unknown message: type: string required: - status additionalProperties: false InferenceProfileWriteResult: type: object properties: ok: type: boolean const: true name: type: string entry: type: object propertyNames: type: string additionalProperties: {} warnings: type: array items: type: string verify: type: string required: - ok - name - entry - warnings - verify additionalProperties: false InferenceProfileDetail: type: object properties: name: type: string entry: type: object propertyNames: type: string additionalProperties: {} availability: anyOf: - $ref: "#/components/schemas/ProfileConnectionAvailability" - type: "null" required: - name - entry - availability additionalProperties: false ProviderConnection: type: object properties: name: type: string minLength: 1 provider: $ref: "#/components/schemas/ConnectionProvider" auth: $ref: "#/components/schemas/AuthOutput" label: anyOf: - type: string minLength: 1 - type: "null" baseUrl: anyOf: - type: string format: uri - type: "null" models: anyOf: - type: array items: $ref: "#/components/schemas/ConnectionModelOutput" - type: "null" createdAt: type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAt: type: integer minimum: -9007199254740991 maximum: 9007199254740991 isManaged: type: boolean required: - name - provider - auth - label - baseUrl - models - createdAt - updatedAt - isManaged additionalProperties: false ProcessEntry: type: object properties: name: type: string status: type: string enum: - running - not_running - unreachable origin: type: string pattern: ^(workspace|plugin:.+)$ description: "Process origin: 'workspace' for the daemon and its subsystems, or 'plugin:' for a process spawned from a plugin (e.g. 'plugin:default-memory', 'plugin:cognee')." children: type: array items: $ref: "#/components/schemas/ProcessEntry" info: type: string required: - name - status - origin additionalProperties: false AuthOutput: oneOf: - type: object properties: type: type: string const: api_key credential: type: string minLength: 1 required: - type - credential additionalProperties: false - type: object properties: type: type: string const: platform required: - type additionalProperties: false - type: object properties: type: type: string const: none required: - type additionalProperties: false - type: object properties: type: type: string const: oauth_subscription credential: type: string minLength: 1 required: - type - credential additionalProperties: false - type: object properties: type: type: string const: service_account credential: type: string minLength: 1 required: - type - credential additionalProperties: false type: object ConnectionModelOutput: type: object properties: id: type: string minLength: 1 displayName: type: string minLength: 1 required: - id additionalProperties: false