Skip to content

API_REFERENCE.md

Latest commit

 

History

History
938 lines (744 loc) · 15.2 KB

API_REFERENCE.md

File metadata and controls

938 lines (744 loc) · 15.2 KB
Raw

Light-SS Pool API Reference

The Light-SS Pool HTTP API provides RESTful endpoints for managing proxy instances, subscriptions, and monitoring.

Base URL

http://127.0.0.1:9090

(Configurable via server.listen in config.yaml)

Authentication

If a token is configured in server.token, all API requests (except /health) must include a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Response Format

All API responses follow this JSON format:

{
  "success": true,
  "data": { ... },
  "error": ""
}
  • success: Boolean indicating if the request succeeded
  • data: Response data (present on success)
  • error: Error message (present on failure)

Endpoints

Health Check

GET /health

Check API server health status.

Response:

{
  "success": true,
  "data": {
    "status": "ok",
    "time": "2025-12-02T04:22:00Z"
  }
}

Instance Management

List Instances

GET /api/inst/list

List all proxy instances.

Response:

{
  "success": true,
  "data": {
    "instances": [
      {
        "id": "instance-001",
        "name": "HK Node 01",
        "source": "subscription",
        "enabled": true,
        "state": "running",
        "pid": 12345,
        "uptime_ms": 3600000,
        "proxy_addr": "127.0.0.1:10800",
        "server_addr": "example.com:8388",
        "cipher": "AEAD_CHACHA20_POLY1305"
      }
    ]
  }
}

Instance States:

  • stopped: Instance is not running
  • starting: Instance is starting up
  • running: Instance is running normally
  • failed: Instance failed to start or crashed

Add Instance

POST /api/inst/add

Manually add a new proxy instance.

Request Body:

{
  "id": "my-instance",
  "name": "My Custom Proxy",
  "enabled": true,
  "shadowsocks": {
    "server": "example.com:8388",
    "password": "your-password",
    "cipher": "AEAD_CHACHA20_POLY1305",
    "timeout": 300,
    "plugin": "simple-obfs",
    "plugin_opts": {
      "obfs": "http",
      "obfs-host": "www.bing.com"
    }
  },
  "proxies": "127.0.0.1:10800"
}

Fields:

  • id (required): Unique instance identifier
  • name (required): Display name
  • enabled: Enable instance on creation (default: false)
  • shadowsocks.server (required): SS server address:port
  • shadowsocks.password (required): SS password
  • shadowsocks.cipher: Encryption cipher (default: AEAD_CHACHA20_POLY1305)
  • shadowsocks.timeout: Connection timeout in seconds (default: 300)
  • shadowsocks.plugin: Plugin name (e.g., "simple-obfs")
  • shadowsocks.plugin_opts: Plugin options (key-value map)
  • proxies (required): Local proxy listen address

Response:

{
  "success": true,
  "data": {
    "id": "my-instance"
  }
}

Get Instance Status

GET /api/inst/:id/status

or

GET /api/inst/:id

Get detailed status of a specific instance.

Response:

{
  "success": true,
  "data": {
    "id": "instance-001",
    "name": "HK Node 01",
    "source": "subscription",
    "enabled": true,
    "state": "running",
    "pid": 12345,
    "uptime_ms": 3600000,
    "proxy_addr": "127.0.0.1:10800",
    "server_addr": "example.com:8388",
    "cipher": "AEAD_CHACHA20_POLY1305"
  }
}

For failed instances, additional fields are included:

{
  "success": true,
  "data": {
    "id": "instance-002",
    "state": "failed",
    "error": "process exited with code 1",
    "failure_count": 3,
    ...
  }
}

Start Instance

POST /api/inst/:id/start

Start a stopped instance.

Response:

{
  "success": true,
  "data": {
    "status": "started"
  }
}

Stop Instance

POST /api/inst/:id/stop

Stop a running instance.

Response:

{
  "success": true,
  "data": {
    "status": "stopped"
  }
}

Restart Instance

POST /api/inst/:id/restart

Restart an instance (stop then start).

Response:

{
  "success": true,
  "data": {
    "status": "restarted"
  }
}

Reload Instance

POST /api/inst/:id/reload

Reload instance configuration and restart if running.

Response:

{
  "success": true,
  "data": {
    "status": "reloaded"
  }
}

Enable Instance

POST /api/inst/:id/enable

Enable an instance (allows it to be started).

Response:

{
  "success": true,
  "data": {
    "status": "enabled"
  }
}

Disable Instance

POST /api/inst/:id/disable

Disable an instance (prevents it from starting).

Response:

{
  "success": true,
  "data": {
    "status": "disabled"
  }
}

Update Instance

POST /api/inst/:id/update

Update instance configuration.

Request Body:

{
  "name": "New Instance Name"
}

Response:

{
  "success": true,
  "data": {
    "status": "updated"
  }
}

Delete Instance

POST /api/inst/:id/delete

Remove an instance from the pool.

Response:

{
  "success": true,
  "data": {
    "status": "deleted"
  }
}

Subscription Management

List Subscriptions

GET /api/subs/list

List all subscriptions.

Response:

