Connection format

Both APIs accept the same server and tweak connection documents. Use explicit objects and arrays; keep endpoints, credentials, and method values in their own fields.

Server and tweak at a glance

Tunnel families

A server uses {"family":"ssh","variant":"default"}. A tweak uses {"ssh":{"variants":["default"]}}. Select the exact profile protocol for V2Ray.

Carrier

Every connection needs carrier.type and carrier.settings.

DNS carriers are available for SSH default, OpenVPN TCP, and the stream-capable V2Ray variants. Proxy methods are not available with DNS carriers. BHTTP, HCR, OpenVPN UDP, V2Ray Hysteria2, V2Ray WireGuard, and UDP Hysteria use the default carrier.

For SSH/OpenVPN with a DNS carrier, omit settings.endpoint; the server destination comes from the carrier. With the default carrier, supply the endpoint separately.

Accepted method combinations

A server's accepted_methods is a nonempty array of distinct combinations. Each combination is an array containing zero or more of payload, proxy, and tls.

{
  "accepted_methods": [[], ["tls"], ["payload", "tls"]]
}

This permits direct, TLS, or payload plus TLS. It does not permit payload alone. [[]] means direct only. [] is invalid because it permits no connection at all.

The supported set depends on the tunnel and carrier. BHTTP, HCR, OpenVPN UDP, Hysteria2, and WireGuard accept direct only. UDP Hysteria supports direct or TLS. Stream protocols on the default carrier support payload, proxy, and TLS combinations; DNS carriers support payload/TLS combinations.

Tweak methods

A direct tweak uses "methods": {}. Here is a TLS-only method object:

{
  "methods": {
    "tls": {"sni": ["edge.example.com"], "version": "TLSv1.2"}
  }
}

A tweak's method names must match one of the server's accepted combinations. SSH/OpenVPN connections offering TLS on the default carrier also need settings.tls_ports. For V2Ray payload/proxy/TLS methods, use a compatible RAW/TCP profile; the profile must support the chosen runtime method; API validation alone does not test that connection. See the dedicated examples.

Endpoints and credentials

SSH: use settings.endpoint.hosts, settings.endpoint.ports, and a settings.credentials object with username and password. Optional settings.private_key contains the private key text; settings.cipher_alias and settings.cipher_algorithm select SSH cipher settings. Each optional string allows up to 1,000,000 characters. These describe an existing server, not a request to generate keys or change its cipher configuration.

OpenVPN: put the profile text in settings.profile, destinations in settings.endpoint, and login values in settings.credentials. Endpoint and transport selection are separate from profile text. Do not include remote, remote-random, proto, port, rport, or <connection> blocks in the API profile: express the destination in endpoint and the transport in tunnel.variant. Use client (or tls-client) and a TUN device, with inline certificates/keys instead of filesystem paths. A panel .ovpn import can extract this structure for you; the API expects it already separated. Optional fields include private_key_password and tls_ports.

V2Ray: put the share URI or supported raw profile in settings.profile. Its protocol must match tunnel.variant.

UDP Hysteria: use endpoint hosts and port_sets, an authentication string, and hop_interval_seconds (at least 8). Optional settings include bandwidth, ALPN, PEM CA certificates, obfuscation password, receive window, MTU discovery, and UDP idle timeout.

{
  "endpoint": {"hosts": ["ssh.example.com", "2001:db8::10"], "ports": [22, 2222]},
  "credentials": {"username": "demo", "password": "replace-me"}
}

This fragment belongs inside a server's settings. Host values contain only a hostname or IP: no URL scheme, port, or credentials. IPv6 addresses in host arrays are bare (2001:db8::10), without brackets. Port arrays contain 1–1,000 distinct JSON integers between 1 and 65,535. Host arrays contain 1–1,000 distinct entries of at most 253 characters. Hosts and ports are independent alternatives, not pairs matched by array position; do not join values with separators.

A Hysteria port set can contain individual ports and ranges:

{
  "endpoint": {
    "hosts": ["hy.example.com"],
    "port_sets": [[{"from": 443, "to": 443}, {"from": 5000, "to": 5100}]]
  }
}

Use connection examples for complete, copyable documents rather than submitting these field fragments on their own.

Transport tuning

These optional fields belong in the tweak, not in server credentials. Only include tuning for a selected tunnel variant.

For BHTTP and HCR, settings.endpoint.ports on the server is the relay listener port. BHTTP/HCR tuning belongs to the tweak. For V2Ray, bug_hosts supplies runtime host candidates; it does not change the profile protocol.

For SlowDNS, carrier.settings.resolvers accepts plain DNS addresses or udp://, https://, tls://, and dot:// resolvers. Server carrier.settings.nameservers contains DNS tunnel nameserver hosts; carrier.settings.public_key is the tunnel's public key.

For Slipstream, use 1–16 total numeric IP paths across carrier.settings.resolvers and carrier.settings.authoritative, with optional ports. IPv6 with a port uses [2001:db8::10]:53 in these resolver strings. carrier.settings.keep_alive_ms is an integer from 0–65,535; carrier.settings.congestion_control is bbr or dcubic. Each domain must be a valid delegated DNS name shorter than 240 bytes. Server settings require domains and may include certificate, a single PEM leaf certificate of at most 16,384 characters.

Hysteria tuning

Paths below are relative to server settings.

Before testing a connection

A valid API document records how to connect; it does not provision remote services or prove they are reachable. SSH users, TLS listeners, proxies, DNS tunnel domains/keys, OpenVPN certificates, and V2Ray profiles must already match your infrastructure.

For a server and tweak used together, verify the tunnel variant, carrier, accepted method combination, and category matching (empty matches empty; named categories must share a token, ignoring case and surrounding spaces; separate tokens with semicolons or newlines). A direct method means no extra payload/proxy/TLS method; it does not disable encryption already supplied by SSH, an OpenVPN profile, or a V2Ray profile.

Field limits and complete values

Use full values for enabled methods: "tls": {} is a summary marker, not a valid authoring value. Send methods: {} only when no methods are enabled. One tweak's carrier and methods must be eligible for every selected family/variant; for example, a proxy tweak cannot also select OpenVPN UDP.

For OpenVPN, supply a complete usable profile with the necessary inline certificates/keys and options. Panel/API validation is structural; the apps also evaluate profiles with their bundled OpenVPN core. Passing API validation does not guarantee successful native parsing, authentication, or negotiation.