API

API Documentation

Overview

• API URL: <https://happ-proxy.com> (relative paths are used below)

• Response Format: application/json

• Response Codes: HTTP code 200. The result of the request is provided in the rc and msg fields of the response body.

Terms and Entities

• provider_code — 8 characters [A-Za-z0-9]{8} (Provider ID).

• auth_key — 32 characters [-_A-Za-z0-9]{32} (Provider authorization key).

• install_code — 12 characters [A-Za-z0-9]{12} (Installation code).

• domain_hash — 64 characters [a-z0-9]{64} (SHA-256 of the subscription domain, lowercase).

---

GET /api/add-install

Purpose: Create a provider link.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• install_limit (int, required) — from 1 to 100

• install_code (string, optional) — 12 characters. If not provided, it will be automatically generated.

• note (string, optional) — 255 characters

Responses

• Success:

  { "rc": 1, "msg": "Ok", "install_code": "ABCDEF123456", "id": 33 }

• install_code already exists:

  { "rc": 2, "msg": "Install code exists" }

• Validation/Authorization/Limit error:

  { "rc": 0, "msg": "Auth error | Install limit error | Max install code created | Unknown error" }

Example

curl -X 'GET' '{url_api}/api/add-install?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234&install_limit=10' \
  -H 'accept: application/json'

---

GET /api/update-install

Purpose: Modify a provider link.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• id (number, required)

• install_limit (int, optional) — from 1 to 100. If not specified, the value remains unchanged. Cannot be less than the current install_count.

• note (string, optional) — 255 characters. If not specified, the value remains unchanged.

• status (int, optional) — 5 (Disabled) / 10 (Active). If not specified, the value remains unchanged.

Responses

• Success:

  { "rc": 1, "msg": "Ok", "install_code": "ABCDEF123456" }

• Validation/Authorization/Limit error:

  { "rc": 0, "msg": "Auth error | Install limit error | Install status error | Error save install | Install not found | Unknown error" }

Example

curl -X 'GET' '{url_api}/api/update-install?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234&id=33&status=10' \
  -H 'accept: application/json'

---

GET /api/list-install

Purpose: Retrieve a list of provider links.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• id (number, optional) — If not provided, returns the last 5000 records.

Responses

• Success:

  { "rc": 1, "msg": "Ok", 
    "data": [
      {
        "id": 1,
        "install_code": "INSTALLCODE1",
        "install_limit": 100,
        "install_count": 43,
        "status": 10,
        "note": null,
        "created_at": "2025-02-18 18:03:54"
      }, 
      {
        "id": 2,
        "install_code": "INSTALLCODE2",
        "install_limit": 100,
        "install_count": 100,
        "status": 10,
        "note": "Note",
        "created_at": "2025-02-18 18:05:54"
      } 
    ] 
  }

  • status values:

    • 5 — Disabled

    • 10 — Active

• Validation/Authorization error:

  { "rc": 0, "msg": "Auth error | Unknown error" }

Example

curl -X 'GET' '{url_api}/api/list-install?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234' \
  -H 'accept: application/json'

---

GET /api/list-hwid

Purpose: Retrieve a list of HWIDs associated with a provider link.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• install_code (string, required) — Required if install_id is not provided.

• install_id (number, required) — Required if install_code is not provided.

• hwid (string, optional) — If not provided, returns the last 5000 records.

Responses

• Success:

  { "rc": 1, "msg": "Ok", 
    "data": [
      {
        "hwid": "4998793c-3ce5-4ac9-9dfa-0ef5417b00fa",
        "date": "2025-07-23 13:38:02",
        "device_name": "DESKTOP-4C6OAQN_x86_64"
      },
      {
        "hwid": "890877189e13ca8b",
        "date": "2025-05-15 13:41:49",
        "device_name": "SM-A528B"
      }
    ] 
  }

• Validation/Authorization error:

  { "rc": 0, "msg": "Auth error | Install code error | Unknown error" }

---

GET /api/delete-hwid

Purpose: Delete an HWID from a provider link.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• install_code (string, required) — Required if install_id is not provided.

• install_id (number, required) — Required if install_code is not provided.

