HTTP API
Starts from Surge iOS 4.4.0 and Surge Mac 4.0.0. You may use HTTP API to control Surge.
Configuration
[General]
http-api = examplekey@0.0.0.0:6171
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:
{
"available": [
"ProxyA",
"ProxyB"
],
}
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.
- GET /v1/profiles (Surge Mac Only, starts from version 4.0.6)
Get all available profile names.
- POST /v1/profiles/check (Surge Mac Only, starts from version 4.0.6)
Request example:
{"name": "Profile2"}
Check the profile. If the profile is invalid an error will be returned. Otherwise the "error" field will be null.
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",
}
Device Management (Surge Mac only, starts from v4.0.6)
- GET /v1/devices
Obtain the list of the current active and saved devices.
- GET /v1/devices/icon?id={iconID}
Obtain the icon of a device. You may get the iconID from device.dhcpDevice.icon.
- POST /v1/devices
Change the device properties. physicalAddress
field is required. And you may adjust multiple or one property from name
, address
, and shouldHandledBySurge
.
Request example:
{
"physicalAddress":"F0:9F:C2:00:00:00",
"name": "Computer",
"address": "192.168.1.200",
"shouldHandledBySurge": true
}
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"}