Bỏ qua để đến nội dung
MZPanel MZPanel
Control plane API Overview of the /v1 REST surface, the agent WebSocket protocol, auth, the Envelope + error shape, and the route groups.
CtrlK

Control plane API

Nội dung này hiện chưa có sẵn bằng ngôn ngữ của bạn.

The MZPanel control plane exposes a REST API (used by the dashboard) and a WebSocket protocol (used by the on-VPS agent), both served from api.mzpanel.com. This page is an orientation to that surface — auth, the shared message shape, and the route groups — not an exhaustive endpoint list.

Auth

Section titled “Auth”

There are two callers, each with its own credential — the same split described in the Security model:

CallerCredential
Dashboard → APIA session cookie (httpOnly, SameSite=Strict, Secure), set at sign-in. CSRF-protected; the agent routes are exempt because they don’t use the cookie.
Agent → API (WS)A long-lived agent token (Authorization: Bearer …), obtained at registration by exchanging a one-time install token (1h TTL). Rotates when the license changes.

Programmatic API keys (scoped, for automation) are a separate credential on the Max plan — see the caveat in Gotchas.

REST (/v1)

Section titled “REST (/v1)”

REST endpoints live under /v1 and are grouped by resource. Inputs are validated with Zod on every route, and any operation that changes a VPS is dispatched as a job: the API queues it, relays it to the target agent over the WebSocket, and streams the result back — the API never touches the box directly.

The main route groups, and the doc page each one drives:

GroupPurposeSee
/v1/servers, /v1/jobsRegister/list servers; dispatch commands to an agentServers
/v1/servers/.../sites, /v1/wpSite CRUD + WordPress content, run through jobsSites
/v1/backupsBackup jobs, snapshots, restoreBackups
/v1/billingSubscription, wallet, invoicesBilling
/v1/team, /v1/orgsMembers, invites, RBACTeam
/v1/accountProfile, preferences, securityAccount
/v1/dns, /v1/domainsDNS providers, records, domain registryDNS & TLS
/v1/uptime, /v1/alerts, /v1/notifyUptime probes, alert rules, channelsUptime
/v1/agent/*Agent-facing (register, binary, WS upgrade) — bearer auth, no cookieThe agent

Agent WebSocket protocol

Section titled “Agent WebSocket protocol”

The agent dials outbound to wss://ws.mzpanel.com/v1/agent and holds one persistent connection — the VPS opens no inbound ports. Messages are JSON envelopes with a shared base shape (type and payload vary per message):

type Envelope = {
  v: 1;            // protocol version
  id: string;      // message UUID
  ts: number;      // unix ms
  type: string;    // discriminator: hello, welcome, heartbeat, cmd, log, job_done, event, …
  ref?: string;    // optional reference to another message's id
  payload: unknown;
};

The flow, briefly:

  1. Agent connects and sends hello (agent version, hostname, OS, sealed-credential public key); the API replies welcome with a signed license envelope.
  2. Agent sends a heartbeat every 30s with a metrics snapshot (CPU, RAM, disk, network, load, process count) and pushes inventory for cached read-model state.
  3. The API sends cmd envelopes; the agent runs them natively and streams log lines, ending with job_done (exit code + duration). cmd.cancel aborts a run.
  4. The agent pushes event envelopes for out-of-band happenings (backup done, SSL renewed, service down).

The protocol also carries interactive channels — pty.* for the web terminal, ai.* for the on-box AI session, and fs.*/xfer.* for the file manager and cross-server transfers. See Architecture for the full connection model.

Error shape

Section titled “Error shape”

API errors use a consistent envelope — never a raw stack trace:

{ "error": { "code": "string", "message": "human readable", "details": {} } }

details is optional and present only when extra context helps (e.g. validation failures). Clients should switch on error.code (stable), not on message (may change). Common codes include unauthorized, forbidden, and rate_limited (the last also returns a Retry-After header).

For AI agents & MCP

Section titled “For AI agents & MCP”

MZPanel also exposes a Model Context Protocol endpoint at /v1/mcp (JSON-RPC 2.0 over POST) that surfaces the same read tools and docs resources the in-panel assistant uses. It’s session-gated today (your browser or a local proxy drives it); action tools return a confirmation card rather than mutating silently. If you’re an LLM reading these docs, start at For AI agents for the llms.txt conventions.

Gotchas & troubleshooting

Section titled “Gotchas & troubleshooting”
  • Scoped API keys are a preview. The Developer page lets you design API keys and webhook endpoints, but that backend is not yet wired — keys created there live only in the browser session and do not authenticate real requests. Today the callable surface is: the dashboard (session cookie) and the agent WS (agent token). Treat standalone key-based access as planned, not live.
  • CORS is locked to the dashboard. /v1/* echoes back only the dashboard and admin origins with credentials: include; other origins are rejected. The unauthenticated /v1/public/* read-model (status pages) is the only exception.
  • Agent routes bypass the cookie. /v1/agent/* is CSRF-exempt and bearer-authed on purpose — a browser session can’t call them, and an agent token can’t call the cookie-authed routes.
  • This page tracks reality. When an endpoint here disagrees with the Developer page’s mock UI, this page is the source of truth for what’s actually callable.
Section titled “Related”