• hwid (string, required)

Responses

• Success:

  { "rc": 1, "msg": "Ok", "install_count": 42 } 

• Validation/Authorization error:

  { "rc": 0, "msg": "Auth error | Invalid parameters | Install code error | Unknown error" }

---

GET /api/add-domain

Purpose: Link a subscription domain to a provider.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• domain_name (string, optional) — Description of the domain for the domain_hash. If not provided, it will be created from domain_hash.

• domain_hash (string, required) — SHA-256 of the domain in lowercase (64 hex).

Responses

• Success:

  { "rc": 1, "msg": "Ok", "id": 33 }

• domain_hash already exists:

  { "rc": 2, "msg": "Domain hash exists | Domain hash exists. State set to active", "id": 33 }

• Validation/Authorization/Save error:

  { "rc": 0, "msg": "Auth error | Domain hash error | Unknown error | Error save domain | Error change state to active" }

---

GET /api/delete-domain

Purpose: Delete a provider domain.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• id (number, required)

Responses

• Success:

  { "rc": 1, "msg": "Ok" }

• Validation/Authorization error:

  { "rc": 0, "msg": "Auth error | Domain save error | Domain not found | Unknown error" }

---

GET /api/list-domain

Purpose: Retrieve a list of provider domains.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• id (number, optional) — If not provided, returns the last 5000 records.

Responses

• Success:

  { "rc": 1, "msg": "Ok", 
    "data": [
      {
        "id": 1,
        "domain_name": "Domain1",
        "domain_hash": "41e5e446716d7577286255aa55fd03e3420510cb85f20b8968e7010c81aa5468",
        "status": 10,
        "created_at": "2025-02-19 22:50:33"
      },
      { 
        "id": 2,
        "domain_name": "Domain2",
        "domain_hash": "e9f29ba623b30632f120a6c338ce066685492f2d4fc9544507388b70691a2f17",
        "status": 5,
        "created_at": "2025-02-19 22:50:33"
      } 
    ] 
  }

  • status values:

    • 5 — Disabled

    • 10 — Active

---

2) General Requests for PUSH Notifications and Remote Control Commands

GET /remote/cancel

Purpose: Cancel a notification or command.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• id (number, required)

Rules:

• You can only cancel your own broadcasts.

• Cancellation is not possible less than 10 minutes before the scheduled delivery time.

Responses

• Success:

  { "rc": 1, "msg": "Ok" }

• Error:

  { "rc": 0, "msg": "Auth error | This feature requires an active subscription | Notification not found | Cannot cancel notification less than 10 minutes before scheduled time | Failed to cancel notification | Unknown error" }

---

GET /remote/list

Purpose: Retrieve a list of notifications and commands.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

• id (number, optional) — ID of the notification/command. If not provided, returns the last 5000 records.

Responses

• Success:

  { "rc": 1, "msg": "Ok", 
    "data": [ 
      {
        "id": 585,
        "target_os": null,
        "target_hwid": "e2a1b20d417fdf9e",
        "status": 100,
        "created_at": "2025-11-18 23:20:22",
        "sent_at": "2025-11-18 23:21:02",
        "notification_type": 20
      },
      {
        "id": 584,
        "target_os": null,
        "target_hwid": "e2a1b20d417fdf9e",
        "status": 110,
        "created_at": "2025-11-18 23:19:24",
        "sent_at": "2025-11-18 23:20:01",
        "notification_type": 20
      }
    ] 
  }

  • status values:

    • 5 / 6 — Load

    • 10 — Created

    • 20 — Checking

    • 30 — Pending

    • 40 — Sending

    • 100 — Sent

    • 110 — Sent with errors

    • 120 — Failed

    • 130 — Cancelled

    • 140 — Blocked

  • notification_type values:

    • 10 — Push

    • 20 — Command

---

3) Bulk PUSH Notifications

POST /remote/notification

Access: Requires an active subscription and Enterprise plan.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

Simple Body (JSON)

{
  "PushNotificationForm": {
    "body": "Please update your app to the latest version",
    "type_push": "optional",
    "expire_days": 7
  },
  "os": ["android"]
}

