> For the complete documentation index, see [llms.txt](https://docs.mpush.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mpush.cloud/api/topics.md).

# Topics

{% hint style="info" %}
This section describes APIs to add devices to MPush and associate them with topics. Only clients (e.g. apps) should implement these APIs or use mobile SDKs.
{% endhint %}

### Add Device <a href="#add-device" id="add-device"></a>

```php
curl https://app.mpush.cloud/api/tokens
-X POST
-H "Accept: application/json" 
-H "Content-Type: application/json"
-H "X-MPush-Token: <token>" 
-H "X-MPush-Version: 2"
-d <data>
```

To register a new device token.

This API requires a **JSON payload**.

#### HTTP Request <a href="#http-request" id="http-request"></a>

`POST https://app.mpush.cloud/api/tokens`

Payload example to register a device to 3 topics:

```php
{
  "token": "<token>",
  "platform": "ios",
  "device_id": "<device ID>"
}
```

#### Parameters <a href="#parameters" id="parameters"></a>

| Name       | Type   | Required | Description                                                                      |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------- |
| token      | string | Yes      | Specify token device obtained from APNS and FCM.                                 |
| platform   | string | Yes      | Specify the device platform. Values are *ios* and *android*.                     |
| device\_id | string | Yes      | Specify the unique device ID. It's used to update the *token* in case of change. |

On success is returned an HTTP 200 and JSON like this:

```php
{
  "status_code": 0
}
```

### Register <a href="#register" id="register"></a>

```php
curl https://app.mpush.cloud/api/register
-X POST
-H "Accept: application/json" 
-H "Content-Type: application/json"
-H "X-MPush-Token: <token>" 
-H "X-MPush-Version: 2"
-d '<JSON payload>' 
```

To register a device to one or more topics.

A topic can represent either a device or a list of devices, you can specify it through the`single`parameter. If the specified topic doesn't exist it will be created.

This API requires a **JSON payload**.

#### HTTP Request <a href="#http-request_1" id="http-request_1"></a>

`POST https://app.mpush.cloud/api/register`

Payload example to register a device to 3 topics:

```php
{
  "topics": [
    {
      "code": "all",
      "title": "All Users",
      "single": false,
    },
    {
      "code": "ios",
      "title": "iOS Users",
      "single": false,
    },
    {
      "code": "user.1",
      "title": "User 1",
      "single": true,
    },
  ],
  "device_id": "<device ID>"
}
```

#### Parameters (JSON) <a href="#parameters-json" id="parameters-json"></a>

| Key        | Type   | Required | Description                                              |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| topics     | array  | Yes      | Contains a list of all topics to register the device to. |
| device\_id | string | Yes      | Specify the unique device ID.                            |

On success is returned an HTTP 200 and JSON like this:

```php
{
  "status_code": 0
}
```

### Unregister <a href="#unregister" id="unregister"></a>

```php
curl https://app.mpush.cloud/api/unregister
-X POST
-H "Accept: application/json" 
-H "Content-Type: application/json"
-H "X-MPush-Token: <token>" 
-H "X-MPush-Version: 2"
-d '<JSON payload>' 
```

To unregister a device from one or more topics.

If the specified topic doesn't exist it will be ignored.

This API requires a **JSON payload**.

#### HTTP Request <a href="#http-request_2" id="http-request_2"></a>

`POST https://app.mpush.cloud/api/unregister`

Payload example to unregister a device from 2 topics (old version):

```php
{
  "topics": ["all", "ios"],
  "device_id": "<device ID>"
}
```

Payload example to unregister a device from 2 topics (new version):

```php
{
  "topics": [
    {
      "code": "all",
    },
    {
      "code": "ios",
    }
  ],
  "device_id": "<device ID>"
}
```

#### Parameters (JSON) <a href="#parameters-json_1" id="parameters-json_1"></a>

| Key        | Type   | Required | Description                                              |
| ---------- | ------ | -------- | -------------------------------------------------------- |
| topics     | array  | Yes      | Contains a list of all topics to register the device to. |
| device\_id | string | Yes      | Specify the unique device ID.                            |

On success is returned an HTTP 200 and JSON like this:

```php
{
  "status_code": 0
}
```

### Unregister All <a href="#unregister-all" id="unregister-all"></a>

```php
curl https://app.mpush.cloud/api/unregister-all
-X POST
-H "Accept: application/json" 
-H "Content-Type: application/json"
-H "X-MPush-Token: <token>" 
-H "X-MPush-Version: 2"
-d '<JSON payload>' 
```

To unregister a device from all topics.

This API requires a **JSON payload**.

#### HTTP Request <a href="#http-request_3" id="http-request_3"></a>

`POST https://app.mpush.cloud/api/unregister-all`

Payload example to unregister a device from all topics:

```php
{
  "device_id": "<device ID>"
}
```

#### Parameters (JSON) <a href="#parameters-json_2" id="parameters-json_2"></a>

| Key        | Type   | Required | Description                   |
| ---------- | ------ | -------- | ----------------------------- |
| device\_id | string | Yes      | Specify the unique device ID. |

On success is returned an HTTP 200 and JSON like this:

```php
{
  "status_code": 0
}
```