REST API Reference

Maestro exposes a REST API for programmatic access. Default port: 3000.

Base URL

http://localhost:3000

Authentication

The API has no built-in authentication. For production, add authentication middleware or use a reverse proxy.

---

Endpoints

POST /chat

Send a message and receive a response.

Request Body

{
  "message": "Hello, how are you?",
  "sessionId": "user-123",
  "stream": true
}

Field	Type	Required	Description
message	string	Yes	User message
sessionId	string	Yes	Session identifier
stream	boolean	No	Enable SSE streaming (default: true)

Streaming Response (SSE)

event: message
data: {"type":"text","content":"Hello"}

event: message
data: {"type":"text","content":"! How"}

event: message
data: {"type":"text","content":" can I help?"}

event: done
data: {}

Non-Streaming Response

{
  "response": "Hello! How can I help you today?",
  "sessionId": "user-123",
  "usage": {
    "inputTokens": 150,
    "outputTokens": 25
  }
}

Example

# Streaming
curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "sessionId": "user-123"}'

# Non-streaming
curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "sessionId": "user-123", "stream": false}'

---

GET /chat/:sessionId

Get conversation history for a session.

Parameters

Parameter	Type	Description
sessionId	string	Session identifier

Response

{
  "sessionId": "user-123",
  "messages": [
    {
      "role": "user",
      "content": "Hello",
      "timestamp": "2025-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Hello! How can I help you?",
      "timestamp": "2025-01-15T10:30:01Z"
    }
  ]
}

Example

curl http://localhost:3000/chat/user-123

---

GET /agents

List all available agents.

Response

{
  "agents": [
    {
      "name": "orchestrator",
      "description": "Routes requests to specialized agents",
      "type": "static"
    },
    {
      "name": "personal-assistant",
      "description": "General-purpose assistant",
      "type": "static"
    },
    {
      "name": "research-helper",
      "description": "Helps with research tasks",
      "type": "dynamic"
    }
  ]
}

Example

curl http://localhost:3000/agents

---

GET /health

Health check endpoint.

Response

{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00Z"
}

Example

curl http://localhost:3000/health

---

Error Responses

Errors return appropriate HTTP status codes:

{
  "error": "Session not found",
  "code": "SESSION_NOT_FOUND"
}

Status	Meaning
400	Bad request (invalid input)
404	Resource not found
429	Rate limited or budget exceeded
500	Internal server error

---

Streaming Events

When stream: true, the response is Server-Sent Events (SSE):

Event	Data	Description
message	{"type":"text","content":"..."}	Text chunk
tool_call	{"type":"tool_call","name":"..."}	Tool invocation
tool_result	{"type":"tool_result","result":"..."}	Tool result
done	{}	Stream complete
error	{"error":"..."}	Error occurred

JavaScript Example

const eventSource = new EventSource('/chat?sessionId=user-123');

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

eventSource.addEventListener('done', () => {
  eventSource.close();
});

---

Rate Limiting

Note

The API doesn’t implement rate limiting by default. For production, add rate limiting at the reverse proxy level or implement middleware.

CORS

CORS is enabled for all origins by default. Configure in production for security.