Skip to main content

​
Overview

The HTTP API adapter allows applications to interact with NapCat by sending HTTP requests. It supports both standard HTTP endpoints and WebSocket connections over the same port.

​
Configuration

Configure the HTTP server in your OneBot config: 
{
  "network": {
    "httpServers": [
      {
        "name": "http-server",
        "enable": true,
        "port": 3000,
        "host": "127.0.0.1",
        "enableCors": true,
        "enableWebsocket": false,
        "messagePostFormat": "array",
        "token": "your_secret_token",
        "debug": false
      }
    ]
  }
}

​
Configuration Options

OptionTypeDefaultDescription
enablebooleanfalseEnable the HTTP server
portnumber3000Port to listen on
hoststring127.0.0.1Host address to bind
enableCorsbooleantrueEnable CORS for cross-origin requests
enableWebsocketbooleanfalseEnable WebSocket on the same port
messagePostFormatstringarrayMessage format (array or string)
tokenstring""Access token for authentication
debugbooleanfalseEnable debug logging

​
Making Requests

​
Basic Request

Make API calls by sending HTTP requests to http://host:port/action_name: 
curl -X POST http://127.0.0.1:3000/send_private_msg \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345678,
    "message": "Hello from NapCat!"
  }'

​
GET Requests

You can also use GET requests with query parameters: 
curl "http://127.0.0.1:3000/get_login_info"

​
Authentication

NapCat supports two authentication methods: 
curl -X POST http://127.0.0.1:3000/send_private_msg \
  -H "Authorization: Bearer your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 12345678, "message": "Hello!"}'

​
2. Query Parameter

curl -X POST "http://127.0.0.1:3000/send_private_msg?access_token=your_secret_token" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 12345678, "message": "Hello!"}'

​
Response Format

All API responses follow the OneBot 11 standard format:

​
Success Response

{
  "status": "ok",
  "retcode": 0,
  "data": {
    "message_id": 123456
  },
  "echo": "optional_echo_value"
}

​
Error Response

{
  "status": "failed",
  "retcode": 1404,
  "message": "不支持的API send_invalid_action",
  "wording": "不支持的API send_invalid_action",
  "echo": "optional_echo_value"
}

​
Common Status Codes

HTTP CodeRetcodeDescription
2000Success
2001400Invalid JSON format
2001403Token verification failed
2001404API action not found
403-Authentication failed

​
WebSocket on HTTP Port

When enableWebsocket is enabled, you can connect to WebSocket on the same port: 
// Event WebSocket (receives events)
const ws = new WebSocket('ws://127.0.0.1:3000/?access_token=your_secret_token');

// API WebSocket (for API calls)
const apiWs = new WebSocket('ws://127.0.0.1:3000/api?access_token=your_secret_token');
See the WebSocket documentation for more details.

​
Echo Parameter

Include an echo field in your request to track responses: 
curl -X POST http://127.0.0.1:3000/send_private_msg \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 12345678,
    "message": "Hello!",
    "echo": "request-123"
  }'
The response will include the same echo value: 
{
  "status": "ok",
  "retcode": 0,
  "data": {...},
  "echo": "request-123"
}

​
Request Body Format

NapCat accepts:
  • Standard JSON (application/json)
  • URL-encoded form data (application/x-www-form-urlencoded)
  • JSON5 format (relaxed JSON syntax)
  • Requests without Content-Type header (auto-detected as JSON)

​
Multiple HTTP Servers

You can run multiple HTTP servers on different ports: 
{
  "network": {
    "httpServers": [
      {
        "name": "public-api",
        "enable": true,
        "port": 3000,
        "host": "0.0.0.0",
        "token": "public_token"
      },
      {
        "name": "internal-api",
        "enable": true,
        "port": 3001,
        "host": "127.0.0.1",
        "token": "internal_token"
      }
    ]
  }
}

​
Implementation Details

The HTTP adapter is implemented in packages/napcat-onebot/network/http-server.ts and uses:
  • Express.js for HTTP routing
  • CORS support for cross-origin requests
  • Support for request bodies up to 5000MB
  • Automatic JSON5 parsing for flexible syntax

​
Best Practices

  1. Always use authentication - Set a strong token in production
  2. Use HTTPS in production - Place NapCat behind a reverse proxy with SSL
  3. Bind to localhost - Use 127.0.0.1 unless you need external access
  4. Enable CORS carefully - Only enable if you need browser access
  5. Monitor the debug logs - Set debug: true during development

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us