Client API Documentation

Authentication

Authenticate every request with the Client API key issued for the Panel account that owns the target configuration.

Rate Limits and Daily Quota

Each Client API credential has a short-term rate limit and a daily request quota. The daily quota resets at 00:00 UTC.

Available Operations

Use these endpoints to automate resources inside configurations owned by the authenticated Panel account.

Existing Configurations

How it works

• GET /api/v1/configs lists configurations owned by the account authenticated with your Client API key.
• POST /api/v1/configs syncs servers and tweaks for one existing configuration selected by config_unique_key; it does not create a new configuration.
• Create the configuration in Panel before connecting your automation.
• The Client API can read and replace the configuration message. Manage other configuration settings, such as password, update_url, and lock toggles in Panel.

Request Schema

Configuration Message

Use GET /api/v1/configs/{config_key}/message to read the complete current message and PUT /api/v1/configs/{config_key}/message to replace it.

Tweak

Endpoints: GET /api/v1/configs/{config_key}/tweaks, POST /api/v1/configs/{config_key}/tweaks, PUT /api/v1/configs/{config_key}/tweaks/{tweak_key}, DELETE /api/v1/configs/{config_key}/tweaks/{tweak_key}.

Required fields: name, tunnel_type.

Server

Endpoints: GET /api/v1/configs/{config_key}/servers, POST /api/v1/configs/{config_key}/servers, PUT /api/v1/configs/{config_key}/servers/{server_key}, DELETE /api/v1/configs/{config_key}/servers/{server_key}.

Required fields: name, tunnel_type.

Cloud Access

Automate the Access-tab resources of an existing configuration: cloud Device IDs and cloud Passwords.

Device IDs

Endpoints: GET /api/v1/configs/{config_key}/device-ids, POST /api/v1/configs/{config_key}/device-ids, PUT /api/v1/configs/{config_key}/device-ids/{device_id}, DELETE /api/v1/configs/{config_key}/device-ids/{device_id}.

{device_id} in URL is the numeric Device ID record id from list/create responses.

Passwords

Endpoints: GET /api/v1/configs/{config_key}/passwords, POST /api/v1/configs/{config_key}/passwords, PUT /api/v1/configs/{config_key}/passwords/{password_id}, DELETE /api/v1/configs/{config_key}/passwords/{password_id}.

{password_id} in URL is the numeric Password record id from list/create responses.

Rules

• A Client API key can access only configurations owned by its Panel account.
• Do not send empty values for required fields.
• Do not send id or configuration_id in server/tweak payloads.
• Use exact enum values only. Invalid values return 422.
• Optional fields can be omitted or set to null.
• Configuration message updates replace the complete value. Fetch the current message first when changing only a date or another substring.
• Delete operations require existing unique_key values in the target configuration.
• Cloud password rule: delete_after_used=true is valid only for type=one_time.
• Cloud HWID rule: each device_id must be exactly 32 hexadecimal characters.
• Cloud access expiry: expire_date uses YYYY-MM-DD. Expired Device IDs and passwords are rejected during authentication.
• Cloud access limits are enforced for device IDs and passwords per configuration.
• Account limits are enforced for configurations, servers, tweaks, device IDs, and passwords.

Examples

These examples automate configurations that already exist in your account. UUID-like keys are shortened with ... for readability; send the full value in real requests.

List Configurations in Your Account

curl -X GET "https://httptweak.com/api/v1/configs" \
  -H "X-API-Key: your_api_key"

List a Configuration's Servers and Tweaks

curl -X GET "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/resources" \
  -H "X-API-Key: your_api_key"

Get the Current Configuration Message

curl -X GET "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/message" \
  -H "X-API-Key: your_api_key"

Replace the Configuration Message

Send the complete message template. You can use placeholders for values that should be filled from the configuration during export.

curl -X PUT "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/message" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "message": "Welcome to [config_name]. Updated: [updated_at]. Servers: [server_list]"
  }'

Add a Server

curl -X POST "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/servers" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "Main SSH Server",
    "category": "Free",
    "tunnel_type": "ssh",
    "host_port_user_pass": "1.2.3.4:22@username:password"
  }'

Add an IPv6 Server

curl -X POST "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/servers" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "IPv6 SSH Server",
    "category": "Free",
    "tunnel_type": "ssh",
    "host_port_user_pass": "[2001:db8::10];[2001:db8::11]:22@username:password"
  }'

Update Server

curl -X PUT "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/servers/8bcb3c4f...7b6c4a12" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "Main SSH Server v2",
    "tunnel_type": "ssh",
    "host_port_user_pass": "1.2.3.4:22@username:newpassword"
  }'

Add a Tweak

curl -X POST "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/tweaks" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "name": "Default Tweak",
    "category": "Free",
    "tunnel_type": "ovpn_tcp_ssh",
    "payload": "CONNECT [host_port] HTTP/1.1",
    "sni": "example.com"
  }'

Add Cloud Device IDs

curl -X POST "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/device-ids" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "device_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\nBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
    "note": "Batch import",
    "is_active": true,
    "delete_after_used": false,
    "expire_date": "2031-02-03"
  }'

Add One-time Cloud Password

curl -X POST "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/passwords" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "password": "Secret123",
    "type": "one_time",
    "delete_after_used": true,
    "is_active": true,
    "expire_date": "2032-04-05"
  }'

Remove a Server

