Skip to content

REST API

Jump to bottom
Chokri Hammedi edited this page Apr 23, 2026 · 3 revisions

REST API

The server exposes a REST API under /api/v1/. All endpoints except /api/v1/auth require a Bearer token.

API Documentation

Complete endpoint documentation with examples is available at:

http://<server>:1024/docs

This page lists all available API endpoints, request/response formats, and usage examples.

Authentication

POST to /api/v1/auth with the server key to receive a token:

curl -X POST http://<server>:1024/api/v1/auth \
  -H "Content-Type: application/json" \
  -d '{"key": "<your-key>"}'

Response:

{
  "token": "tun_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Use the token in all subsequent requests:

-H "Authorization: Bearer tun_xxx"

Token Scopes

Scope Access
read GET requests, view agents, routes, forwards
write Control operations, port forwards, SOCKS5, CLI commands
admin Settings, token management, shutdown

Tokens are prefixed tun_ and support an optional TTL. Manage them via the Settings modal in the dashboard or the token REPL command.

Endpoints

Status

GET /api/v1/status

Returns server uptime and connected agent count.

Agents

GET    /api/v1/agents              List all connected agents
GET    /api/v1/agents/{id}         Get a specific agent
POST   /api/v1/agents/{id}/disconnect   Disconnect an agent
POST   /api/v1/agents/{id}/reconnect    Force reconnect
POST   /api/v1/agents/{id}/tag          Set a display tag
POST   /api/v1/agents/{id}/ping         Ping a host via agent
POST   /api/v1/agents/{id}/discover     Run ping sweep on agent subnets
POST   /api/v1/agents/{id}/portscan     Run port scan via agent

Example | list agents:

curl -H "Authorization: Bearer tun_xxx" \
  http://<server>:1024/api/v1/agents

Example | tag an agent:

curl -X POST http://<server>:1024/api/v1/agents/agent-1/tag \
  -H "Authorization: Bearer tun_xxx" \
  -H "Content-Type: application/json" \
  -d '{"tag": "dc-east"}'

Port Forwards

GET    /api/v1/forwards            List active forwards
POST   /api/v1/forwards            Add a forward
DELETE /api/v1/forwards            Remove a forward

Example | add a TCP forward:

curl -X POST http://<server>:1024/api/v1/forwards \
  -H "Authorization: Bearer tun_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add",
    "agent_id": "agent-1",
    "local_port": 8080,
    "target_host": "192.168.1.10",
    "target_port": 80
  }'

Reverse Forwards

GET    /api/v1/rforwards           List reverse forwards
POST   /api/v1/rforwards           Add a reverse forward
DELETE /api/v1/rforwards           Remove a reverse forward

SOCKS5

GET    /api/v1/socks               List active SOCKS5 proxies
POST   /api/v1/socks               Start a SOCKS5 proxy
DELETE /api/v1/socks               Stop a SOCKS5 proxy

Example | start SOCKS5:

curl -X POST http://<server>:1024/api/v1/socks \
  -H "Authorization: Bearer tun_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent-1", "port": 1080}'

With authentication:

-d '{"agent_id": "agent-1", "port": 1080, "username": "user", "password": "pass"}'

Routes

GET   /api/v1/routes               List routing table
PATCH /api/v1/routes               Enable or disable a route

CLI

Run any REPL command via the API:

POST /api/v1/cli

curl -X POST http://<server>:1024/api/v1/cli \
  -H "Authorization: Bearer tun_xxx" \
  -H "Content-Type: application/json" \
  -d '{"command": "discover agent-1 10.10.10.0/24"}'

Settings

GET   /api/v1/settings             Get current server config
PATCH /api/v1/settings             Update server config

Requires admin scope.

Tokens

GET    /api/v1/tokens              List API tokens
POST   /api/v1/tokens              Create a token
DELETE /api/v1/tokens              Revoke a token

Requires admin scope.

Example| create a read-only token with TTL:

curl -X POST http://<server>:1024/api/v1/tokens \
  -H "Authorization: Bearer tun_xxx" \
  -H "Content-Type: application/json" \
  -d '{"scope": "read", "ttl_minutes": 60}'

Connect Bind Agent

POST /api/v1/connect-bind

Tell the server to dial a bind-mode agent:

curl -X POST http://<server>:1024/api/v1/connect-bind \
  -H "Authorization: Bearer tun_xxx" \
  -H "Content-Type: application/json" \
  -d '{"address": "<agent-ip>:4444"}'

Shutdown

POST /api/v1/shutdown

Requires admin scope. Gracefully shuts down the server.

Dashboard WebSocket

GET /api/dashboard-data            Current dashboard state (session auth)
WS  /ws-dashboard                  Real-time push stream (session auth)

Used by the web dashboard. Requires a valid session cookie, not a Bearer token.

Use only on systems you own or have explicit written permission to test. Unauthorized use is prohibited.

Clone this wiki locally