sulala-docs
Platform

Agent API Reference

REST API for Sulala Agent OS — agents, run, stream, tasks, skills, memory, conversations, channels.

Base URL and auth

  • Base URL: Server origin (e.g. http://127.0.0.1:3010).
  • Auth: No built-in API key by default. If you add gateway auth, send the key in headers or query as required.

Health

MethodPathDescription
GET/healthHealth check. Returns { ok: true, service: "agent-os" }.

Agents

MethodPathDescription
GET/api/agentsList all agents (id, name, description, model, personality, skills, tools, schedule, avatar, etc.).
POST/api/agentsCreate agent. Body: agent config (id, name, model, skills?, tools?, personality?, schedule?, etc.).
PUT/api/agents/:idUpdate agent. Body: partial fields (name, model, skills, tools, schedule, schedule_input, schedule_enabled, avatar, limits, etc.).
DELETE/api/agents/:idDelete agent.
POST/api/agents/suggestSuggest agent config (e.g. from description).
POST/api/agents/install-systemInstall system agents from seed dir. Returns { ok: true, installed }.
POST/api/agents/runRun agent. Body: { agent_id, task, conversation_id? }. Returns { success, output?, error? }.
POST/api/agents/run/streamRun agent with streaming. Body: { agent_id, task, conversation_id?, attachment_paths? }. SSE events: assistant, tool_call, done, error.
POST/api/agents/:id/uploadUpload file to agent (e.g. avatar or workspace).
GET/api/agents/:id/workspace/:filenameRead file from agent workspace.
PUT/api/agents/:id/workspace/:filenameWrite file to agent workspace.

Tasks & logs

MethodPathDescription
GET/api/tasksList tasks. Query: agent_id, graph_id, status, limit.
POST/api/tasksCreate task (enqueue). Body: task payload.
GET/api/tasks?id=...Get single task by id.
GET/api/logsList recent logs (query: limit).

Graphs

MethodPathDescription
GET/api/graphsList graphs.
GET/api/graphs/:idGet graph by id.
PUT/api/graphs/:idCreate or update graph. Body: nodes, edges, schedule?, schedule_input?, schedule_enabled?.
POST/api/graphs/runRun graph. Body: graph id and input.
POST/api/graphs/run/streamRun graph with streaming.

Memory

MethodPathDescription
POST/api/memory/writeWrite a memory entry. Body: agent_id, user_id?, content, metadata?.
GET/api/memory/searchSearch memories. Query: agent_id, user_id?, q, semantic?, limit?.
DELETE/api/memory/:idDelete memory by id.

Conversations

MethodPathDescription
GET/api/conversationsList conversations (query: limit, agent_id?, etc.).
POST/api/conversationsCreate conversation.
PUT/api/conversations/:idUpdate conversation (e.g. append messages).
POST/api/conversations/summarizeSummarize a conversation.

Settings

MethodPathDescription
GET/api/settingsGet settings (API keys, channel config, etc.; values may be redacted).
PUT/api/settingsUpdate settings (write to ~/.agent-os/config.json).

Skills

MethodPathDescription
GET/api/skillsList installed skills.
GET/api/skills/marketplaceGet marketplace / curated skill list.
GET/api/skills/store-registryGet store registry (if configured). Returns skills, storeBase, registryUrl.
GET/api/skills/:id/config/schemaGet config schema for a skill.
GET/api/skills/:id/setupGet setup markdown for a skill.
GET/api/skills/:id/configGet current skill config (configured keys).
PUT/api/skills/:id/configUpdate skill config (key/value).
POST/api/skills/installInstall skill (e.g. from store by slug or URL). Body: slug or url.
POST/api/skills/install-systemInstall system skills from seed dir.
POST/api/skills/uploadUpload skill (zip).
POST/api/skills/upload-skill-mdUpload skill Markdown.
DELETE/api/skills/:idUninstall skill.

Channels (webhooks)

MethodPathDescription
POST/api/channels/telegram/webhookTelegram bot webhook.
GET/api/channels/telegram/statusTelegram channel status.
POST/api/channels/telegram/set-webhookSet Telegram webhook URL.
POST/api/channels/slack/webhookSlack Events API / slash webhook.
GET/api/channels/slack/statusSlack channel status.
POST/api/channels/discord/webhookDiscord interactions webhook.
GET/api/channels/discord/statusDiscord channel status.
POST/api/channels/signal/webhookSignal bridge webhook.
GET/api/channels/signal/statusSignal channel status.
POST/api/channels/viber/webhookViber bot webhook.
GET/api/channels/viber/statusViber channel status.
POST/api/channels/viber/set-webhookSet Viber webhook.

Docs

MethodPathDescription
GET/api/docs/:nameGet built-in doc by name (e.g. specs).

WebSocket

  • Path: GET /api/events (upgrade to WebSocket).
  • Events: Server pushes runtime events (e.g. task.created, agent.started, tool.called, agent.completed, task.failed). Clients can use this for live logs and task updates.

CORS

The server sends CORS headers on responses. OPTIONS requests return 204 with CORS headers.

Security

How secrets, tokens, and access are handled in Sulala Agent OS.

Agent Configuration

Config file and environment variables for Sulala Agent OS — server, AI, channels, and paths.