HTTP API

SurgeTeam

该文档还在撰写和完善中

HTTP API

Starts from Surge iOS Build xxx and Surge Mac 4.0.0. You may use HTTP APIs to control Surge.

Configuration

[General]
http-api = examplekey@0.0.0.0:6166

Authentication

The API key must be filled in the 'X-Key' header for all requests.

GET /v1/events
X-Key: examplekey
Accept: */*

Basic Constraints

Only HTTP without TLS is supported currently. Surge only uses GET and POST methods.

For GET method, you should use URL queries to send parameters.
For POST method, you should use JSON body to send parameters.

Surge will always return a JSON body as a response.

Paths

Toggle capabilities

GET /v1/features/mitm
POST /v1/features/mitm
GET /v1/features/capture
POST /v1/features/capture
GET /v1/features/rewrite
POST /v1/features/rewrite
GET /v1/features/scripting
POST /v1/features/scripting
GET /v1/features/system_proxy (Surge Mac Only)
POST /v1/features/system_proxy (Surge Mac Only)
GET /v1/features/enhanced_mode (Surge Mac Only)
POST /v1/features/enhanced_mode (Surge Mac Only)

Use GET method to obtain the state of a capability.

GET Response example:

{"enabled":true}

Use POST method to adjust the state of a capability.

POST Request example:

{"enabled":true}

Outbound Mode

GET /v1/outbound
POST /v1/outbound

Use GET to obtain the outbound mode, and use POST to change it.

GET Response example:

{"mode":"rule"}

POST Request example:

{"mode":"rule"}

Possible modes: direct, proxy, rule

GET /v1/outbound/global
POST /v1/outbound/global

Obtain or change the default policy for global outbound mode.

GET Response example:

{"policy":"ProxyA"}

POST Request example:

{"policy":"ProxyB"}

Proxy Policy

GET /v1/policies

List all policies.

GET /v1/policies/detail?policy_name=ProxyNameHere

Obtain the detail of policy.

POST /v1/policies/test

Test policies with a URL.

Request example:

{"policy_names": ["ProxyA", "ProxyB"], "url": "http://bing.com"}

GET /v1/policy_groups

List all policy groups and their options.

GET /v1/policy_groups/test_results

Obtain the test result of a url-test/fallback/load-balance group.

GET /v1/policy_groups/select?group_name=GroupNameHere

Obtain the option of a select group.

Response example:

{"policy": "ProxyA"}

POST /v1/policy_groups/select

Change the option of a select group.

Request example:

{"group_name": "GroupA", "policy": "ProxyA"}

POST /v1/policy_groups/test

Test a group immediately.

Request example:

{"group_name": "GroupA"}

Response example:

{
    "results": [
        {
            "data": {
                "ProxyA": {
                    "tcp": 48,
                    "rtt": 45,
                    "receive": 273,
                    "available": 213
                },
                "ProxyB": {
                    "tcp": 48,
                    "tfo": false,
                    "receive": 164,
                    "rtt": 51,
                    "available": 48
                },
                "ProxyC": {}
            },
            "time": 1595510609.6405091
        }
    ],
    "time": 1595510609.6405091,
    "winner": "ProxyA"
}

Requests

GET /v1/requests/recent

List recent requests.

GET /v1/requests/active

List all active requests.

POST /v1/requests/kill

Kill an active request.

Request example:

{"id": 100}

Profiles

GET /v1/profiles/current?sensitive=0

Obtain the text content of the current profile. If 'sensitive' is false, all passwords field will be masked.

POST /v1/profiles/reload

Execute profile reloading immediately.

POST /v1/profiles/switch (Surge Mac Only)

Request example:

{"name": "Profile2"}

Switch to another profile.

DNS

POST /v1/dns/flush

Flush the DNS cache.

GET /v1/dns

Obtain the current DNS cache content.

POST /v1/test/dns_delay

Test the DNS delay.

Modules

GET /v1/modules

List the available and enabled modules.

Response example:

{
    "enabled": [
        "router.com"
    ],
    "available": [
        "Game Console SNAT",
        "Google Home Devices",
        "router.com",
        "MitM All Hostnames"
    ]
}

POST /v1/modules

Enable or disable modules.

Request example:

{
	"router.com": false,
	"Google Home Devices": true
}

Scripting

GET /v1/scripting

List all the scripts.

POST /v1/scripting/evaluate

Evaluate a script with a mock environment.

Request example:

{
    "script_text": "The content of JS script",
    "mock_type": "cron",
    "timeout": 5
}

POST /v1/scripting/cron/evaluate

Evaluate a cron script immediately.

Request example:

{
    "script_name": "script1",
}

Misc

POST /v1/stop

Shutdown Surge engine. If Always On is enabled on Surge iOS, the Surge engine will restart.

GET /v1/events

Obtain the content of the event center.

GET /v1/rules

Obtain the list of rules.

GET /v1/traffic

Obtain traffic information.

POST /v1/log/level

Change the log level for the current session.

Request example:

{"level": "verbose"}

msdurex

Mac Version 4.0？ When can we update to this version?

geekdada

UlysessWeb

Is Mac 4.0.0 a paid upgrade？

mieqq

请问下 HTTP API 有计划支持模块的开关吗？谢谢。

mieqq

感谢添加对模块的支持，另外，还是希望 Scripting 或 HTTP API 能添加获取所有持久化数据的 API，谢谢😆

Gary

这个文档里的功能是已经在测试版有了吗？

NozyLog

希望能加入获取流量统计信息的 API。

Surge Mac 的流量统计没 Surge iOS 的全面（比如缺了按主机名分组的流量统计），Surge Mac 上按策略分组的流量统计查起来也麻烦，必须一个个切换。还有实时流量图也缺少调节功能……

Trowel6700

背景

surge version: surge 4.5.2
os: macOS Monterey
surge 配置 http-api 后，可以在浏览器正常访问，http://localhost:6171

目标

希望使用 https 访问 surge http api，所以试图通过 nginx 反向代理，但遇到了问题

问题

通过 docker 搭建了 nginx，反向代理 localhost:6171 后，通过 https://surge.example.com 访问，现象为：

可以正常打开登录页
但登录进去后，会报错

# 报错1（居中弹窗提示）
Network Error
Unable to connect to Surge, please try again.
# 报错2（侧边消息提示）
Your surge is too old please upgrade your surge to use this application

nginx(docker方式部署的) 配置如下：

# 宿主机 6171
upstream surge {
    server host.docker.internal:6171;
}

server {
        listen 80;
        server_name surge.example.com ;
        return 301 https://$host$request_uri;
}
server {
    listen 443 ssl;
    server_name surge.example.com;

    ssl_certificate      /etc/nginx/ssl/fullchain.cer;
    ssl_certificate_key  /etc/nginx/ssl/example.com.key;

    location / {     
        proxy_pass http://surge;     
    }
}

mieqq

Trowel6700
Surge http api 已经支持 https 访问了啊
[General]
http-api-tls = true

Trowel6700

mieqq

官方文档没看到有这个 feature 啊，而且如果追加了这个配置，https port 是多少呢？也是 6171 吗？

配置该项后，访问 https://localhost:6171/ ?

貌似我追加了这个配置，http://localhost:6171 也访问不了了

mieqq

Trowel6700

端口等其他都一样的，mitm 有配置了证书吗，https api 会使用这个证书

arcwarden

@SurgeTeam 升级 iOS16 系统后调用 GET /v1/traffic 这个 API 超时，麻烦看下为啥

mieqq

arcwarden 脚本编辑器试了下好像并没有问题

arcwarden

mieqq 你多试几次，杀掉surge，再进来，不是必现

$httpClient.get({
url: 'http://127.0.0.1:6171/v1/traffic',
headers: {
'X-Key': '123456'
}
},
function(error, response, data) {
console.log(data)
$done()
})

mieqq

arcwarden 没发现，你可以试试新的API

$httpAPI(method<String>, path<String>, body<String>, callback<Function>(result<Object>))

arcwarden

mieqq ok

arcwarden

mieqq 帮忙看下

arcwarden

arcwarden 亲，脚本里面发起http请求这个版本不会走代理规则了吗

mieqq

arcwarden 会的，只是 generic 类型脚本发起的请求不会在最近请求显示，其他类型的都可以，并且是走规则系统的。

arcwarden

这里表达的意思我有点看不懂，是说脚本发起 HTTP 请求需要单独声明策略吗

You may specify a policy to perform the request:

policy: Use an existing policy with its name.
policy-descriptor: Use a temporary policy with a full descriptor.
You must predeclare ability=http-client-policy to use this option.

mieqq

arcwarden 这个是新加的一个特性而已，发起请求的时候可以增加参数选择走已用的策略，或者临时定义的策略