asyncat
Download
ASYNCAT / DOCUMENTATIONv0.9.0-beta.1 ↗

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, 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

Cats have their own router at /api/cats/: see Cats below.

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

MethodPathDescription
GET/api/ai/chatsList conversations. Query: ?mode=chat|action&limit=50&offset=0&search=&includeArchived=false
POST/api/ai/chats/saveSave a conversation. Body: { messages, title?, mode?, conversationId? }
POST/api/ai/chats/autosaveAuto-save (no title generation). Requires ≥ 2 messages. Body: same as /save.
POST/api/ai/generate-titleGenerate a short title from message content. Body: { userMessage, aiResponse }
GET/api/ai/chats/searchFull-text search across conversation titles and messages. Query: ?q=term&limit=20
GET/api/ai/chats/trashList soft-deleted conversations.
DELETE/api/ai/chats/trash/emptyPermanently delete all trashed conversations.
GET/api/ai/chats/stats/summaryConversation statistics (counts by mode, total messages, etc.).
GET/api/ai/chats/:idGet a conversation with all messages.
PATCH/api/ai/chats/:idUpdate a conversation. Body: { title?, is_pinned?, is_archived?, folder_id? }
DELETE/api/ai/chats/:idSoft-delete (moves to trash).
POST/api/ai/chats/:id/restoreRestore a trashed conversation.
DELETE/api/ai/chats/:id/permanentPermanently delete a conversation (bypasses trash).
PATCH/api/ai/chats/:id/folderAssign a conversation to a folder. Body: { folder_id }

Chat folders

MethodPathDescription
GET/api/ai/chat-foldersList all folders. Requires ?workspaceId=.
POST/api/ai/chat-foldersCreate a folder. Body: { name, color? }
PATCH/api/ai/chat-folders/:idUpdate a folder name, color, or sort order.
DELETE/api/ai/chat-folders/:idDelete 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

FieldTypeRequiredDescription
goalstringYesThe task or message for the agent.
conversationHistoryarrayNoPrevious messages: [{ role, content }]
agentModestringNoaction (default), chat, plan, or design. In chat mode the agent responds without using tools.
profileIdstringNoAgent profile ID to use. Defaults to the user's default profile.
continueSessionIdstringNoResume a prior session. Agent picks up where it left off.
workingDirstringNoWorking directory for file and shell tools.
workingContextobjectNoStructured workspace context (rootId, relativePath).
maxRoundsnumberNoMax ReAct rounds. Default: 25 (or profile setting).
autoApprovebooleanNoSkip permission prompts for all tools. Default: false.
preApprovedToolsstring[]NoTool names to pre-approve for this run only.
agentMentionsarrayNoSub-agent profiles to make available for delegation.
fileAttachmentsarrayNoFiles to attach to the goal (max 10).
reasoningEffortstringNoauto (default), low, high. Passed to the model if supported.

SSE event types

TypeDescription
session_startSession initialized. Contains sessionId.
skills_loadedSkills loaded from disk. Contains skills[].
thinkingAgent is generating a response.
tool_startTool call starting. Contains tool name and args.
tool_resultTool call finished. Contains tool name and result.
permission_requestAgent needs approval to use a tool. Respond via POST /api/ai/permissions/:requestId.
ask_userAgent is asking the user a question. Respond via POST /api/ai/ask/:requestId.
plan_updateAgent updated its plan. Contains plan[] with statuses.
agent_delegate_startDelegating to a sub-agent profile.
agent_delegate_resultSub-agent finished.
usage_updateModel token usage update.
answerFinal answer. Run complete.
errorRun failed. Contains message.

Live permission responses

MethodPathDescription
POST/api/ai/permissions/:requestIdRespond to a permission request. Body: { decision: "allow"|"deny"|"allow_session"|"allow_always_tool" }. Times out after 5 minutes.
POST/api/ai/ask/:requestIdAnswer an ask_user prompt. Body: { answer: "..." }. Times out after 5 minutes.

Other agent endpoints

