AI API

All AI and agent endpoints. Requires Authorization: Bearer <token>.

Overview

The AI API is split across two mount points — both backed by the same router:

/api/ai/ — conversations, agent runtime, skills, soul, profiles, memory, scheduler, git, sandboxes, artifacts, code intelligence, MCP management
/api/agent/ — alias for all of the above (identical routes)
/api/ai/providers/ — provider config, model management, audio, and visual AI

The primary streaming endpoint is POST /api/ai/run, which runs a ReAct agent loop and streams progress as SSE (Server-Sent Events).

Conversations

Chat history is stored in the conversations SQLite table. Folders organise chats into groups.

Chats

Method	Path	Description
`GET`	`/api/ai/chats`	List conversations. Query: `?mode=chat\|action&limit=50&offset=0&search=&includeArchived=false`
`POST`	`/api/ai/chats/save`	Save a conversation. Body: `{ messages, title?, mode?, conversationId? }`
`POST`	`/api/ai/chats/autosave`	Auto-save (no title generation). Requires ≥ 2 messages. Body: same as `/save`.
`POST`	`/api/ai/generate-title`	Generate a short title from message content. Body: `{ userMessage, aiResponse }`
`GET`	`/api/ai/chats/search`	Full-text search across conversation titles and messages. Query: `?q=term&limit=20`
`GET`	`/api/ai/chats/trash`	List soft-deleted conversations.
`DELETE`	`/api/ai/chats/trash/empty`	Permanently delete all trashed conversations.
`GET`	`/api/ai/chats/stats/summary`	Conversation statistics (counts by mode, total messages, etc.).
`GET`	`/api/ai/chats/:id`	Get a conversation with all messages.
`PATCH`	`/api/ai/chats/:id`	Update a conversation. Body: `{ title?, is_pinned?, is_archived?, folder_id? }`
`DELETE`	`/api/ai/chats/:id`	Soft-delete (moves to trash).
`POST`	`/api/ai/chats/:id/restore`	Restore a trashed conversation.
`DELETE`	`/api/ai/chats/:id/permanent`	Permanently delete a conversation (bypasses trash).
`PATCH`	`/api/ai/chats/:id/folder`	Assign a conversation to a folder. Body: `{ folder_id }`

 Chat folders
   Method Path Description
 
  GET /api/ai/chat-folders List all folders. Requires ?workspaceId=.
 POST /api/ai/chat-folders Create a folder. Body: { name, color? }
 PATCH /api/ai/chat-folders/:id Update a folder name, color, or sort order.
 DELETE /api/ai/chat-folders/:id Delete a folder (chats inside are unfoldered, not deleted).