{
  "success": true,
  "data": {
    "subscriptions": [
      {
        "id": "my-sub",
        "name": "My Subscription",
        "url": "https://example.com/subscription",
        "enabled": true,
        "update_interval": 86400,
        "last_updated": "2025-12-02T04:00:00Z"
      }
    ]
  }
}

Add Subscription

POST /api/subs/add

Add a new subscription.

Request Body:

{
  "id": "my-sub",
  "name": "My Subscription",
  "url": "https://example.com/subscription",
  "enabled": true,
  "update_interval": 86400
}

Fields:

  • id (required): Unique subscription identifier
  • name (required): Display name
  • url (required): Subscription URL
  • enabled: Enable subscription (default: false)
  • update_interval: Auto-update interval in seconds (default: 86400 = 24h)

Response:

{
  "success": true,
  "data": {
    "id": "my-sub"
  }
}

Get Subscription Status

GET /api/subs/:id/status

or

GET /api/subs/:id

Get subscription details.

Response:

{
  "success": true,
  "data": {
    "id": "my-sub",
    "name": "My Subscription",
    "url": "https://example.com/subscription",
    "enabled": true,
    "update_interval": 86400,
    "last_updated": "2025-12-02T04:00:00Z"
  }
}

Sync Subscription

POST /api/subs/:id/sync

Fetch and parse subscription URL to update instances.

Response:

{
  "success": true,
  "data": {
    "status": "synced"
  }
}

This will:

  1. Fetch subscription URL
  2. Parse Shadowsocks nodes
  3. Create/update instances in the pool
  4. Reload pool manager with new instances

Enable Subscription

POST /api/subs/:id/enable

Enable a subscription.

Response:

{
  "success": true,
  "data": {
    "status": "enabled"
  }
}

Disable Subscription

POST /api/subs/:id/disable

Disable a subscription.

Response:

{
  "success": true,
  "data": {
    "status": "disabled"
  }
}

Update Subscription

POST /api/subs/:id/update

Update subscription configuration.

Request Body:

{
  "name": "New Subscription Name",
  "url": "https://new-url.com/subscription",
  "update_interval": 43200
}

All fields are optional. Only provided fields will be updated.

Response:

{
  "success": true,
  "data": {
    "status": "updated"
  }
}

Delete Subscription

POST /api/subs/:id/delete

Remove a subscription.

Response:

{
  "success": true,
  "data": {
    "status": "deleted"
  }
}

Test Subscription Servers

POST /api/subs/:id/test

Test all servers in a subscription without starting instances. Tests connection, latency, and optionally download speed.

Request Body:

{
  "latency_only": false,
  "force_refresh": false,
  "min_speed_mbps": 0,
  "max_latency_ms": 0
}

Fields:

  • latency_only: If true, only test latency (skip speed test) - much faster (default: false)
  • force_refresh: Force new test, ignore cache (default: false)
  • min_speed_mbps: Filter servers with minimum speed in Mbps (default: 0 = no filter)
  • max_latency_ms: Filter servers with maximum latency in milliseconds (default: 0 = no filter)

Response:

{
  "success": true,
  "data": {
    "subscription_id": "my-sub",
    "subscription_name": "My Subscription",
    "test_time": "2025-12-02T10:00:00Z",
    "total_servers": 310,
    "tested_servers": 310,
    "working_servers": 302,
    "failed_servers": 8,
    "cached": false,
    "cache_expires": "2025-12-02T12:00:00Z",
    "test_duration_seconds": 465.5,
    "results": [
      {
        "server": "example.com:8388",
        "name": "HK Node 01",
        "cipher": "aes-256-gcm",
        "success": true,
        "latency_ms": 36,
        "download_speed_mbps": 193.98,
        "rank": 1,
        "plugin": "simple-obfs",
        "test_time": "2025-12-02T10:00:00Z"
      }
    ],
    "summary": {
      "avg_latency_ms": 85,
      "avg_speed_mbps": 75.5,
      "fastest_server": "example.com:8388",
      "lowest_latency_server": "example2.com:8388"
    }
  }
}

Test Features:

  • Tests up to 1000 servers per subscription
  • 10 concurrent tests for performance
  • 15-second timeout per server
  • 2-hour result caching
  • Results ranked by download speed

Get Cached Test Results

GET /api/subs/:id/test-results

Retrieve cached test results without running a new test.

Response:

{
  "success": true,
  "data": {
    "subscription_id": "my-sub",
    "cached": true,
    "cache_expires": "2025-12-02T12:00:00Z",
    "total_servers": 310,
    "working_servers": 302,
    "failed_servers": 8,
    "results": [...]
  }
}

If no cached results exist:

{
  "success": false,
  "error": "no cached test results found"
}

Clear Test Cache

DELETE /api/subs/:id/test-cache

Clear cached test results for a subscription, forcing next test to be fresh.

Response:

{
  "success": true,
  "data": {
    "status": "cache cleared"
  }
}

Server Testing

Test Shadowsocks Server

POST /api/test

Test a Shadowsocks server without creating an instance. Useful for validating server configurations before deployment.

Request Body:

