Tweaks

A tweak provides connection methods for compatible servers. Its tunnels object describes the allowed families and variants; carrier chooses the transport carrier; methods holds payload, TLS, or proxy values.

Use your Client API key for every endpoint here. The quickstart sets the shell variables used below.

List tweaks

GET /api/v1/configs/{config_key}/tweaks

Returns configuration identifiers and a tweaks array. Entries include id, unique_key, name, category, tunnels, carrier, methods, and timestamps. Method values and carrier settings are omitted in this summary.

Create a tweak

POST /api/v1/configs/{config_key}/tweaks

For a direct SSH connection, save this as tweak.json:

{
    "name": "Direct SSH",
    "tunnels": {
        "ssh": {
            "variants": [
                "default"
            ]
        }
    },
    "carrier": {
        "type": "default",
        "settings": {}
    },
    "methods": {}
}

curl --fail-with-body --request POST "$API_BASE/configs/$CONFIG_KEY/tweaks" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $CLIENT_API_KEY" \
  --data-binary @tweak.json

Success is HTTP 201 Created, with a Location header and the full editable object in tweak, beside success and message. Private method values are included; the response uses Cache-Control: no-store, private. The owning account's tweak allowance applies per configuration.

Read a tweak for editing

GET /api/v1/configs/{config_key}/tweaks/{tweak_key}

export TWEAK_KEY='PASTE_THE_RETURNED_TWEAK_UNIQUE_KEY'
curl --fail-with-body "$API_BASE/configs/$CONFIG_KEY/tweaks/$TWEAK_KEY" \
  --header 'Accept: application/json' \
  --header "X-API-Key: $CLIENT_API_KEY"

Returns the full object in tweak, including method values and carrier settings. It is owner-only and uses Cache-Control: no-store, private. Copy only name, category, note, tunnels, carrier, and methods into an update body; omit the response-only id. The URL supplies the resource key.

Update a tweak

PATCH /api/v1/configs/{config_key}/tweaks/{tweak_key}

This example enables TLS for the direct SSH server and tweak created in these guides. First configure a working TLS listener on your infrastructure; the API only records its settings. Replace 443 below if your listener uses another port.

Update the existing server to allow both direct and TLS connections:

curl --fail-with-body --request PATCH "$API_BASE/configs/$CONFIG_KEY/servers/$SERVER_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $CLIENT_API_KEY" \
  --data '{"accepted_methods":[[],["tls"]],"settings":{"tls_ports":[443]}}'

Then update the tweak with your TLS hostname:

curl --fail-with-body --request PATCH "$API_BASE/configs/$CONFIG_KEY/tweaks/$TWEAK_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $CLIENT_API_KEY" \
  --data '{"methods":{"tls":{"sni":["edge.example.com"],"version":"TLSv1.2"}}}'

Omitted metadata and connection groups stay unchanged. A supplied nested group replaces that group; it is not a recursive patch. For example, supplying methods with only tls removes an existing payload or proxy. Send "methods": {} to clear all methods.

PATCH changes an existing tweak and returns the full editable object in tweak. A missing key returns 404 and never creates a record. Use batch sync for intentional upsert.

Replace a tweak

PUT /api/v1/configs/{config_key}/tweaks/{tweak_key}

Use PUT only for a complete replacement of an existing tweak. Include name, tunnels, carrier, and methods. Omitted optional fields reset to their defaults: category and note become null. The existing identity is preserved. Missing required groups return 422; a missing resource returns 404.

Use the same complete JSON shape as creation, without response-only id, internal, or unique_key fields. PUT returns HTTP 200 and the editable object in tweak. Use PATCH for a rename, method change, or another partial change.

Delete a tweak

DELETE /api/v1/configs/{config_key}/tweaks/{tweak_key}

curl --fail-with-body --request DELETE "$API_BASE/configs/$CONFIG_KEY/tweaks/$TWEAK_KEY" \
  --header 'Accept: application/json' \
  --header "X-API-Key: $CLIENT_API_KEY"

Returns success: true and tweak containing unique_key and action: "deleted". A missing tweak returns 404.

Match a tweak to a server

A matching pair uses the same carrier, a supported tunnel family and variant, a method set explicitly allowed by the server, and compatible categories. A server accepting [[], ["tls"]] supports direct or TLS; it does not support a tweak using both payload and TLS.

See connection format and complete examples before combining more methods.

Categories affect matching

category is also a connection filter in Android and iOS, not just a display label. Matching ignores case and surrounding whitespace. Separate multiple category tokens with semicolons or newlines; commas do not separate tokens.

Keep both categories empty for the first example. If you categorize a server later, update the intended tweaks too. The API validates each resource's structure; it does not guarantee that every submitted tweak has a matching server in the configuration.

One tweak can match several servers and tunnel variants. The app filters available servers for the selected tweak; a successful API response with no matching pair can still leave the app with nothing to connect to.

Protected resources

Resources marked internal: true are protected even when they belong to your configuration. Lists expose only id, unique_key, name, category, internal, and timestamps. Connection groups, credentials, profiles, method values, and notes are omitted.

Only removal is allowed. Detail reads and PATCH/PUT edits return 403; batch sync also rejects any attempt to update a protected key, including a request that removes and recreates that same key. Delete it through the individual DELETE endpoint or the batch removal array. Neither Client nor Business requests can set the internal flag or turn protected resources into editable resources.