Method	Path	Description
`GET`	`/api/ai/chat-folders`	List all folders. Requires `?workspaceId=`.
`POST`	`/api/ai/chat-folders`	Create a folder. Body: `{ name, color? }`
`PATCH`	`/api/ai/chat-folders/:id`	Update a folder name, color, or sort order.
`DELETE`	`/api/ai/chat-folders/:id`	Delete a folder (chats inside are unfoldered, not deleted).

  Agent run (SSE)
 POST /api/ai/run — starts a ReAct agent loop and streams progress as Server-Sent Events (SSE). The response Content-Type is text/event-stream.
 Request body
   Field Type Required Description
 
  goal string Yes The task or message for the agent.
 conversationHistory array No Previous messages: [{ role, content }]
 agentMode string No action (default), chat, plan, or design. In chat mode the agent responds without using tools.
 profileId string No Agent profile ID to use. Defaults to the user's default profile.
 continueSessionId string No Resume a prior session. Agent picks up where it left off.
 workingDir string No Working directory for file and shell tools.
 workingContext object No Structured workspace context (rootId, relativePath).
 maxRounds number No Max ReAct rounds. Default: 25 (or profile setting).
 autoApprove boolean No Skip permission prompts for all tools. Default: false.
 preApprovedTools string[] No Tool names to pre-approve for this run only.
 agentMentions array No Sub-agent profiles to make available for delegation.
 fileAttachments array No Files to attach to the goal (max 10).
 reasoningEffort string No auto (default), low, high. Passed to the model if supported.
 
 
 SSE event types
   Type Description
 
  session_start Session initialized. Contains sessionId.
 skills_loaded Skills loaded from disk. Contains skills[].
 thinking Agent is generating a response.
 tool_start Tool call starting. Contains tool name and args.
 tool_result Tool call finished. Contains tool name and result.
 permission_request Agent needs approval to use a tool. Respond via POST /api/ai/permissions/:requestId.
 ask_user Agent is asking the user a question. Respond via POST /api/ai/ask/:requestId.
 plan_update Agent updated its plan. Contains plan[] with statuses.
 agent_delegate_start Delegating to a sub-agent profile.
 agent_delegate_result Sub-agent finished.
 usage_update Model token usage update.
 answer Final answer. Run complete.
 error Run failed. Contains message.
 
 
 Live permission responses
   Method Path Description
 
  POST /api/ai/permissions/:requestId Respond to a permission request. Body: { decision: "allow"|"deny"|"allow_session"|"allow_always_tool" }. Times out after 5 minutes.
 POST /api/ai/ask/:requestId Answer an ask_user prompt. Body: { answer: "..." }. Times out after 5 minutes.
 
 
 Other agent endpoints
   Method Path Description
 
  GET /api/ai/tools List all registered tools with name, description, permission level, and category.
 GET /api/ai/capabilities/multimodal Detect available multimodal capabilities (vision, Whisper, TTS, image gen).
 GET /api/ai/runtime/status Current model runtime status (loaded model, provider, context window).
 GET /api/ai/health Agent health stats: session success/failure rates, tool usage, loop detection across recent sessions.
 GET /api/ai/brain-stats Quick summary: memory entry count, total skills, auto-generated skill count.
 POST /api/ai/multi Run up to 10 agent tasks in parallel. Body: { tasks: [{ goal, name?, workingDir? }], maxConcurrency? }
 
 
  Sessions
 Each agent run creates an agent_sessions record. Sessions store the full reasoning trace, tool audit log, and optionally a checkpoint for revert.
   Method Path Description
 
  GET /api/ai/sessions List recent sessions. Query: ?limit=20
 GET /api/ai/sessions/search Full-text search sessions by goal or tool content. Query: ?q=term
 GET /api/ai/sessions/:id Get a session, including linked task run (if any).
 PATCH /api/ai/sessions/:id Edit session goal. Body: { goal }
 PATCH /api/ai/sessions/:id/plan Inject or replace the session plan mid-run. Body: { plan: [{ id, content, status }] }
 DELETE /api/ai/sessions/:id Delete a session and its checkpoint.
 GET /api/ai/sessions/:id/audit Full tool call audit log for a session (tool name, args, result, success, timing).
 GET /api/ai/sessions/:id/changes/state Derive file-system changes made during the session, plus revert availability.
 POST /api/ai/sessions/:id/revert Revert all file changes made during the session using its baseline checkpoint.
 POST /api/ai/sessions/:id/feedback Submit a 1–5 star rating. Body: { rating, comment?, was_helpful? }
 POST /api/ai/sessions/:id/correct Record a correction for self-improvement. Body: { correction, tool?, explanation? }
 
 
 Checkpoints
   Method Path Description
 
  GET /api/ai/checkpoints List all saved workspace checkpoints.
 POST /api/ai/checkpoints/restore Restore a checkpoint by ID. Body: { id }
 
 
  Task runs
 Task runs link agent sessions to kanban cards. When you assign a card to an agent, a task run is created and the agent works on it in the background. Task runs can also be created via the API.
   Method Path Description
 
  GET /api/ai/task-runs List all task runs with their linked cards. Query: ?projectId=&cardId=
 POST /api/ai/task-runs Create and start a task run. Body: { cardId, profileId?, goal? }. If goal is omitted, it is generated from the card title, description, and checklist.
 GET /api/ai/task-runs/:id Get a task run with status, session, and audit log.
 POST /api/ai/task-runs/:id/cancel Cancel a queued or running task run.
 
 
 Task run statuses: queued, running, completed, failed, cancelled. A failed run with displayStatus: "needs_input" means the agent stopped because it needed user clarification.
 
  Skills & Soul
 Skills are reusable instruction blocks injected into the agent's system prompt. Soul files define the agent's personality and base system prompt.
 Skills
   Method Path Description
 
  GET /api/ai/skills List all skills with name, description, brain region, tags, and source.
 GET /api/ai/skills/:name Get a single skill by name.
 POST /api/ai/skills Create a skill. Body: { name, description?, brain_region?, weight?, tags?, when_to_use?, body }
 PUT /api/ai/skills/:name Update a skill (any field).
 DELETE /api/ai/skills/:name Delete a skill.
 POST /api/ai/skills/reload Hot-reload all skills from disk without restarting the server.
 
 
 Soul
   Method Path Description
 
  GET /api/ai/souls List all available soul files.
 GET /api/ai/soul Get a soul's raw content. Query: ?name=default
 PUT /api/ai/soul Write a soul file. Body: { name, content }. The content is a markdown system prompt with optional frontmatter.
 
 
 MCP server management
   Method Path Description
 
  GET /api/ai/mcp List MCP servers and their connection status.
 POST /api/ai/mcp Add an MCP server. Body: { name, command, args?, env?, disabled? }
 PATCH /api/ai/mcp/:name Update server config (command, args, env, disabled flag).
 DELETE /api/ai/mcp/:name Remove an MCP server.
 POST /api/ai/mcp/reload Reconnect and reload tools from all configured MCP servers.
 
 
  Profiles
 Agent profiles bundle a soul, working directory, tool permissions, max rounds, and auto-approve setting into a reusable configuration. The default profile is used when no profile is specified.
   Method Path Description
 
  GET /api/ai/profiles List all profiles for the current user.
 POST /api/ai/profiles Create a profile. Body: { name, handle?, description?, icon?, color?, soulName?, workingDir?, maxRounds?, autoApprove?, alwaysAllowedTools?, isDefault? }
 GET /api/ai/profiles/:id Get a profile by ID.
 PUT /api/ai/profiles/:id Update a profile (any field).
 DELETE /api/ai/profiles/:id Delete a profile.
 
 
 alwaysAllowedTools — array of tool names pre-approved for every run using this profile. The agent will not prompt for permission on these tools.
 
  Memory
 Persistent key-value memory stored in the agent_memory table. Memory entries have a memory_type for categorisation and an importance score. The agent reads and writes memory using the save_memory / recall_memory tools.
   Method Path Description
 
   GET  /api/ai/memory  List or search memory entries. Query: ?q=term (search), ?kind=all|user|feedback|project|reference|fact|preference|context|task_state, ?limit=50  
  GET  /api/ai/memory/:key  Get a specific memory entry by key. Increments access count.  
  DELETE  /api/ai/memory/:key  Delete a memory entry by key (URL param).  
  DELETE  /api/ai/memory  Delete a memory entry by key (request body). Body: { key }  
 
 
 Memory types: user, feedback, project, reference, fact, preference, context, task_state.
 
  Scheduler
 Cron-based scheduler that runs agent goals automatically. Jobs are stored in scheduled_jobs and their history in scheduled_job_runs. Schedule format: standard 5-field cron (minute hour day month weekday) or plain English intervals like @daily, @hourly.
   Method Path Description
 
  GET /api/ai/schedule List all scheduled jobs with their next run time and provider info.
 POST /api/ai/schedule Create a job. Body: { name, goal, schedule, profileId?, providerProfileId?, workingDir? }
 PATCH /api/ai/schedule/:id Update a job (name, goal, schedule, enabled, profile, provider, workingDir).
 DELETE /api/ai/schedule/:id Delete a job.
 POST /api/ai/schedule/:id/run-now Trigger a job immediately, outside its schedule.
 GET /api/ai/schedule/:id/runs Get job run history. Query: ?limit=20
 PATCH /api/ai/schedule/:id/enable Enable a disabled job.
 PATCH /api/ai/schedule/:id/disable Disable a job without deleting it.
 
 
 Note: Scheduled runs cannot request live permission approval — pre-approve tools in the linked profile or enable autoApprove on the profile.
 
  Git
 Visual git workflow endpoints. All operate on a working directory resolved from the request. Pass ?path=/absolute/path or include workingContext in the body.
   Method Path Description
 
  GET /api/ai/git/state Working tree status — staged, unstaged, untracked files, current branch.
 GET /api/ai/git/log Commit history. Query: ?limit=100&skip=0
 GET /api/ai/git/diff Diff output. Query: ?file=path&staged=true&compare=branch
 GET /api/ai/git/branches List local and remote branches.
 GET /api/ai/git/commit/:hash Get full details for a commit.
 POST /api/ai/git/commit-message Generate a conventional commit message using the active AI model. Body: { scope? }
 POST /api/ai/git/stage Stage files. Body: { files: ["path"] }
 POST /api/ai/git/unstage Unstage files. Body: { files: ["path"] }
 POST /api/ai/git/discard Discard (revert) file changes. Body: { files: ["path"] }
 POST /api/ai/git/commit Commit staged changes. Body: { message, files?, amend? }
 POST /api/ai/git/pull Pull from remote. Body: { remote?, branch? }
 POST /api/ai/git/push Push to remote. Body: { remote?, branch?, setUpstream? }. Force push is blocked.
 POST /api/ai/git/stash Stash operations. Body: { action: "push"|"pop"|"drop"|"list", message?, index? }
 POST /api/ai/git/branch Branch operations. Body: { action: "create"|"checkout"|"delete"|"list", name? }
 
 
  Sandboxes
 Sandboxes are isolated copies of a workspace (or a subset of it) where the agent can make changes, test code, and produce a patch — without touching the real working directory until you explicitly apply it.
   Method Path Description
 
  GET /api/ai/sandboxes List sandboxes. Query: ?workspaceId=&includeDeleted=false
 POST /api/ai/sandboxes Create a sandbox. Body: { name?, sourcePath?, strategy?, baseRef? }
 GET /api/ai/sandboxes/:id Get sandbox status and metadata.
 GET /api/ai/sandboxes/:id/diff Diff between sandbox and source. Query: ?file=path&includePatch=true
 POST /api/ai/sandboxes/:id/patch Export sandbox changes as a unified diff patch. Body: { filePaths? }
 POST /api/ai/sandboxes/:id/apply Apply sandbox changes to the main workspace. Body: { filePaths?, dryRun? }
 POST /api/ai/sandboxes/:id/commit-branch Commit sandbox changes to a new git branch. Body: { message?, filePaths? }
 GET /api/ai/sandboxes/:id/jobs List command jobs run inside the sandbox.
 POST /api/ai/sandboxes/:id/jobs Run a command inside the sandbox. Body: { command, cwd?, kind?, timeoutMs? }
 GET /api/ai/sandboxes/:id/jobs/:jobId Get job result and output.
 DELETE /api/ai/sandboxes/:id Delete a sandbox. Query: ?force=true to skip confirmation.
 
 
 Code intelligence
   Method Path Description
 
  GET /api/ai/code/search Search for symbols in the workspace. Query: ?q=name&kind=any|function|class&language=&limit=30
 GET /api/ai/code/definitions List all definitions in a file. Query: ?file=path
 GET /api/ai/code/find-definition Find definition location of a symbol. Query: ?q=symbol&language=
 
 
 
  Artifacts
 Artifacts are files generated by the agent and stored in .asyncat/artifacts/ inside the workspace. They include reports, exports, generated code, and any other output the agent writes there.
   Method Path Description
 
  GET /api/ai/artifacts List all artifacts (filename, type, size, modified date). Pass X-Workspace-Root header to target a specific workspace directory.
 GET /api/ai/artifacts/:filename Get artifact content as JSON, or add ?download=1 to stream the raw file.
 DELETE /api/ai/artifacts/:filename Delete an artifact.
 
 
 
  Providers
 Mounted at /api/ai/providers. Manages cloud and local AI providers, model downloads, audio (Whisper + TTS), and image generation.
 Provider profiles & config
   Method Path Description
 
  GET /api/ai/providers/config Get the currently active provider configuration.
 DELETE /api/ai/providers/config Reset provider config to defaults.
 GET /api/ai/providers/catalog List all supported provider presets (OpenAI, Anthropic, Google, Groq, Ollama, etc.).
 GET /api/ai/providers/profiles List saved provider profiles (name, model, base URL, status).
 POST /api/ai/providers/profiles Create a provider profile. Body: { name, provider_type, model, base_url?, api_key? }
 PATCH /api/ai/providers/profiles/:id Update a provider profile.
 DELETE /api/ai/providers/profiles/:id Delete a provider profile.
 POST /api/ai/providers/profiles/:id/test Test a provider connection. Returns latency and model info.
 POST /api/ai/providers/profiles/:id/activate Set a profile as the active provider for all agent runs.
 GET /api/ai/providers/usage Model usage summary (token counts by model/provider).
 GET /api/ai/providers/stats Hardware stats (GPU, RAM, CPU usage).
 
 
 Models
   Method Path Description
 
  GET /api/ai/providers/models List all available models (cloud + local GGUF).
 GET /api/ai/providers/local-models List downloaded GGUF model files.
 POST /api/ai/providers/local-models/download Start a GGUF model download. Body: { url }. Returns a download job ID.
 GET /api/ai/providers/local-models/downloads List active downloads with progress.
 GET /api/ai/providers/local-models/downloads/:id Get download status and progress for a specific job.
 DELETE /api/ai/providers/local-models/downloads/:id Cancel an in-progress download.
 DELETE /api/ai/providers/local-models/:filename Delete a downloaded GGUF model file.
 POST /api/ai/providers/local-models/start Load a model into the built-in llama.cpp server.
 GET /api/ai/providers/hf-search Search Hugging Face for GGUF models. Query: ?q=term
 GET /api/ai/providers/recommended-models Curated list of recommended models for local inference.
 
 
 llama.cpp server
   Method Path Description
 
  GET /api/ai/providers/server/status Built-in llama.cpp server status (running, loaded model, port).
 POST /api/ai/providers/server/start Start the server with a model.
 POST /api/ai/providers/server/stop Stop the server.
 POST /api/ai/providers/server/activate Activate the server as the current provider.
 GET /api/ai/providers/server/engines List available inference engines (llama.cpp, MLX, etc.).
 POST /api/ai/providers/server/engines/install Install an inference engine.
 
 
 Audio — Whisper & TTS
   Method Path Description
 
  POST /api/ai/providers/audio/transcribe Transcribe audio to text using Whisper. Body: raw audio bytes (Content-Type: audio/*). Max 50 MB.
 POST /api/ai/providers/audio/speak Text-to-speech synthesis. Body: { text, voice? }. Returns audio data.
 GET /api/ai/providers/audio/whisper/status Whisper server status and loaded model.
 POST /api/ai/providers/audio/whisper/start Start the Whisper server.
 POST /api/ai/providers/audio/whisper/stop Stop the Whisper server.
 GET /api/ai/providers/audio/tts/status TTS server status.
 POST /api/ai/providers/audio/tts/start Start the TTS server.
 POST /api/ai/providers/audio/tts/stop Stop the TTS server.
 GET /api/ai/providers/audio/models List downloaded audio models (Whisper + TTS).
 
 
 Image generation
   Method Path Description
 
  GET /api/ai/providers/visual/models List available visual/image generation models.
 POST /api/ai/providers/visual/image/cloud/generate Generate an image via a cloud provider (OpenAI DALL-E, etc.). Body: { prompt, size?, quality? }
 POST /api/ai/providers/visual/image/simple/generate Generate an image via a local model.
 GET /api/ai/providers/mlx/status MLX (Apple Silicon) server status. Only available on Apple Silicon Macs.
 GET /api/ai/providers/mlx/models List available MLX models.
 POST /api/ai/providers/mlx/start Start the MLX server.
 POST /api/ai/providers/mlx/stop Stop the MLX server.

Type	Description
`session_start`	Session initialized. Contains `sessionId`.
`skills_loaded`	Skills loaded from disk. Contains `skills[]`.
`thinking`	Agent is generating a response.
`tool_start`	Tool call starting. Contains `tool` name and `args`.
`tool_result`	Tool call finished. Contains `tool` name and `result`.
`permission_request`	Agent needs approval to use a tool. Respond via `POST /api/ai/permissions/:requestId`.
`ask_user`	Agent is asking the user a question. Respond via `POST /api/ai/ask/:requestId`.
`plan_update`	Agent updated its plan. Contains `plan[]` with statuses.
`agent_delegate_start`	Delegating to a sub-agent profile.
`agent_delegate_result`	Sub-agent finished.
`usage_update`	Model token usage update.
`answer`	Final answer. Run complete.
`error`	Run failed. Contains `message`.

Method	Path	Description
`GET`	`/api/ai/git/state`	Working tree status — staged, unstaged, untracked files, current branch.
`GET`	`/api/ai/git/log`	Commit history. Query: `?limit=100&skip=0`
`GET`	`/api/ai/git/diff`	Diff output. Query: `?file=path&staged=true&compare=branch`
`GET`	`/api/ai/git/branches`	List local and remote branches.
`GET`	`/api/ai/git/commit/:hash`	Get full details for a commit.
`POST`	`/api/ai/git/commit-message`	Generate a conventional commit message using the active AI model. Body: `{ scope? }`
`POST`	`/api/ai/git/stage`	Stage files. Body: `{ files: ["path"] }`
`POST`	`/api/ai/git/unstage`	Unstage files. Body: `{ files: ["path"] }`
`POST`	`/api/ai/git/discard`	Discard (revert) file changes. Body: `{ files: ["path"] }`
`POST`	`/api/ai/git/commit`	Commit staged changes. Body: `{ message, files?, amend? }`
`POST`	`/api/ai/git/pull`	Pull from remote. Body: `{ remote?, branch? }`
`POST`	`/api/ai/git/push`	Push to remote. Body: `{ remote?, branch?, setUpstream? }`. Force push is blocked.
`POST`	`/api/ai/git/stash`	Stash operations. Body: `{ action: "push"\|"pop"\|"drop"\|"list", message?, index? }`
`POST`	`/api/ai/git/branch`	Branch operations. Body: `{ action: "create"\|"checkout"\|"delete"\|"list", name? }`

Method	Path	Description
`GET`	`/api/ai/sandboxes`	List sandboxes. Query: `?workspaceId=&includeDeleted=false`
`POST`	`/api/ai/sandboxes`	Create a sandbox. Body: `{ name?, sourcePath?, strategy?, baseRef? }`
`GET`	`/api/ai/sandboxes/:id`	Get sandbox status and metadata.
`GET`	`/api/ai/sandboxes/:id/diff`	Diff between sandbox and source. Query: `?file=path&includePatch=true`
`POST`	`/api/ai/sandboxes/:id/patch`	Export sandbox changes as a unified diff patch. Body: `{ filePaths? }`
`POST`	`/api/ai/sandboxes/:id/apply`	Apply sandbox changes to the main workspace. Body: `{ filePaths?, dryRun? }`
`POST`	`/api/ai/sandboxes/:id/commit-branch`	Commit sandbox changes to a new git branch. Body: `{ message?, filePaths? }`
`GET`	`/api/ai/sandboxes/:id/jobs`	List command jobs run inside the sandbox.
`POST`	`/api/ai/sandboxes/:id/jobs`	Run a command inside the sandbox. Body: `{ command, cwd?, kind?, timeoutMs? }`
`GET`	`/api/ai/sandboxes/:id/jobs/:jobId`	Get job result and output.
`DELETE`	`/api/ai/sandboxes/:id`	Delete a sandbox. Query: `?force=true` to skip confirmation.

Field	Type	Required	Description
`goal`	string	Yes	The task or message for the agent.
`conversationHistory`	array	No	Previous messages: `[{ role, content }]`
`agentMode`	string	No	`action` (default), `chat`, `plan`, or `design`. In `chat` mode the agent responds without using tools.
`profileId`	string	No	Agent profile ID to use. Defaults to the user's default profile.
`continueSessionId`	string	No	Resume a prior session. Agent picks up where it left off.
`workingDir`	string	No	Working directory for file and shell tools.
`workingContext`	object	No	Structured workspace context (rootId, relativePath).
`maxRounds`	number	No	Max ReAct rounds. Default: 25 (or profile setting).
`autoApprove`	boolean	No	Skip permission prompts for all tools. Default: `false`.
`preApprovedTools`	string[]	No	Tool names to pre-approve for this run only.
`agentMentions`	array	No	Sub-agent profiles to make available for delegation.
`fileAttachments`	array	No	Files to attach to the goal (max 10).
`reasoningEffort`	string	No	`auto` (default), `low`, `high`. Passed to the model if supported.

Method	Path	Description
`POST`	`/api/ai/permissions/:requestId`	Respond to a permission request. Body: `{ decision: "allow"\|"deny"\|"allow_session"\|"allow_always_tool" }`. Times out after 5 minutes.
`POST`	`/api/ai/ask/:requestId`	Answer an `ask_user` prompt. Body: `{ answer: "..." }`. Times out after 5 minutes.

Method	Path	Description
`GET`	`/api/ai/tools`	List all registered tools with name, description, permission level, and category.
`GET`	`/api/ai/capabilities/multimodal`	Detect available multimodal capabilities (vision, Whisper, TTS, image gen).
`GET`	`/api/ai/runtime/status`	Current model runtime status (loaded model, provider, context window).
`GET`	`/api/ai/health`	Agent health stats: session success/failure rates, tool usage, loop detection across recent sessions.
`GET`	`/api/ai/brain-stats`	Quick summary: memory entry count, total skills, auto-generated skill count.
`POST`	`/api/ai/multi`	Run up to 10 agent tasks in parallel. Body: `{ tasks: [{ goal, name?, workingDir? }], maxConcurrency? }`

Method	Path	Description
`GET`	`/api/ai/sessions`	List recent sessions. Query: `?limit=20`
`GET`	`/api/ai/sessions/search`	Full-text search sessions by goal or tool content. Query: `?q=term`
`GET`	`/api/ai/sessions/:id`	Get a session, including linked task run (if any).
`PATCH`	`/api/ai/sessions/:id`	Edit session goal. Body: `{ goal }`
`PATCH`	`/api/ai/sessions/:id/plan`	Inject or replace the session plan mid-run. Body: `{ plan: [{ id, content, status }] }`
`DELETE`	`/api/ai/sessions/:id`	Delete a session and its checkpoint.
`GET`	`/api/ai/sessions/:id/audit`	Full tool call audit log for a session (tool name, args, result, success, timing).
`GET`	`/api/ai/sessions/:id/changes/state`	Derive file-system changes made during the session, plus revert availability.
`POST`	`/api/ai/sessions/:id/revert`	Revert all file changes made during the session using its baseline checkpoint.
`POST`	`/api/ai/sessions/:id/feedback`	Submit a 1–5 star rating. Body: `{ rating, comment?, was_helpful? }`
`POST`	`/api/ai/sessions/:id/correct`	Record a correction for self-improvement. Body: `{ correction, tool?, explanation? }`

Method	Path	Description
`GET`	`/api/ai/checkpoints`	List all saved workspace checkpoints.
`POST`	`/api/ai/checkpoints/restore`	Restore a checkpoint by ID. Body: `{ id }`

Method	Path	Description
`GET`	`/api/ai/task-runs`	List all task runs with their linked cards. Query: `?projectId=&cardId=`
`POST`	`/api/ai/task-runs`	Create and start a task run. Body: `{ cardId, profileId?, goal? }`. If `goal` is omitted, it is generated from the card title, description, and checklist.
`GET`	`/api/ai/task-runs/:id`	Get a task run with status, session, and audit log.
`POST`	`/api/ai/task-runs/:id/cancel`	Cancel a queued or running task run.

Method	Path	Description
`GET`	`/api/ai/skills`	List all skills with name, description, brain region, tags, and source.
`GET`	`/api/ai/skills/:name`	Get a single skill by name.
`POST`	`/api/ai/skills`	Create a skill. Body: `{ name, description?, brain_region?, weight?, tags?, when_to_use?, body }`
`PUT`	`/api/ai/skills/:name`	Update a skill (any field).
`DELETE`	`/api/ai/skills/:name`	Delete a skill.
`POST`	`/api/ai/skills/reload`	Hot-reload all skills from disk without restarting the server.

Method	Path	Description
`GET`	`/api/ai/souls`	List all available soul files.
`GET`	`/api/ai/soul`	Get a soul's raw content. Query: `?name=default`
`PUT`	`/api/ai/soul`	Write a soul file. Body: `{ name, content }`. The content is a markdown system prompt with optional frontmatter.

Method	Path	Description
`GET`	`/api/ai/mcp`	List MCP servers and their connection status.
`POST`	`/api/ai/mcp`	Add an MCP server. Body: `{ name, command, args?, env?, disabled? }`
`PATCH`	`/api/ai/mcp/:name`	Update server config (command, args, env, disabled flag).
`DELETE`	`/api/ai/mcp/:name`	Remove an MCP server.
`POST`	`/api/ai/mcp/reload`	Reconnect and reload tools from all configured MCP servers.

Method	Path	Description
`GET`	`/api/ai/profiles`	List all profiles for the current user.
`POST`	`/api/ai/profiles`	Create a profile. Body: `{ name, handle?, description?, icon?, color?, soulName?, workingDir?, maxRounds?, autoApprove?, alwaysAllowedTools?, isDefault? }`
`GET`	`/api/ai/profiles/:id`	Get a profile by ID.
`PUT`	`/api/ai/profiles/:id`	Update a profile (any field).
`DELETE`	`/api/ai/profiles/:id`	Delete a profile.

Method	Path	Description
`GET`	`/api/ai/memory`	List or search memory entries. Query: `?q=term` (search), `?kind=all\|user\|feedback\|project\|reference\|fact\|preference\|context\|task_state`, `?limit=50`
`GET`	`/api/ai/memory/:key`	Get a specific memory entry by key. Increments access count.
`DELETE`	`/api/ai/memory/:key`	Delete a memory entry by key (URL param).
`DELETE`	`/api/ai/memory`	Delete a memory entry by key (request body). Body: `{ key }`

Method	Path	Description
`GET`	`/api/ai/schedule`	List all scheduled jobs with their next run time and provider info.
`POST`	`/api/ai/schedule`	Create a job. Body: `{ name, goal, schedule, profileId?, providerProfileId?, workingDir? }`
`PATCH`	`/api/ai/schedule/:id`	Update a job (name, goal, schedule, enabled, profile, provider, workingDir).
`DELETE`	`/api/ai/schedule/:id`	Delete a job.
`POST`	`/api/ai/schedule/:id/run-now`	Trigger a job immediately, outside its schedule.
`GET`	`/api/ai/schedule/:id/runs`	Get job run history. Query: `?limit=20`
`PATCH`	`/api/ai/schedule/:id/enable`	Enable a disabled job.
`PATCH`	`/api/ai/schedule/:id/disable`	Disable a job without deleting it.

Method	Path	Description
`GET`	`/api/ai/code/search`	Search for symbols in the workspace. Query: `?q=name&kind=any\|function\|class&language=&limit=30`
`GET`	`/api/ai/code/definitions`	List all definitions in a file. Query: `?file=path`
`GET`	`/api/ai/code/find-definition`	Find definition location of a symbol. Query: `?q=symbol&language=`

Method	Path	Description
`GET`	`/api/ai/artifacts`	List all artifacts (filename, type, size, modified date). Pass `X-Workspace-Root` header to target a specific workspace directory.
`GET`	`/api/ai/artifacts/:filename`	Get artifact content as JSON, or add `?download=1` to stream the raw file.
`DELETE`	`/api/ai/artifacts/:filename`	Delete an artifact.

Method	Path	Description
`GET`	`/api/ai/providers/config`	Get the currently active provider configuration.
`DELETE`	`/api/ai/providers/config`	Reset provider config to defaults.
`GET`	`/api/ai/providers/catalog`	List all supported provider presets (OpenAI, Anthropic, Google, Groq, Ollama, etc.).
`GET`	`/api/ai/providers/profiles`	List saved provider profiles (name, model, base URL, status).
`POST`	`/api/ai/providers/profiles`	Create a provider profile. Body: `{ name, provider_type, model, base_url?, api_key? }`
`PATCH`	`/api/ai/providers/profiles/:id`	Update a provider profile.
`DELETE`	`/api/ai/providers/profiles/:id`	Delete a provider profile.
`POST`	`/api/ai/providers/profiles/:id/test`	Test a provider connection. Returns latency and model info.
`POST`	`/api/ai/providers/profiles/:id/activate`	Set a profile as the active provider for all agent runs.
`GET`	`/api/ai/providers/usage`	Model usage summary (token counts by model/provider).
`GET`	`/api/ai/providers/stats`	Hardware stats (GPU, RAM, CPU usage).

Method	Path	Description
`GET`	`/api/ai/providers/models`	List all available models (cloud + local GGUF).
`GET`	`/api/ai/providers/local-models`	List downloaded GGUF model files.
`POST`	`/api/ai/providers/local-models/download`	Start a GGUF model download. Body: `{ url }`. Returns a download job ID.
`GET`	`/api/ai/providers/local-models/downloads`	List active downloads with progress.
`GET`	`/api/ai/providers/local-models/downloads/:id`	Get download status and progress for a specific job.
`DELETE`	`/api/ai/providers/local-models/downloads/:id`	Cancel an in-progress download.
`DELETE`	`/api/ai/providers/local-models/:filename`	Delete a downloaded GGUF model file.
`POST`	`/api/ai/providers/local-models/start`	Load a model into the built-in llama.cpp server.
`GET`	`/api/ai/providers/hf-search`	Search Hugging Face for GGUF models. Query: `?q=term`
`GET`	`/api/ai/providers/recommended-models`	Curated list of recommended models for local inference.

Method	Path	Description
`GET`	`/api/ai/providers/server/status`	Built-in llama.cpp server status (running, loaded model, port).
`POST`	`/api/ai/providers/server/start`	Start the server with a model.
`POST`	`/api/ai/providers/server/stop`	Stop the server.
`POST`	`/api/ai/providers/server/activate`	Activate the server as the current provider.
`GET`	`/api/ai/providers/server/engines`	List available inference engines (llama.cpp, MLX, etc.).
`POST`	`/api/ai/providers/server/engines/install`	Install an inference engine.

Method	Path	Description
`POST`	`/api/ai/providers/audio/transcribe`	Transcribe audio to text using Whisper. Body: raw audio bytes (`Content-Type: audio/*`). Max 50 MB.
`POST`	`/api/ai/providers/audio/speak`	Text-to-speech synthesis. Body: `{ text, voice? }`. Returns audio data.
`GET`	`/api/ai/providers/audio/whisper/status`	Whisper server status and loaded model.
`POST`	`/api/ai/providers/audio/whisper/start`	Start the Whisper server.
`POST`	`/api/ai/providers/audio/whisper/stop`	Stop the Whisper server.
`GET`	`/api/ai/providers/audio/tts/status`	TTS server status.
`POST`	`/api/ai/providers/audio/tts/start`	Start the TTS server.
`POST`	`/api/ai/providers/audio/tts/stop`	Stop the TTS server.
`GET`	`/api/ai/providers/audio/models`	List downloaded audio models (Whisper + TTS).

Method	Path	Description
`GET`	`/api/ai/providers/visual/models`	List available visual/image generation models.
`POST`	`/api/ai/providers/visual/image/cloud/generate`	Generate an image via a cloud provider (OpenAI DALL-E, etc.). Body: `{ prompt, size?, quality? }`
`POST`	`/api/ai/providers/visual/image/simple/generate`	Generate an image via a local model.
`GET`	`/api/ai/providers/mlx/status`	MLX (Apple Silicon) server status. Only available on Apple Silicon Macs.
`GET`	`/api/ai/providers/mlx/models`	List available MLX models.
`POST`	`/api/ai/providers/mlx/start`	Start the MLX server.
`POST`	`/api/ai/providers/mlx/stop`	Stop the MLX server.