# API

## API

**General Information**

* API URL: [https://happ-proxy.com](https://happ-proxy.com/) (relative paths are used below)
* Response format: `application/json`
* Response codes: HTTP code `200`. Request execution result is provided in the `rc` and `msg` fields.

**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, in lowercase).

***

#### Create a limited link

GET `/api/add-install`

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 generated automatically
* `note` *(string, optional)* — 255 characters

Responses

* Success:

JSON

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

* This `install_code` already exists:

JSON

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

* Validation/Authorization/Limit error:

JSON

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

Example

Bash

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

***

#### Update a limited link

GET `/api/update-install`

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 `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:

JSON

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

* Validation/Authorization/Limit error:

JSON

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

Example

Bash

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

***

#### Get list of limited links

GET `/api/list-install`

Query parameters

* `provider_code` *(string, required)* — 8 characters
* `auth_key` *(string, required)* — 32 characters
* `id` *(number, optional)* — if not provided, the last 5000 records are returned

Responses

* Success:

JSON

```
{ "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:

JSON

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

Example

Bash

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

***

#### Get list of HWIDs for a limited link

GET `/api/list-hwid`

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, the last 5000 records are returned

Responses

* Success:

JSON

```
{ "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:

JSON

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

Example

Bash

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

***

#### Delete HWID from a limited link

GET `/api/delete-hwid`

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:

JSON

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

* Validation/Authorization error:

JSON

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

Example

Bash

```
curl -X 'GET' '{url_api}/api/delete-hwid?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234&install_code=INSTIDCODE01&hwid=DEVICEHWID' \
  -H 'accept: application/json'
```

***

#### Bind a subscription domain to a provider ID

GET `/api/add-domain`

Query parameters

* `provider_code` *(string, required)* — 8 characters
* `auth_key` *(string, required)* — 32 characters
* `domain_name` *(string, optional)* — description of the domain in `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:

JSON

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

* This `domain_hash` already exists:

JSON

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

* Validation/Authorization/Limit/Save error:

JSON

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

Example

Bash

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

***

#### Delete a domain from a provider ID

GET `/api/delete-domain`

Query parameters

* `provider_code` *(string, required)* — 8 characters
* `auth_key` *(string, required)* — 32 characters
* `id` *(number, required)*

Responses

* Success:

JSON

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

* Validation/Authorization error:

JSON

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

Example

Bash

```
curl -X 'GET' '{url_api}/api/delete-domain?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234&id=33' \
  -H 'accept: application/json'
```

***

#### Get list of domains for a provider ID

GET `/api/list-domain`

Query parameters

* `provider_code` *(string, required)* — 8 characters
* `auth_key` *(string, required)* — 32 characters
* `id` *(number, optional)* — if not provided, the last 5000 records are returned

Responses

* Success:

JSON

```
{ "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
* Validation/Authorization error:

JSON

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

Example

Bash

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

***

#### Common Requests for PUSH Notifications and Remote Control Commands

***

#### Cancel a notification or command

GET `/remote/cancel`

Query parameters

* `provider_code` *(string, required)* — 8 characters
* `auth_key` *(string, required)* — 32 characters
* `id` *(number, required)*

Rules:

* You can only cancel your own distribution.
* Cancellation is not allowed less than 10 minutes before the scheduled delivery time.

Responses

* Success:

JSON

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

* Validation/Authorization/Limit/Cancellation error:

JSON

```
{ "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" }
```

Example

Bash

```
curl -X GET '{url_api}/remote/cancel?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234&id=10' \
  -H 'accept: application/json' 
```

***

#### List of notifications and commands

GET `/remote/list`

Query parameters

* `provider_code` *(string, required)* — 8 characters
* `auth_key` *(string, required)* — 32 characters
* `id` *(number, optional)* — if not provided, the last 5000 records are returned

Responses

* Success:

JSON

```
{ "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
* Validation/Authorization error:

JSON

```
{ "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" }
```

Example

Bash

```
curl -X GET '{url_api}/remote/list?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234&id=10' \
  -H 'accept: application/json' 
```

***

#### Mass PUSH Notifications

***

#### Send a PUSH notification

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

Body (Simple JSON)

JSON

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

Body (Extended JSON)

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"
      },
      "CN": {
        "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

* The message body is serialized as JSON and encoded in base64; the base64 string size must be ≤ 4096 bytes.
* Anti-spam rules apply if not sending to specific HWIDs: "general" distributions are limited to once every 5 minutes.
* VPN provider:
  * with `hwid` — HWIDs must belong to the user.
  * with `os` — distribution only to the user's devices with the specified OS.

Responses

* Success:

JSON

```
{ "rc": 1, "msg": "Ok", "id": 10 }
```

* Validation/Authorization/Limit/Save error:

JSON

```
{ "rc": 0, "msg": "Auth error | 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

```bash
curl -X POST '{url_api}/remote/notification?provider_code=Ab12Cd34&auth_key=AbcdEfghIjklMnopQrstuVwxyz_1234' \
 -H 'Content-Type: application/json' \
 -d '{
 "PushNotificationForm": {
    "body": "Please update your app to the latest version",
    "type_push": "optional",
    "expire_days": 7
  },
  "os": ["android"]
 }'
```

***

#### Remote Control Commands

***

#### Send a command to a device

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 Options (JSON)

1. Send data for import

```jsonc
{
  "action_type": "import-data",
  "import_data": "raw string to import",
  "specific-device-toggle": false, //If false, it will be sent to everyone on the specified OS
  "os": ["ios","android"]
}
```

2. Update all subscriptions

```json
{
  "action_type": "update-subscription",
  "specific-device-toggle": true, //If true, then you need to specify up to 5 HWIDs
  "hwid": "HWID1,HWID2"
}
```

3. Set settings

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

App Configuration Parameters

| **Parameter Name**              | **Values**                     |
| ------------------------------- | ------------------------------ |
| `fragmentation-enable`          | `true` /`false`                |
| `fragmentation-packets`         | `"tlshello"` / `"1-3"`         |
| `local-dns-enable`              | `true` /`false`                |
| `subscription-autoconnect`      | `true` /`false`                |
| `subscription-autoconnect-type` | `"lastused"` / `"lowestdelay"` |
| `ping-type`                     | `"proxy"` / `"tcp"` / `"icmp"` |
| `per-app-proxy-mode`            | `"off"` / `"on"` / `"bypass"`  |

4. Change subscription

```json
{
  "action_type": "sub-change",
  "change_type": "domain", // domain | url 
  "change_value": "example.com",
  "specific-device-toggle": false,
  "os": ["ios","android"]
}
```

Validation

* If `specific-device-toggle=true` ⇒ `hwid` is required.
* If not `specific-device-toggle`, then `os` must not be empty.
* For `set-settings` — `settings` is required and must be valid JSON.

Responses

* Success:

```json
{ "rc": 1, "msg": "Ok", "id": 10 }
```

* Validation/Authorization error:

```json
{ "rc": 0, "msg": "Auth error | This feature requires an active subscription | HWID is required for specific device | Select at least one OS | Unknown error" }
```

***

Additional Information

* Allowed HTML 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`.
* OS values: `ios`, `android`.

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}$`      |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.happ-proxy.com/getting-started/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.