Tools and APIs
Profile Validation Service
This service is in beta.
Surge provides an online service that checks whether a profile is valid, using the same profile parser as Surge. It is useful for checking a profile before you distribute it, for example in a CI pipeline or in a tool that generates profiles.
The service is available at https://services.nssurge.com. It needs no API key, and cross-origin requests are allowed, so a web page can call it directly.
Validating a Profile
POST https://services.nssurge.com/v1/config/validate
Send the whole profile as the request body:
curl https://services.nssurge.com/v1/config/validate \
-H 'Content-Type: text/plain' \
--data-binary @surge.conf
Or, with Content-Type: application/json, pass the profile content in the profile field:
curl https://services.nssurge.com/v1/config/validate \
-H 'Content-Type: application/json' \
--data '{"profile": "[General]\nloglevel = notify\n\n[Rule]\nFINAL,DIRECT\n"}'
The response is a JSON object. valid indicates whether the profile is valid:
{"valid": true}
When the profile is invalid, error.message describes the problem, including the line that caused it:
{
"valid": false,
"error": {
"message": "Invalid line in profile.conf at #4\nError: The parameter `port` is required and must be provided.\nLine: p1 = vless, 1.2.3.4 (SGSettingsModelErrorDomain:0)"
}
}
An invalid profile is still a successful request and returns HTTP 200. Other status codes mean that the profile was not checked:
| Status | Meaning |
|---|---|
| 400 | The request carries no profile content, or the profile is larger than 512 KB. |
| 429 | The service is handling too many requests. Try again later. |
| 500 | The check failed or took longer than 10 seconds. |
These responses use the same JSON format, with valid set to false and the reason in error.message.
What Is Checked
The service checks the profile text itself, the same way Surge parses it when the profile is loaded. It does not have your other files and does not fetch anything from the network:
- Lines that include other files with
#!includecannot be resolved and are reported as errors. Merge the included content into the profile before checking it. - Resources referenced by URL, such as rule sets and
policy-path, are not downloaded. Only the line that references them is checked. - The service checks complete profiles. A module is not a complete profile and fails the check.
Checker Version
GET https://services.nssurge.com/v1/version
Returns the version of the Surge parser used by the service:
{"version": "6012000"}
The number encodes the Surge Mac version that the parser was built from: 6012000 is Mac 6.12.0. A profile that uses syntax introduced in a later version may be reported as invalid.
Privacy
To protect your privacy, the service does not log or store the content of the profiles it receives. Each profile is deleted as soon as it has been checked.
If you are still concerned about privacy, replace sensitive values such as server addresses, usernames, and passwords in the profile before checking it. Use placeholders in the same format, for example server.example.com for a hostname, so that the lines remain valid.