Remote API Reference

DotAgents exposes a Fastify HTTP API for the mobile app, operator dashboards, local automation, and OpenAI-compatible clients. The server is disabled by default; enable it in Settings > Remote Server.

---

Base URL and Auth

Local default:

http://127.0.0.1:3210

Every protected endpoint expects:

Authorization: Bearer <remote-server-api-key>

Use 127.0.0.1 for local clients. Use a LAN IP, hostname, or Cloudflare Tunnel URL only when you intentionally expose the server.

OpenAI-Compatible Chat

POST /v1/chat/completions

Runs an agent through an OpenAI-compatible chat completions shape. Supports streaming and non-streaming responses.

{
  "model": "agent:general-assistant",
  "messages": [
    {"role": "user", "content": "Search recent AI news and summarize the important bits."}
  ],
  "stream": true
}

Notes:

• Use the desktop-configured model or an agent/model alias exposed by /v1/models.
• Tool use, MCP calls, skills, knowledge notes, and loop context are handled by the desktop runtime.
• Streaming responses use server-sent events compatible with OpenAI-style clients.

GET /v1/models

Lists model and agent aliases that the remote client can use.

GET /v1/models/:providerId

Lists known models for one provider profile when the desktop runtime can resolve them.

Agent and Content Management

Endpoint	Purpose
GET /v1/agent-profiles	List configured agent profiles.
GET /v1/agent-profiles/:id	Fetch one agent profile.
POST /v1/agent-profiles	Create an agent profile.
PATCH /v1/agent-profiles/:id	Update an agent profile.
DELETE /v1/agent-profiles/:id	Delete an agent profile.
POST /v1/agent-profiles/:id/toggle	Enable or disable an agent profile.
GET /v1/skills	List skills available to agents.
POST /v1/skills/:id/toggle-profile	Enable or disable a skill for a profile.
GET /v1/knowledge/notes	List knowledge notes.
GET /v1/knowledge/notes/:id	Fetch one knowledge note.
POST /v1/knowledge/notes	Create a knowledge note.
PATCH /v1/knowledge/notes/:id	Update a knowledge note.
DELETE /v1/knowledge/notes/:id	Delete a knowledge note.
GET /v1/loops	List scheduled/autonomous loops.
POST /v1/loops	Create a loop.
PATCH /v1/loops/:id	Update a loop.
DELETE /v1/loops/:id	Delete a loop.
POST /v1/loops/:id/toggle	Enable or disable a loop.
POST /v1/loops/:id/run	Run a loop immediately.

Conversations and Push

Endpoint	Purpose
GET /v1/conversations	List conversations.
POST /v1/conversations	Create a conversation.
GET /v1/conversations/:id	Fetch a conversation and messages.
PUT /v1/conversations/:id	Update conversation metadata/messages.
GET /v1/conversations/:id/assets/videos/:fileName	Stream a video attachment that belongs to a conversation.
POST /v1/emergency-stop	Stop the active remote run.
POST /v1/push/register	Register a push notification token.
POST /v1/push/unregister	Remove a push notification token.
GET /v1/push/status	Read push notification status.
POST /v1/push/clear-badge	Clear the mobile badge count.

Speech and Media

Endpoint	Purpose
POST /v1/tts/speak	Generate speech audio with the desktop-configured TTS provider.
GET /v1/conversations/:id/assets/videos/:fileName	Stream conversation-local video assets for mobile clients.

MCP and Settings

Endpoint	Purpose
GET /v1/mcp/servers	List configured MCP servers and connection status.
POST /v1/mcp/servers/:name/toggle	Enable or disable an MCP server.
GET /v1/settings	Read non-secret app settings for remote clients.
PATCH /v1/settings	Update remote-safe settings.
GET /v1/profiles	List provider/model profiles for mobile settings.
GET /v1/profiles/current	Read the active provider/model profile.
POST /v1/profiles/current	Switch the active provider/model profile.
GET /v1/profiles/:id/export	Export a provider/model profile.
POST /v1/profiles/import	Import a provider/model profile.

