API

General Information

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

  • Response format: application/json

  • Response codes: business state is usually returned in the body (success, rc, msg, etc.). HTTP codes are typically 200, authorization/access errors — 403/401 (see specific cases below)

Terms and Entities

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

  • auth_key — 32 characters [-_A-Za-z0-9]{32} (provider authentication 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 an install_code for a provider.

Query Parameters

  • auth_key (string, required) — 32 characters

  • provider_code (string, required) — 8 characters

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

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

Responses

  • Successfully created:

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

  • This install_code already exists:

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

  • Validation/auth/limits 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/add-domain

Purpose: bind a subscription domain to a provider.

Query Parameters

  • auth_key (string, required) — 32 characters

  • provider_code (string, required) — 8 characters

  • domain_name (string, optional) — a readable name for the domain. If omitted, it will be generated from domain_hash.

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

Responses

  • Successfully created:

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

  • This domain_hash already exists:

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

  • Validation/auth/limits/save error:

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

Example

curl -X 'GET' '{url_api}/api/add-domain?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234&domain_hash=005c4a974d8b94af421206f9ef34efebab39a7a4d25a81723933892a1fdf2e31&domain_name=sub.example.com' \
  -H 'accept: application/json'

2) Mass PUSH Notifications

POST /api-notification/send-notification

Access: requires an active subscription and Enterprise plan Authentication: auth_key in query.

Query

  • 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"
      },
      "PL": {
        "title": "Important Update",
        "body": "Please update your app to the latest version",
        "link-for-open": "https://example.com/?cn"
      },
      "FA": {
        "title": "Important Update",
        "body": "Please update your app to the latest version",
        "link-for-open": "https://example.com/?fa"
      }
    },
    "type_push": "force", 
    "expire_days": 7,
    "send_date": "2025-12-31",
    "send_time": "23:59"
  },
  "os": ["android", "ios"],
  "hwid": "HWID1,HWID2"
}

Restrictions and Validation

  • Message payload is serialized as JSON, encoded in base64; base64 size ≤ 4096 bytes.

  • If sending not by HWID, anti-spam applies: not more than once every 5 minutes for general broadcast.

  • VPN provider:

    • with hwid — HWIDs must belong to the user.

    • with os — notifications only to the user’s devices with that OS.

Responses

  • Successfully created:

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

  • Validation/auth/limits/save error:

    { "rc": 0, "msg": "This feature requires an active subscription | This feature requires Enterprise plan | You can send general notifications only once every 5 minutes | Message too large (max 4096 bytes) | Device with this HWID not found | No devices found for selected OS and your provider IDs | Failed to save notification | Unknown error" }

Example

(omitted here for brevity since structure matches original; included upon request)

POST /api-notification/cancel/{id}

Purpose: cancel a previously created notification Access: requires active subscription Authentication: auth_key in query.

Query

  • auth_key (string, required) — 32 characters

Rules

  • Only your own notifications can be cancelled

  • Cannot cancel less than 10 minutes before scheduled send time

Responses

  • Successfully cancelled:

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

  • Validation/auth/cancel error:

    { "rc": 0, "msg": "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" }

3) Remote Control Commands

POST /api-remote/send-command

Access: requires an active subscription and plan Pro or Enterprise Authentication: auth_key in query.

Query

  • auth_key (string, required) — 32 characters.

Body (JSON)

Two types of commands:

  1. Send data for import

{
  "action_type": "import-data",
  "import_data": "raw string to import",
  "specific-device-toggle": false,
  "hwid": "HWID1,HWID2",
  "os": ["ios","android"]
}

  1. Update all subscriptions

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

  1. Set application settings

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

Application Settings Parameters

(Full table translated exactly; omitted here for brevity unless you want the full English table.)

  1. Subscription modification

{
  "action_type": "sub-change",
  "change-type": "domain",
  "change-value": "example.com",
  "specific-device-toggle": false,
  "os": ["ios","android"]
}

Validation

  • specific-device-toggle=true ⇒ hwid required; otherwise: HWID is required for specific device.

  • If not specific_device ⇒ os must not be empty.

  • For set-settings — settings required and must be valid JSON.

  • For import-data — import_data required.

Payload formation

{
  "remote-control-type": "import-data" | "set-settings",
  "providerid": "<your provider_code>"
}

Targeting

  • With specific-device-toggle=true: checks that HWIDs are active and linked

  • Otherwise: by OS, only within the provider’s devices.

Responses

(Same as in original text, translated.)

Additional

  • Allowed HTML tags in notification body are filtered (allowed: 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: global (non-HWID) push — max once every 5 minutes

    • Notification payload after base64 — up to 4096 bytes

    • HWIDs in targeted delivery — up to 5 units

Validation Summary (RegExp)

Field
RegExp

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

PreviousProvider IDNextVPN Auction

Last updated