Skip to content
mycellm_

API Overview

mycellm exposes an OpenAI-compatible REST API on port 8420. Any tool that works with the OpenAI API works with mycellm.

Base URL

Section titled “Base URL”
http://localhost:8420/v1

Authentication

Section titled “Authentication”

When MYCELLM_API_KEY is set, all /v1/* endpoints require authentication:

Authorization: Bearer <your-api-key>

Public endpoints (/health, /metrics, /v1/public/*) never require auth.

Node platforms

Section titled “Node platforms”

The routes below are served by the Python node (Linux, macOS, Docker). The iOS & iPadOS app serves the same paths and payload shapes for everything a leaf node does — inference, status, activity, logs, metrics, model management, credits and relays — so fleet tooling doesn’t branch on platform. It does not serve the coordinator surfaces (/v1/admin/**, /v1/public/**), federation or settings writes; see the iOS API surface for the full list.

Endpoints

Section titled “Endpoints”

Inference

Section titled “Inference”
MethodPathAuthDescription
POST/v1/chat/completionsYesChat completions (streaming supported)
GET/v1/modelsYesList available models
GET/v1/models/{id}YesRetrieve one model (404 if unknown)
POST/v1/embeddingsYesText embeddings

Public (no auth)

Section titled “Public (no auth)”
MethodPathDescription
POST/v1/public/chat/completionsRate-limited public chat (5K tokens/day)
GET/v1/node/public/statsNetwork stats

Node Management

Section titled “Node Management”
MethodPathDescription
GET/v1/node/statusNode status
GET/v1/node/systemHardware info
GET/v1/node/creditsCredit balance
POST/v1/node/models/loadLoad a model
POST/v1/node/models/unloadUnload a model
POST/v1/node/models/downloadInstall a model — Hugging Face, URL, or manifest
GET/v1/node/models/downloadsIn-flight downloads and their progress
POST/v1/node/models/downloads/abortAbort a download by download_id
GET/v1/node/peersConnected peers
GET/v1/node/connectionsActive connections
GET/v1/node/activityRecent events + rolling stats (/stream for SSE)
GET/v1/node/logsRecent log lines (/stream for SSE)
GET/v1/node/fleet/hardwareFleet aggregate stats

Execution fabric (0.8)

Section titled “Execution fabric (0.8)”
MethodPathDescription
POST/v1/chat/completions with model: "mycellm/swarm"Fan out to N models, then synthesise
POST/v1/node/planExplain how a request would execute — runs nothing
GET/v1/node/groupsServing groups and their deployments
GET/v1/node/relayRelay backends behind those groups
POST/v1/node/relay/addAttach an OpenAI-compatible gateway
POST/v1/node/relay/removeDetach one
POST/v1/node/relay/refreshRe-discover models from all relays

Monitoring

Section titled “Monitoring”
MethodPathAuthDescription
GET/healthNoHealth check + version
GET/metricsNoPrometheus metrics
GET/v1/node/versionYesVersion + update check

Admin (Bootstrap nodes)

Section titled “Admin (Bootstrap nodes)”
MethodPathDescription
POST/v1/admin/nodes/announceNode announcement
GET/v1/admin/nodesList fleet nodes
POST/v1/admin/nodes/{id}/approveApprove pending node
GET/v1/admin/fleet/peersPeers reachable for fleet commands
POST/v1/admin/fleet/commandRelay a command to a peer — the key is verified on the target, never stored here

Interactive docs

Section titled “Interactive docs”

Every running node serves OpenAPI docs at:

http://localhost:8420/docs