curl -X DELETE "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/servers/8bcb3c4f...7b6c4a12" \
  -H "X-API-Key: your_api_key"

Remove a Tweak

curl -X DELETE "https://httptweak.com/api/v1/configs/2f7c1f7e...dc5a2d8b/tweaks/6e1d2f8c...d5ce0d62" \
  -H "X-API-Key: your_api_key"

Responses

List Configurations Response

{
  "success": true,
  "message": "Configurations listed",
  "total": 2,
  "max_configurations": 20,
  "remaining_configurations": 18,
  "configurations": [
    {
      "id": 12,
      "name": "Config 12",
      "unique_key": "2f7c1f7e...dc5a2d8b",
      "servers_count": 2,
      "tweaks_count": 1,
      "is_cloud_hwid_lock": false,
      "is_cloud_password": false,
      "created_at": "2026-02-20 09:00:00",
      "updated_at": "2026-02-20 09:10:00"
    }
  ]
}

Configuration Resources Response

{
  "success": true,
  "message": "Configuration resources listed",
  "configuration_id": 12,
  "configuration_name": "Config 12",
  "config_unique_key": "2f7c1f7e...dc5a2d8b",
  "servers": [
    {
      "id": 2,
      "name": "Main SSH Server v2",
      "category": "Free",
      "tunnel_type": "ssh",
      "unique_key": "8bcb3c4f...7b6c4a12",
      "created_at": "2026-02-20 09:00:00",
      "updated_at": "2026-02-20 09:10:00"
    }
  ],
  "tweaks": [
    {
      "id": 4,
      "name": "Default Tweak",
      "category": "Free",
      "tunnel_type": "ovpn_tcp_ssh",
      "bug_host": null,
      "unique_key": "6e1d2f8c...d5ce0d62",
      "created_at": "2026-02-20 09:00:00",
      "updated_at": "2026-02-20 09:05:00"
    }
  ]
}

Configuration Message Response

{
  "success": true,
  "message": "Configuration message retrieved",
  "configuration_id": 12,
  "configuration_name": "Config 12",
  "config_unique_key": "2f7c1f7e...dc5a2d8b",
  "config_message": "Welcome to [config_name]. Updated: [updated_at]. Servers: [server_list]"
}

Server and Tweak Mutation Response

{
  "success": true,
  "message": "Configuration resources synced",
  "configuration_id": 12,
  "configuration_name": "Config 12",
  "config_unique_key": "2f7c1f7e...dc5a2d8b",
  "summary": {
    "servers_created": 0,
    "servers_updated": 1,
    "servers_deleted": 1,
    "tweaks_created": 0,
    "tweaks_updated": 0,
    "tweaks_deleted": 1
  },
  "servers": [
    {
      "action": "updated",
      "id": 2,
      "unique_key": "8bcb3c4f...7b6c4a12",
      "name": "Main SSH Server v2",
      "category": "Free",
      "tunnel_type": "ssh"
    },
    {
      "action": "deleted",
      "id": 3,
      "unique_key": "9f2a6d90...7a7b91d1",
      "name": "Backup SSH Server",
      "category": null,
      "tunnel_type": "ovpn_udp"
    }
  ],
  "tweaks": [
    {
      "action": "deleted",
      "id": 4,
      "unique_key": "6e1d2f8c...d5ce0d62",
      "name": "Default Tweak",
      "category": "Free",
      "tunnel_type": "ovpn_tcp_ssh",
      "bug_host": null
    }
  ]
}

Cloud Device ID List Response

{
  "success": true,
  "message": "Device IDs listed",
  "configuration_id": 12,
  "config_unique_key": "2f7c1f7e...dc5a2d8b",
  "device_ids": [
    {
      "id": 31,
      "device_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "note": "Batch import",
      "is_active": true,
      "delete_after_used": false,
      "expire_date": "2031-02-03",
      "created_at": "2026-02-24 18:30:00",
      "updated_at": "2026-02-24 18:30:00"
    }
  ]
}

Cloud Device ID Create Response

{
  "success": true,
  "message": "2 Device IDs added.",
  "configuration_id": 12,
  "config_unique_key": "2f7c1f7e...dc5a2d8b",
  "added_count": 2,
  "device_ids": [
    {
      "id": 31,
      "device_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
      "note": "Batch import",
      "is_active": true,
      "delete_after_used": false,
      "expire_date": "2031-02-03",
      "created_at": "2026-02-24 18:30:00",
      "updated_at": "2026-02-24 18:30:00"
    },
    {
      "id": 32,
      "device_id": "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
      "note": "Batch import",
      "is_active": true,
      "delete_after_used": false,
      "expire_date": "2031-02-03",
      "created_at": "2026-02-24 18:30:00",
      "updated_at": "2026-02-24 18:30:00"
    }
  ]
}

Cloud Password Create Response

{
  "success": true,
  "message": "Password added.",
  "configuration_id": 12,
  "config_unique_key": "2f7c1f7e...dc5a2d8b",
  "added_count": 1,
  "passwords": [
    {
      "id": 45,
      "password": "Secret123",
      "type": "one_time",
      "note": null,
      "is_active": true,
      "delete_after_used": true,
      "expire_date": "2032-04-05",
      "used_device_id": null,
      "used_at": null,
      "created_at": "2026-02-24 18:32:00",
      "updated_at": "2026-02-24 18:32:00"
    }
  ]
}

Error Codes