REST

REST API

The Naomi server exposes a REST API for managing agents and the network.

Base URL

http://localhost:3000/api

Agent Endpoints

List All Agents

GET /api/agents

Response:

{
  "agents": [
    {
      "id": "agent-1",
      "config": { ... },
      "network": { ... },
      "isActive": true,
      "lastActivity": 1234567890
    }
  ]
}

Get Agent by ID

GET /api/agents/:id

Response:

{
  "agent": {
    "id": "agent-1",
    "config": { ... },
    "network": { ... },
    "isActive": true,
    "lastActivity": 1234567890
  }
}

Create Agent

POST /api/agents
Content-Type: application/json

{
  "id": "agent-1",
  "name": "My Agent",
  "systemPrompt": "You are a helpful assistant.",
  "temperature": 0.7,
  "maxTokens": 1000
}

Response:

{
  "agent": {
    "id": "agent-1",
    "config": { ... },
    "network": { ... },
    "isActive": false,
    "lastActivity": 1234567890
  }
}

Update Agent

PUT /api/agents/:id
Content-Type: application/json

{
  "temperature": 0.5,
  "maxTokens": 2000
}

Delete Agent

DELETE /api/agents/:id

Response:

{
  "success": true
}

Process Message

POST /api/agents/:id/process
Content-Type: application/json

{
  "message": "Hello, how are you?",
  "metadata": {
    "source": "user",
    "timestamp": 1234567890
  }
}

Response:

{
  "response": {
    "content": "Hello! I'm doing well, thank you for asking.",
    "contextUpdates": [
      {
        "id": "msg_1234567890_abc123",
        "agentId": "agent-1",
        "content": "Hello, how are you?",
        "timestamp": 1234567890,
        "metadata": {
          "response": "Hello! I'm doing well...",
          "source": "user"
        },
        "contextType": "message"
      }
    ],
    "metadata": { ... }
  }
}

Share Knowledge

POST /api/agents/:id/knowledge
Content-Type: application/json

{
  "knowledge": "Bitcoin price is $50,000",
  "targetAgents": ["agent-2", "agent-3"],
  "metadata": {
    "source": "market-data",
    "timestamp": 1234567890
  }
}

Response:

{
  "success": true
}

Context Endpoints

Get Agent Context

GET /api/context/agent/:id?limit=50

Response:

{
  "context": [
    {
      "id": "msg_1234567890_abc123",
      "agentId": "agent-1",
      "content": "Hello",
      "timestamp": 1234567890,
      "metadata": { ... },
      "contextType": "message"
    }
  ]
}

Get Shared Context

POST /api/context/shared
Content-Type: application/json

{
  "agentIds": ["agent-1", "agent-2"],
  "limit": 100
}

Clear Agent Context

DELETE /api/context/agent/:id

Response:

{
  "success": true
}

Network Endpoints

Get Network Topology

GET /api/network/topology

Response:

{
  "topology": [
    {
      "agentId": "agent-1",
      "connections": ["agent-2", "agent-3"]
    },
    {
      "agentId": "agent-2",
      "connections": ["agent-1"]
    }
  ]
}

Connect Agents

POST /api/network/connect
Content-Type: application/json

{
  "agentId1": "agent-1",
  "agentId2": "agent-2"
}

Response:

{
  "success": true
}

Get Registered Agents

GET /api/network/agents

Response:

{
  "agents": ["agent-1", "agent-2", "agent-3"]
}

WebSocket Events

The server also supports WebSocket connections for real-time updates.

Connection

const ws = new WebSocket('ws://localhost:3000');

ws.on('open', () => {
  console.log('Connected to Naomi server');
});

Events

• agent:created - New agent created

• agent:processed - Agent processed a message

• agent:connected - Agents connected

• context:shared - Context shared between agents

• context:created - New context message created