MethodPathDescription
GET/api/ai/toolsList all registered tools with name, description, permission level, and category.
GET/api/ai/capabilities/multimodalDetect available multimodal capabilities (vision, Whisper, TTS, image gen).
GET/api/ai/runtime/statusCurrent model runtime status (loaded model, provider, context window).
GET/api/ai/healthAgent health stats: session success/failure rates, tool usage, loop detection across recent sessions.
GET/api/ai/brain-statsQuick summary: memory entry count, total skills, auto-generated skill count.
POST/api/ai/multiRun 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.

MethodPathDescription
GET/api/ai/sessionsList recent sessions. Query: ?limit=20
GET/api/ai/sessions/searchFull-text search sessions by goal or tool content. Query: ?q=term
GET/api/ai/sessions/:idGet a session, including linked task run (if any).
PATCH/api/ai/sessions/:idEdit session goal. Body: { goal }
PATCH/api/ai/sessions/:id/planInject or replace the session plan mid-run. Body: { plan: [{ id, content, status }] }
DELETE/api/ai/sessions/:idDelete a session and its checkpoint.
GET/api/ai/sessions/:id/auditFull tool call audit log for a session (tool name, args, result, success, timing).
GET/api/ai/sessions/:id/changes/stateDerive file-system changes made during the session, plus revert availability.
POST/api/ai/sessions/:id/revertRevert all file changes made during the session using its baseline checkpoint.
POST/api/ai/sessions/:id/feedbackSubmit a 1–5 star rating. Body: { rating, comment?, was_helpful? }
POST/api/ai/sessions/:id/correctRecord a correction for self-improvement. Body: { correction, tool?, explanation? }

Checkpoints

MethodPathDescription
GET/api/ai/checkpointsList all saved workspace checkpoints.
POST/api/ai/checkpoints/restoreRestore a checkpoint by ID. Body: { id }

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

MethodPathDescription
GET/api/ai/skillsList all skills with name, description, brain region, tags, and source.
GET/api/ai/skills/:nameGet a single skill by name.
POST/api/ai/skillsCreate a skill. Body: { name, description?, brain_region?, weight?, tags?, when_to_use?, body }
PUT/api/ai/skills/:nameUpdate a skill (any field).
DELETE/api/ai/skills/:nameDelete a skill.
POST/api/ai/skills/reloadHot-reload all skills from disk without restarting the server.

Soul

MethodPathDescription
GET/api/ai/soulsList all available soul files.
GET/api/ai/soulGet a soul's raw content. Query: ?name=default
PUT/api/ai/soulWrite a soul file. Body: { name, content }. The content is a markdown system prompt with optional frontmatter.

MCP server management

MethodPathDescription
GET/api/ai/mcpList MCP servers and their connection status.
POST/api/ai/mcpAdd an MCP server. Body: { name, command, args?, env?, disabled? }
PATCH/api/ai/mcp/:nameUpdate server config (command, args, env, disabled flag).
DELETE/api/ai/mcp/:nameRemove an MCP server.
POST/api/ai/mcp/reloadReconnect 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.

MethodPathDescription
GET/api/ai/profilesList all profiles for the current user.
POST/api/ai/profilesCreate a profile. Body: { name, handle?, description?, icon?, color?, soulName?, workingDir?, maxRounds?, autoApprove?, alwaysAllowedTools?, isDefault? }
GET/api/ai/profiles/:idGet a profile by ID.
PUT/api/ai/profiles/:idUpdate a profile (any field).
DELETE/api/ai/profiles/:idDelete 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.

MethodPathDescription
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.

Cats

Scheduled jobs became Cats in 0.9 and the old /api/ai/schedule routes are gone. Cats have their own router at /api/cats: the Cats themselves, their runs and timeline, the inbox where they ask for approval or an answer, and feedback on runs. See Cats.