ACP-Injected MCP Transport

These endpoints are active runtime endpoints used by ACP/acpx delegation and injected runtime tools. They are not the normal user-facing MCP configuration API above.

Endpoint	Purpose
POST /mcp/:acpSessionToken	Initialize or send a Streamable HTTP MCP request scoped to an ACP session token.
GET /mcp/:acpSessionToken	Open the Streamable HTTP server-to-client stream for an ACP session token.
DELETE /mcp/:acpSessionToken	Close the injected MCP transport for an ACP session token.
POST /mcp/tools/list	List injected runtime tools for the current request context.
POST /mcp/:acpSessionToken/tools/list	List injected runtime tools scoped to an ACP session token.
POST /mcp/tools/call	Call an injected runtime tool in the current request context.
POST /mcp/:acpSessionToken/tools/call	Call an injected runtime tool scoped to an ACP session token.

Operator Endpoints

Operator endpoints are intended for trusted dashboards and automations.

Endpoint	Purpose
GET /v1/operator/status	Operator status summary.
GET /v1/operator/health	Health and build/runtime metadata.
GET /v1/operator/errors	Recent error events.
GET /v1/operator/logs	Recent operator log events.
GET /v1/operator/audit	Audit events.
GET /v1/operator/conversations	Operator conversation list.
GET /v1/operator/remote-server	Remote server status/config snapshot.
GET /v1/operator/tunnel	Cloudflare Tunnel status.
GET /v1/operator/tunnel/setup	Tunnel setup instructions/status.
POST /v1/operator/tunnel/start	Start tunnel exposure.
POST /v1/operator/tunnel/stop	Stop tunnel exposure.
GET /v1/operator/integrations	Integration status summary.
GET /v1/operator/whatsapp	WhatsApp MCP/operator status.
POST /v1/operator/whatsapp/connect	Connect/start WhatsApp integration.
POST /v1/operator/whatsapp/logout	Log out WhatsApp integration.
GET /v1/operator/discord	Discord integration status.
GET /v1/operator/discord/logs	Discord logs.
POST /v1/operator/discord/connect	Connect Discord integration.
POST /v1/operator/discord/disconnect	Disconnect Discord integration.
POST /v1/operator/discord/logs/clear	Clear Discord logs.
GET /v1/operator/updater	Updater status.
POST /v1/operator/updater/check	Trigger update check.
POST /v1/operator/updater/download-latest	Download the latest update artifact.
POST /v1/operator/updater/reveal-download	Reveal the downloaded update in Finder/Explorer.
POST /v1/operator/updater/open-download	Open the downloaded update.
POST /v1/operator/updater/open-releases	Open the GitHub releases page.
GET /v1/operator/mcp	Operator MCP status.
POST /v1/operator/actions/mcp-restart	Restart MCP services.
POST /v1/operator/actions/restart-remote-server	Restart the remote server.
POST /v1/operator/actions/restart-app	Restart the desktop app.
POST /v1/operator/actions/run-agent	Run an agent from the operator surface.
POST /v1/operator/access/rotate-api-key	Rotate the remote API key.

Pairing Mobile

1. Enable Settings > Remote Server in desktop.
2. Show the QR code in desktop remote server settings.
3. In mobile, open Connection Settings and scan it.
4. Mobile stores the base URL and bearer token in device storage.

See Remote Server & Mobile Pairing for setup and security guidance.

Compatibility Notes

• Legacy endpoints like /chat, /conversations, and /mcp/execute are no longer the documented surface. Use /v1/* endpoints.
• The /mcp/:acpSessionToken endpoints above are current internal ACP/acpx runtime transport endpoints, not legacy /mcp/execute endpoints.
• The API is local-first. Do not expose it without an API key, CORS review, and tunnel/firewall controls.
• Provider model catalogs change frequently; use /v1/models or provider APIs for exact availability.

---

Next Steps

• Mobile App — Mobile client that uses this API
• Remote Server & Pairing — Setup, QR pairing, and tunnel guidance
• Settings Reference — Configuration options