API Docs

Authentication

Provide the client API key with one of the following methods:

• X-API-Key: your_api_key (recommended)
• X-Client-Api-Key: your_api_key
• api_key in request body (POST/PUT/PATCH only)

Use headers for GET/DELETE requests. Many clients and proxies ignore request bodies for those methods.

Resources

Use resource endpoints for config, server, tweak, cloud device ID, and cloud password operations.

Configuration

Behavior

• List configs via GET /api/v1/configs.
• Sync resources to an existing config via POST /api/v1/configs with config_unique_key.
• Create configurations in Panel manually, then manage servers/tweaks/access resources via API.
• Config metadata fields such as password, update_url, and lock toggles are managed in Panel.

Request Schema

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

Cloud Access endpoints manage Access-tab resources: 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

• 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.
• 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 limits are enforced for device IDs and passwords per configuration.
• Account limits are enforced for configurations, servers, tweaks, device IDs, and passwords.

Examples

For readability, UUID-like keys below are shortened with .... In real requests, send the full key value.

List All Configs

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

List Servers/Tweaks of Config

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

Create 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",
    "tunnel_type": "ssh",
    "ip_port_user_pass": "1.2.3.4:22@user:pass"
  }'

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",
    "ip_port_user_pass": "1.2.3.4:22@user:newpass"
  }'

Create 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",
    "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
  }'

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
  }'

Remove Server

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

Remove Tweak

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

Responses

List Configs Body

{
  "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,
      "created_at": "2026-02-20 09:00:00",
      "updated_at": "2026-02-20 09:10:00"
    }
  ]
}

List Config Resources Body

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

Mutation Body (Server/Tweak Create, Update, Delete)

{
  "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",
      "tunnel_type": "ssh"
    },
    {
      "action": "deleted",
      "id": 3,
      "unique_key": "9f2a6d90...7a7b91d1",
      "name": "Backup SSH Server",
      "tunnel_type": "ovpn_udp"
    }
  ],
  "tweaks": [
    {
      "action": "deleted",
      "id": 4,
      "unique_key": "6e1d2f8c...d5ce0d62",
      "name": "Default Tweak",
      "tunnel_type": "ovpn_tcp_ssh"
    }
  ]
}

Cloud Access List Body (Device IDs)

{
  "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,
      "created_at": "2026-02-24 18:30:00",
      "updated_at": "2026-02-24 18:30:00"
    }
  ]
}

Cloud Access Mutation Body (Password Create)

{
  "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,
      "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