MethodPathDescription
GET/api/catsList your Cats.
POST/api/catsCreate a Cat.
POST/api/cats/parse-scheduleRead a schedule written in words, for previews. Body: { text, timezone }
GET/api/cats/:idGet one Cat.
PATCH/api/cats/:idChange a Cat.
DELETE/api/cats/:idDelete a Cat.
POST/api/cats/:id/wakeWake it now. With { message } it writes to the Cat in its chat; without, it runs now.
POST/api/cats/:id/cancelStop a run that is in progress.
GET/api/cats/:id/runsIts runs. Query: ?limit=
GET/api/cats/:id/timelineIts timeline. Query: limit, before, runId
POST/api/cats/:id/chatWrite to the Cat in its chat.
POST/api/cats/:id/triggers/:triggerId/checkCheck one of its triggers now.
GET/api/cats/inboxInbox items. Query: kind, status (default open), catId, limit
POST/api/cats/inbox/:itemId/answerAnswer an approval or a question.
POST/api/cats/inbox/:itemId/dismissDismiss an inbox item.
POST/api/cats/inbox/read-allMark results read, optionally for one Cat: { catId }
POST/api/cats/runs/:runId/feedbackRate a run so the Cat does better next time.

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.

MethodPathDescription
GET/api/ai/git/stateWorking tree status — staged, unstaged, untracked files, current branch.
GET/api/ai/git/logCommit history. Query: ?limit=100&skip=0
GET/api/ai/git/diffDiff output. Query: ?file=path&staged=true&compare=branch
GET/api/ai/git/branchesList local and remote branches.
GET/api/ai/git/commit/:hashGet full details for a commit.
POST/api/ai/git/commit-messageGenerate a conventional commit message using the active AI model. Body: { scope? }
POST/api/ai/git/stageStage files. Body: { files: ["path"] }
POST/api/ai/git/unstageUnstage files. Body: { files: ["path"] }
POST/api/ai/git/discardDiscard (revert) file changes. Body: { files: ["path"] }
POST/api/ai/git/commitCommit staged changes. Body: { message, files?, amend? }
POST/api/ai/git/pullPull from remote. Body: { remote?, branch? }
POST/api/ai/git/pushPush to remote. Body: { remote?, branch?, setUpstream? }. Force push is blocked.
POST/api/ai/git/stashStash operations. Body: { action: "push"|"pop"|"drop"|"list", message?, index? }
POST/api/ai/git/branchBranch 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.

MethodPathDescription
GET/api/ai/sandboxesList sandboxes. Query: ?workspaceId=&includeDeleted=false
POST/api/ai/sandboxesCreate a sandbox. Body: { name?, sourcePath?, strategy?, baseRef? }
GET/api/ai/sandboxes/:idGet sandbox status and metadata.
GET/api/ai/sandboxes/:id/diffDiff between sandbox and source. Query: ?file=path&includePatch=true
POST/api/ai/sandboxes/:id/patchExport sandbox changes as a unified diff patch. Body: { filePaths? }
POST/api/ai/sandboxes/:id/applyApply sandbox changes to the main workspace. Body: { filePaths?, dryRun? }
POST/api/ai/sandboxes/:id/commit-branchCommit sandbox changes to a new git branch. Body: { message?, filePaths? }
GET/api/ai/sandboxes/:id/jobsList command jobs run inside the sandbox.
POST/api/ai/sandboxes/:id/jobsRun a command inside the sandbox. Body: { command, cwd?, kind?, timeoutMs? }
GET/api/ai/sandboxes/:id/jobs/:jobIdGet job result and output.
DELETE/api/ai/sandboxes/:idDelete a sandbox. Query: ?force=true to skip confirmation.

Code intelligence

MethodPathDescription
GET/api/ai/code/searchSearch for symbols in the workspace. Query: ?q=name&kind=any|function|class&language=&limit=30
GET/api/ai/code/definitionsList all definitions in a file. Query: ?file=path
GET/api/ai/code/find-definitionFind 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.

MethodPathDescription
GET/api/ai/artifactsList all artifacts (filename, type, size, modified date). Pass X-Workspace-Root header to target a specific workspace directory.
GET/api/ai/artifacts/:filenameGet artifact content as JSON, or add ?download=1 to stream the raw file.
DELETE/api/ai/artifacts/:filenameDelete 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