Full Body (JSON)

{
  "PushNotificationForm": {
    "title": "Default title",
    "body": "Default body",
    "link_for_open": "https://example.com/",
    "background_image": "https://example.com/image.jpg",
    "locales": {
      "RU": {
        "title": "Важное обновление",
        "body": "Пожалуйста, обновите приложение до последней версии",
        "link-for-open": "https://example.com/?ru"
      },
      "EN": {
        "title": "Important Update",
        "body": "Please update your app to the latest version",
        "link-for-open": "https://example.com/?en"
      }
      // other locales...
    },
    "type_push": "force", // force | optional 
    "expire_days": 7,
    "send_date": "2025-12-31",
    "send_time": "23:59"
  },
  "os": ["android", "ios"], // Array of OS (if not sending by HWID)
  "hwid": "HWID1,HWID2" // String, up to 5 HWIDs separated by commas
}

Constraints and Validation

• The message body is serialized as JSON and base64 encoded; the base64 string size must be ≤ 4096 bytes.

• If sending not by specific HWIDs, anti-spam applies: no more than once every 5 minutes for "general" broadcasts.

• For VPN providers:

  • With hwid — HWIDs must belong to the provider's users.

  • With os — Broadcast only to provider's devices with the specified OS.

---

4) Remote Control Commands

POST /remote/command

Access: Requires an active subscription and Pro or Enterprise plan.

Query Parameters

• provider_code (string, required) — 8 characters

• auth_key (string, required) — 32 characters

Body (JSON)

1. Send data for import

{
  "action_type": "import-data",
  "import_data": "raw string to import", // Will be base64 encoded and passed as "input-data"
  "specific-device-toggle": false, // true if HWID is specified, otherwise false
  "hwid": "HWID1,HWID2",  // Required if specific-device-toggle=true; max 5
  "os": ["ios","android"] // Required if specific-device-toggle=false
}

1. Update all subscriptions

{
  "action_type": "update-subscription",
  "specific-device-toggle": true,
  "hwid": "HWID-ABC123"
}

1. Set Settings

{
  "action_type": "set-settings",
  "settings": { "log_level": "info", "featureX": true },
  "specific-device-toggle": true,
  "hwid": "HWID-ABC123"
}

Application Parameter Table

Parameter Name	Values
fragmentation-enable	true / false
fragmentation-packets	"tlshello" / "1-3"
fragmentation-length	Number
fragmentation-interval	Number
local-dns-enable	true / false
subscription-auto-update-enable	true / false
subscription-auto-update-open-enable	true / false
subscription-always-hwid-enable	true / false
subscription-autoconnect	true / false
subscription-ping-onopen-enabled	true / false
subscription-autoconnect-type	"lastused" / "lowestdelay"
notification-subs-expire	true / false
check-url-via-proxy	String
ping-type	"proxy" / "tcp" / "icmp"
fragmentation-type	"xray" / "advanced"
fragmentation-advanced-param	String
change-user-agent	String
app-auto-start	true / false
server-address-resolve-enable	true / false
server-address-resolve-dns-ip	String
server-address-resolve-dns-domain	String
per-app-proxy-mode	"off" / "on" / "bypass"
per-app-proxy-list	String
Custom	String

---

Additional Notes

• Allowed HTML Tags in notification body are filtered (Basic tags: a, b, big, blockquote, br, cite, del, dfn, div, em, i, img, li, p, s, small, span, strike, strong, sub, sup, tt, u, ul; allowed attributes: href, title, src, alt; target="_blank" is allowed).

• OS Values — ios, android.

• Limits:

  • send-notification: General push without hwid — no more than once every 5 minutes.

  • Notification payload after base64 — up to 4096 bytes.

  • HWIDs in targeted sends — up to 5 per request.

Validation RegExp Summary

Field	Regex
provider_code	^[A-Za-z0-9]{8}$
auth_key	^[-_A-Za-z0-9]{32}$
install_code	^[A-Za-z0-9]{12}$
domain_hash	^[a-z0-9]{64}$
install_limit	integer 1..100

Would you like me to create a Postman collection for these endpoints?