{
  "server": "example.com:8388",
  "password": "your-password",
  "cipher": "aes-256-gcm",
  "timeout": 15,
  "latency_only": false,
  "plugin": "simple-obfs",
  "plugin_opts": {
    "obfs": "http",
    "obfs-host": "bing.com"
  }
}

Fields:

  • server (required): Server address with port
  • password (required): Server password
  • cipher (required): Encryption cipher
  • timeout: Test timeout in seconds (default: 15)
  • latency_only: Only test latency, skip speed test (default: false)
  • plugin: Plugin name (e.g., "simple-obfs")
  • plugin_opts: Plugin options map

Response:

{
  "success": true,
  "data": {
    "server": "example.com:8388",
    "cipher": "aes-256-gcm",
    "success": true,
    "latency_ms": 36,
    "download_speed_mbps": 15.57,
    "timestamp": "2025-12-02T10:00:00Z"
  }
}

Failed Test Response:

{
  "success": true,
  "data": {
    "server": "example.com:8388",
    "cipher": "aes-256-gcm",
    "success": false,
    "error": "connection timeout",
    "timestamp": "2025-12-02T10:00:00Z"
  }
}

Pool Management

Get Pool Status

GET /api/pool/status

Get overall pool statistics.

Response:

{
  "success": true,
  "data": {
    "total": 10,
    "running": 7,
    "stopped": 2,
    "failed": 1,
    "enabled": 9,
    "disabled": 1
  }
}

Get Pool Configuration

GET /api/pool/config

Get pool configuration.

Response:

{
  "success": true,
  "data": {
    "listen": "127.0.0.1:9090",
    "light_ss_binary": "./lss",
    "data_path": "./data",
    "monitor_enabled": true,
    "auto_restart": true
  }
}

Start All Instances

POST /api/pool/start-all

Start all enabled instances.

Response:

{
  "success": true,
  "data": {
    "status": "started"
  }
}

Stop All Instances

POST /api/pool/stop-all

Stop all running instances.

Response:

{
  "success": true,
  "data": {
    "status": "stopped"
  }
}

Monitoring

Get Monitor Summary

GET /api/monitor/summary

Get health monitoring summary.

Response:

{
  "success": true,
  "data": {
    "total": 10,
    "healthy": 7,
    "unhealthy": 3,
    "running": 7,
    "stopped": 2,
    "failed": 1,
    "starting": 0,
    "enabled": 9,
    "checked_at": "2025-12-02T04:22:00Z"
  }
}

Get Monitor Status

GET /api/monitor/status

Get monitoring service status.

Response:

{
  "success": true,
  "data": {
    "enabled": true,
    "running": true,
    "last_check_at": "2025-12-02T04:22:00Z"
  }
}

Error Responses

Error responses follow the standard format:

{
  "success": false,
  "error": "error message here"
}

Common HTTP Status Codes

  • 200 OK: Request succeeded
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid authentication token
  • 404 Not Found: Resource not found
  • 405 Method Not Allowed: HTTP method not supported for endpoint
  • 500 Internal Server Error: Server error

Examples

Using curl

Add a subscription:

curl -X POST http://127.0.0.1:9090/api/subs/add \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-sub",
    "name": "My Subscription",
    "url": "https://example.com/subscription",
    "enabled": true
  }'

Sync subscription:

curl -X POST http://127.0.0.1:9090/api/subs/my-sub/sync

Start an instance:

curl -X POST http://127.0.0.1:9090/api/inst/instance-001/start

Get pool status:

curl http://127.0.0.1:9090/api/pool/status

Test subscription servers:

curl -X POST http://127.0.0.1:9090/api/subs/my-sub/test \
  -H "Content-Type: application/json" \
  -d '{
    "latency_only": true,
    "force_refresh": false
  }'

Get cached test results:

curl http://127.0.0.1:9090/api/subs/my-sub/test-results

Clear test cache:

curl -X DELETE http://127.0.0.1:9090/api/subs/my-sub/test-cache

Test a server manually:

curl -X POST http://127.0.0.1:9090/api/test \
  -H "Content-Type: application/json" \
  -d '{
    "server": "example.com:8388",
    "password": "your-password",
    "cipher": "aes-256-gcm",
    "latency_only": false,
    "plugin": "simple-obfs",
    "plugin_opts": {
      "obfs": "http",
      "obfs-host": "bing.com"
    }
  }'

With Authentication

If token authentication is enabled:

curl -X POST http://127.0.0.1:9090/api/subs/my-sub/sync \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Using the CLI

The lspc CLI client provides a convenient wrapper around the API:

# Add subscription
./lspc subs add my-sub -name "My Subscription" -url "https://..." -enabled

# Sync subscription
./lspc subs sync my-sub

# Start instance
./lspc inst start instance-001

# Get pool status
./lspc pool status

# Test subscription servers
./lspc subs test my-sub --latency-only

# View test results
./lspc subs test-results my-sub

# Clear test cache
./lspc subs test-clear my-sub

# Test a server manually
./lspc test --server example.com:8388 --password mypass --cipher aes-256-gcm --latency-only

See the main README for more CLI examples.