API Reference

Magec exposes two HTTP servers on separate ports. Each one has its own interactive Swagger UI where you can explore every endpoint, see request/response schemas, and test things directly from the browser.

User API — Port 8080 #

This is the API that clients use to interact with agents. The Voice UI, Telegram, webhooks, and any custom integration goes through here.

Swagger UI → http://localhost:8080/swagger/

Authentication #

All endpoints require a client token: Authorization: Bearer mgc_...

The token comes from the client configuration in the Admin UI. Each client has its own token, which determines what agents and flows it can access.

When no clients exist (fresh install without a seed), the API runs in open mode with no authentication required. Authentication is enforced as soon as you create your first client.

Agent endpoints (ADK) #

All routes under /api/v1/agent/* implement the Google Agent Development Kit (ADK) protocol exposed as a REST API. This includes:

  • Execution — Send messages to agents (blocking or SSE streaming)
  • Sessions — Create, list, get, update, and delete conversation sessions
  • Artifacts — Retrieve files and structured data generated by agents, with version history
  • Debug — Execution traces and interaction graphs

The request format for sending a message:

{
  "app_name": "AGENT_OR_FLOW_ID",
  "user_id": "user1",
  "session_id": "session1",
  "new_message": {
    "role": "user",
    "parts": [{ "text": "Hello!" }]
  }
}

Other endpoints #

Beyond ADK, the User API also serves:

  • Voice — STT and TTS proxies per agent, plus a WebSocket for real-time wake word and VAD events. See Voice System.
  • Webhooks — Trigger endpoint for webhook clients. See Webhooks.
  • Client info — Pairing info, allowed agents and flows, response agent markers.
  • Health — Simple health check at /api/v1/health.

The Swagger UI documents all of these with full schemas and lets you try them interactively.

Admin API — Port 8081 #

This is the management API that powers the Admin UI. Full CRUD for every resource in the platform: agents, backends, memory providers, MCP servers, clients, commands, flows, settings, and conversations.

Swagger UI → http://localhost:8081/swagger/

No authentication required. In production, restrict access to this port (bind to localhost, firewall, or VPN).

Every resource follows the same REST pattern (GET, POST, PUT, DELETE), plus type-specific extras like health checks for memory providers, token regeneration for clients, and MCP server linking for agents.

It also includes backup and restore endpoints — download a full .tar.gz snapshot of all data, or upload one to atomically replace everything. The Swagger UI has it all.

Both Swagger UIs are fully interactive — you can execute requests directly from the browser without writing any code. This is the best way to explore the API.