Express Template API Reference

Complete reference for all endpoints available in the Skillful Express Server template.

Health Check

GET /health

Check if the server and agent are running properly.

const response = await fetch('http://localhost:3000/health');
const data = await response.json();
// {
//     "status": "ok",
//     "agent": "Wojak"
// }

Agent Endpoints

GET /agent/info

Get detailed information about the current agent.

const response = await fetch('http://localhost:3000/agent/info');
const data = await response.json();
// {
//     "name": "Wojak",
//     "description": "The Web3 King",
//     "config": {
//         "llm": { ... },
//         "skills": [ ... ]
//     }
// }

GET /agent/skills

Get a categorized list of the agent's skills.

const response = await fetch('http://localhost:3000/agent/skills');
const data = await response.json();
// {
//     "Finance": [
//         {
//             "name": "get_stock_price",
//             "friendlyName": "Get Stock Price",
//             "description": "..."
//         }
//     ],
//     "Weather": [
//         {
//             "name": "get_weather",
//             "friendlyName": "Get Weather",
//             "description": "..."
//         }
//     ]
// }

GET /agents

List all available agents.

const response = await fetch('http://localhost:3000/agents');
const data = await response.json();
// [
//     {
//         "name": "Wojak",
//         "description": "The Web3 King",
//         "type": "base"
//     }
// ]

POST /agent/switch

Switch to a different agent.

const response = await fetch('http://localhost:3000/agent/switch', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        agentName: "NewAgent"
    })
});
const data = await response.json();
// {
//     "status": "success",
//     "message": "Switched to agent: NewAgent",
//     "agent": {
//         "name": "NewAgent",
//         "description": "...",
//         "type": "base"
//     }
// }

Chat Endpoints

POST /chat

Send a message to the agent.

const response = await fetch('http://localhost:3000/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        message: "Hello! Who are you?"
    })
});
const data = await response.json();
// {
//     "text": "I am Wojak, the Web3 expert...",
//     "events": [...],
//     "tools": [...],
//     "sources": [...]
// }

GET /chat/history

Get the conversation history.

const response = await fetch('http://localhost:3000/chat/history');
const data = await response.json();
// [
//     {
//         "role": "user",
//         "content": "Hello! Who are you?"
//     },
//     {
//         "role": "assistant",
//         "content": "I am Wojak..."
//     }
// ]

POST /chat/clear

Clear the conversation history.

const response = await fetch('http://localhost:3000/chat/clear', {
    method: 'POST'
});
const data = await response.json();
// {
//     "status": "Conversation cleared"
// }

Response Status Codes

• 200: Successful request

• 400: Bad request (missing or invalid parameters)

• 429: Too many requests (rate limit exceeded)

• 500: Server error

Rate Limiting Headers

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1623456789

Error Responses

All error responses follow this format:

{
    "error": "Error type or description",
    "message": "Detailed error message"
}

Example error when rate limit is exceeded:

{
    "error": "Too many requests",
    "message": "Please try again in 15 minutes",
    "waitTime": "15 minutes"
}

Example error when no agent is selected:

{
    "error": "No active agent",
    "message": "Please select an agent using /agent/switch"
}