API Overview

Moxxy v4 exposes a REST API for managing agents, runs, memory, skills, vault secrets, channels, and more.

Base URL

http://127.0.0.1:3000

The port is configurable via the MOXXY_PORT environment variable.

All endpoints are prefixed with /v1/.

Authentication

Bearer Tokens

Moxxy uses Bearer tokens with a mox_ prefix. Tokens are SHA-256 hashed at rest.

curl -H "Authorization: Bearer mox_your_token_here" http://127.0.0.1:3000/v1/agents

Loopback Mode

By default, Moxxy runs in loopback mode, which bypasses authentication for requests originating from localhost (127.0.0.1 or ::1). This simplifies local development.

Bootstrap Flow

The very first token creation requires no authentication. This allows you to bootstrap the system:

# First token (no auth required)
curl -X POST http://127.0.0.1:3000/v1/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["*"]}'

Subsequent token creation requires a token with the tokens:admin scope.

Token Scopes

Scope	Description
agents:read	Read agent details and list agents
agents:write	Create, update, and delete agents
runs:write	Start runs, stop agents, reset sessions
vault:read	List vault secrets
vault:write	Create, delete secrets and grants
tokens:admin	Create and revoke API tokens
events:read	Subscribe to SSE event stream
channels:read	List channels
channels:write	Create, delete, and pair channels
*	Wildcard -- grants all scopes

Response Format

All responses return direct JSON (not wrapped in a {success, data} envelope). For example, listing agents returns an array directly:

[
  {
    "name": "researcher",
    "created_at": "2025-03-15T10:00:00Z"
  }
]

Errors

Errors return the appropriate HTTP status code with a JSON body:

{
  "error": "Agent 'unknown' not found"
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful deletion)
400	Bad Request
401	Unauthorized
403	Forbidden (insufficient scope)
404	Not Found
429	Too Many Requests
500	Internal Server Error

Rate Limiting

Rate limiting is configurable via RateLimitConfig (powered by tower-governor). The default configuration is permissive. The health check endpoint (/v1/health) is exempt from rate limiting.

SSE Event Stream

Moxxy provides a Server-Sent Events stream for real-time event monitoring:

GET /v1/events/stream

Filter events with query parameters:

Parameter	Description
agent_id	Filter by agent
run_id	Filter by run
event_type	Filter by event type

Events are delivered as EventEnvelope objects:

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-03-15T10:00:00Z",
  "agent_id": "researcher",
  "run_id": "run_abc123",
  "sequence": 1,
  "event_type": "run.started",
  "payload": {}
}

There are roughly 60 event types including run.started, run.completed, run.failed, message.user, message.assistant, model.request, model.response, skill.invoked, skill.completed, memory.stored, vault.accessed, heartbeat.fired, channel.message_received, and more.

API Endpoints Overview

Auth

Method	Endpoint	Description
POST	/v1/auth/tokens	Create API token
GET	/v1/auth/tokens	List tokens
DELETE	/v1/auth/tokens/{id}	Revoke token

Agents

Method	Endpoint	Description
POST	/v1/agents	Create agent
GET	/v1/agents	List agents
GET	/v1/agents/{name}	Get agent details
PATCH	/v1/agents/{name}	Update agent
DELETE	/v1/agents/{name}	Delete agent
POST	/v1/agents/{name}/runs	Start a run
POST	/v1/agents/{name}/stop	Stop running agent
POST	/v1/agents/{name}/reset	Reset session
GET	/v1/agents/{name}/history	Get conversation history
POST	/v1/agents/{name}/ask-responses/{question_id}	Answer agent question

Providers

Method	Endpoint	Description
GET	/v1/providers	List installed providers
POST	/v1/providers	Install provider
GET	/v1/providers/{id}/models	List models for provider

Memory

Method	Endpoint	Description
GET	/v1/agents/{id}/memory/search	Semantic + keyword search
POST	/v1/agents/{id}/memory/compact	Trigger memory compaction

Skills

Method	Endpoint	Description
GET	/v1/agents/{id}/skills	List skills
POST	/v1/agents/{id}/skills/install	Install skill
DELETE	/v1/agents/{id}/skills/{skill_id}	Delete skill

Heartbeats

Method	Endpoint	Description
POST	/v1/agents/{id}/heartbeats	Create scheduled heartbeat
GET	/v1/agents/{id}/heartbeats	List heartbeats
DELETE	/v1/agents/{id}/heartbeats/{hb_id}	Disable heartbeat

Vault

Method	Endpoint	Description
POST	/v1/vault/secrets	Create secret reference
GET	/v1/vault/secrets	List secret references
DELETE	/v1/vault/secrets/{id}	Delete secret
POST	/v1/vault/grants	Grant agent access to secret

Templates

Method	Endpoint	Description
POST	/v1/templates	Create template
GET	/v1/templates	List templates
GET	/v1/templates/{slug}	Get template

Webhooks

Method	Endpoint	Description
POST	/v1/hooks/{token}	Receive inbound webhook (HMAC verified, no auth)
GET	/v1/agents/{name}/webhooks	List agent webhooks
DELETE	/v1/agents/{name}/webhooks/{slug}	Delete webhook

Channels

Method	Endpoint	Description
POST	/v1/channels	Create channel
GET	/v1/channels	List channels
POST	/v1/channels/pair	Pair chat to agent
DELETE	/v1/channels/{id}	Delete channel

MCP

Method	Endpoint	Description
GET	/v1/agents/{id}/mcp	List MCP servers
POST	/v1/agents/{id}/mcp	Add MCP server
DELETE	/v1/agents/{id}/mcp/{id}	Remove MCP server

Events & Health

Method	Endpoint	Description
GET	/v1/events/stream	SSE event stream
GET	/v1/audit	Query audit log
GET	/v1/health	Health check

Client Examples

cURL

curl http://127.0.0.1:3000/v1/agents \
  -H "Authorization: Bearer mox_your_token_here"

JavaScript/TypeScript

const response = await fetch('http://127.0.0.1:3000/v1/agents', {
  headers: { 'Authorization': 'Bearer mox_your_token_here' }
});
const agents = await response.json();

Python

import requests

response = requests.get(
    'http://127.0.0.1:3000/v1/agents',
    headers={'Authorization': 'Bearer mox_your_token_here'}
)
agents = response.json()