API Overview

Moxxy provides a REST API for programmatic access to all agent functionality.

Base URL

http://127.0.0.1:17890

Configure via:

moxxy run --agent default --prompt "Store '18900' in vault as gateway_port"

Authentication

Internal Token

For internal API access:

export MOXXY_INTERNAL_TOKEN="your-token"

Include in requests:

curl -H "X-Moxxy-Internal-Token: your-token" http://localhost:17890/api/agents

No Authentication

For local development, the API is accessible without authentication by default.

Response Format

Success

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent 'unknown' not found"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Error

Rate Limiting

Default limits:

Endpoint Type	Limit
Chat	10/second
Read	100/second
Write	50/second

API Endpoints Overview

Agents

Method	Endpoint	Description
GET	/api/agents	List all agents
GET	/api/agents/:name	Get agent info
POST	/api/agents	Create agent
DELETE	/api/agents/:name	Delete agent

Chat

Method	Endpoint	Description
POST	/api/agents/:name/chat	Send message
GET	/api/agents/:name/chat/stream	Stream messages

Memory

Method	Endpoint	Description
GET	/api/agents/:name/memory	Get memory
POST	/api/agents/:name/memory	Add memory
DELETE	/api/agents/:name/memory	Clear memory

Skills

Method	Endpoint	Description
GET	/api/agents/:name/skills	List skills
POST	/api/agents/:name/skills/:skill/invoke	Invoke skill

Vault

Method	Endpoint	Description
GET	/api/agents/:name/vault	List secrets
GET	/api/agents/:name/vault/:key	Get secret
POST	/api/agents/:name/vault	Store secret
DELETE	/api/agents/:name/vault/:key	Delete secret

Channels

Method	Endpoint	Description
GET	/api/agents/:name/channels	List channels
POST	/api/agents/:name/channels	Configure channel

Webhooks

Method	Endpoint	Description
GET	/api/webhooks	List webhooks
POST	/api/webhooks	Create webhook
POST	/api/webhooks/:name/trigger	Trigger webhook

Streaming

Use Server-Sent Events (SSE) for streaming responses:

const eventSource = new EventSource('/api/agents/default/chat/stream?message=Hello');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.done) {
    eventSource.close();
  } else {
    console.log(data.content);
  }
};

OpenAPI Specification

Full OpenAPI spec available at:

GET /api/openapi.json

Client Libraries

JavaScript/TypeScript

const response = await fetch('http://localhost:17890/api/agents/default/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hello!' })
});
const data = await response.json();

Python

import requests

response = requests.post(
    'http://localhost:17890/api/agents/default/chat',
    json={'message': 'Hello!'}
)
data = response.json()

cURL

curl -X POST http://localhost:17890/api/agents/default/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}'