# API Reference

## `Express Template API Reference`

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

### `Health Check`

#### <kbd>GET /health</kbd>

Check if the server and agent are running properly.

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

### `Agent Endpoints`

#### <kbd>GET /agent/info</kbd>

Get detailed information about the current agent.

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

#### <kbd>GET /agent/skills</kbd>

Get a categorized list of the agent's skills.

```javascript
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": "..."
//         }
//     ]
// }
```

#### <kbd>GET /agents</kbd>

List all available agents.

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

#### <kbd>POST /agent/switch</kbd>

Switch to a different agent.

```javascript
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`

#### <kbd>POST /chat</kbd>

Send a message to the agent.

```javascript
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": [...]
// }
```

#### <kbd>GET /chat/history</kbd>

Get the conversation history.

```javascript
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..."
//     }
// ]
```

#### <kbd>POST /chat/clear</kbd>

Clear the conversation history.

```javascript
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:

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

Example error when rate limit is exceeded:

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

Example error when no agent is selected:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gaming.skillfulai.io/web-sdk/templates/express-server-template/api-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.