MethodPathDescription
GET/api/ai/providers/configGet the currently active provider configuration.
DELETE/api/ai/providers/configReset provider config to defaults.
GET/api/ai/providers/catalogList all supported provider presets (OpenAI, Anthropic, Google, Groq, Ollama, etc.).
GET/api/ai/providers/profilesList saved provider profiles (name, model, base URL, status).
POST/api/ai/providers/profilesCreate a provider profile. Body: { name, provider_type, model, base_url?, api_key? }
PATCH/api/ai/providers/profiles/:idUpdate a provider profile.
DELETE/api/ai/providers/profiles/:idDelete a provider profile.
POST/api/ai/providers/profiles/:id/testTest a provider connection. Returns latency and model info.
POST/api/ai/providers/profiles/:id/activateSet a profile as the active provider for all agent runs.
GET/api/ai/providers/usageModel usage summary (token counts by model/provider).
GET/api/ai/providers/statsHardware stats (GPU, RAM, CPU usage).

Models

MethodPathDescription
GET/api/ai/providers/modelsList all available models (cloud + local GGUF).
GET/api/ai/providers/local-modelsList downloaded GGUF model files.
POST/api/ai/providers/local-models/downloadStart a GGUF model download. Body: { url }. Returns a download job ID.
GET/api/ai/providers/local-models/downloadsList active downloads with progress.
GET/api/ai/providers/local-models/downloads/:idGet download status and progress for a specific job.
DELETE/api/ai/providers/local-models/downloads/:idCancel an in-progress download.
DELETE/api/ai/providers/local-models/:filenameDelete a downloaded GGUF model file.
POST/api/ai/providers/local-models/startLoad a model into the built-in llama.cpp server.
GET/api/ai/providers/hf-searchSearch Hugging Face for GGUF models. Query: ?q=term
GET/api/ai/providers/recommended-modelsCurated list of recommended models for local inference.

llama.cpp server

MethodPathDescription
GET/api/ai/providers/server/statusBuilt-in llama.cpp server status (running, loaded model, port).
POST/api/ai/providers/server/startStart the server with a model.
POST/api/ai/providers/server/stopStop the server.
POST/api/ai/providers/server/activateActivate the server as the current provider.
GET/api/ai/providers/server/enginesList available inference engines (llama.cpp, MLX, etc.).
POST/api/ai/providers/server/engines/installInstall an inference engine.

Audio — Whisper & TTS

MethodPathDescription
POST/api/ai/providers/audio/transcribeTranscribe audio to text using Whisper. Body: raw audio bytes (Content-Type: audio/*). Max 50 MB.
POST/api/ai/providers/audio/speakText-to-speech synthesis. Body: { text, voice? }. Returns audio data.
GET/api/ai/providers/audio/whisper/statusWhisper server status and loaded model.
POST/api/ai/providers/audio/whisper/startStart the Whisper server.
POST/api/ai/providers/audio/whisper/stopStop the Whisper server.
GET/api/ai/providers/audio/tts/statusTTS server status.
POST/api/ai/providers/audio/tts/startStart the TTS server.
POST/api/ai/providers/audio/tts/stopStop the TTS server.
GET/api/ai/providers/audio/modelsList downloaded audio models (Whisper + TTS).

Image generation

MethodPathDescription
GET/api/ai/providers/visual/modelsList available visual/image generation models.
POST/api/ai/providers/visual/image/cloud/generateGenerate an image via a cloud provider (OpenAI DALL-E, etc.). Body: { prompt, size?, quality? }
POST/api/ai/providers/visual/image/simple/generateGenerate an image via a local model.
GET/api/ai/providers/mlx/statusMLX (Apple Silicon) server status. Only available on Apple Silicon Macs.
GET/api/ai/providers/mlx/modelsList available MLX models.
POST/api/ai/providers/mlx/startStart the MLX server.
POST/api/ai/providers/mlx/stopStop the MLX server.