# Application groups

Version date: 22 April 2025

***

> To authorize, you need to add the header `"Authorization: Bearer ..."` (get your API KEY in your personal account on "Personal" tab).

## Endpoints

* [Create an Application Group](#create-an-application-group)
* [List Application Groups](#list-application-groups)
* [Get an Application Groups](#get-an-application-groups)
* [Archive an Application Group](#archive-an-application-group)
* [Delete an Application Group](#delete-an-application-group)
* [Restore an Application Group](#restore-an-application-group)
* [Update an Application Group](#update-an-application-group)

***

### Create an Application Group

**POST** `https://core.push.express/api/b/v2/app/groups`

* **Description**: Creates a new application group.

Request:

```bash
curl --url "https://core.push.express/api/b/v2/app/groups"
    --request POST
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
    "app_ids": [25328,25329,25330,25331],
    "name": "appGroupName",
    "all_apps": false,
'
```

Body params:

* `app_ids`, *required*. If all\_apps = flash, you will definitely need to send the application ID.
* `name`, *required*. Application group name, any printable characters.
* `all_apps`, *required*. If true, the group will consist of all active applications. In this case, the app\_ids parameter can be left empty..

Response:

* 201: New application group created

```json
{"id":12345}
```

* `id`, *int*. ID of newly created application group.

***

### List Application Groups

**GET** `https://core.push.express/api/b/v2/app/groups`

* **Description**: Retrieves a list of all application groups

> No more then 10000 records can be returned

Request

```bash
curl --url "https://core.push.express/api/b/v2/app/groups?archived=false"
    --request GET
    --header "Authorization: Bearer ..."
```

Query parameters:

* `archived`, *bool, optional*. Filters archived application groups if *true*, otherwise returns active application groups.

Response:

* 200: List of application groups retrieved

```json
{
"app_groups": [
    {
        "id": 1443,
        "app_ids": [25328,25329,25330,25331],
        "name": "appGroupName",
        "all_apps": false,
        "archived": false
    },
    ...
],
}
```

* `id`, *int*. ID of application group for API.
* `app_ids`, *string*. ID of applications in group.
* `name`, `all_apps` see [Create an Application Group](#create-an-application-group).
* `archived`, *bool*. *True* if application group archived, *false* otherwise.

  **Pagination:**

Now supports one type of pagination:

1. **Page-based pagination** - for UI with numbered pages (limited to 10K records).

**Page-based**

Request

```bash
curl --url "https://core.push.express/api/b/v2/app/groups?page=2&per_page=50"
    --request GET
    --header "Authorization: Bearer ..."
```

Query parameters:

* `page`, *int, optional*. Page number.
* `per_page`, *int, optional*. The number of entries per page.

````

Response:
```json
{
 "app_groups": [
    {
        "id": 1443,
        "app_ids": [25328,25329,25330,25331],
        "name": "appGroupName",
        "all_apps": false,
        "archived": false
    },
    ...
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total_pages": 15,
    "total_count": 705
  }
}
````

* `pagination`, *object*. Pagination metadata.
* `pagination.page`, *int*. Current page number.
* `pagination.per_page`, *int*. Records per page.
* `pagination.total_pages`, *int*. Total number of pages.
* `pagination.total_count`, *int*. Total matching records.

**Limit:** Max offset = 10,000 records. UI with numbered pages \[1] \[2] \[3]. Small/medium datasets.

***

### Get an Application Group

**GET** `https://core.push.express/api/b/v2/app/groups/:app_group_id`

* **Description**: Retrieves details of a specific application group by its ID.

Request

```bash
curl --url "https://core.push.express/api/b/v2/app/groups/:app_group_id"
    --request GET
    --header "Authorization: Bearer ..."
```

Response:

* 200: Application group info retrieved

```json
{
    "id": 1443,
    "app_ids": [25328,25329,25330,25331],
    "name": "appGroupName",
    "all_apps": false,
    "archived": false
}
```

Details on response can see in [List Application Groups](#list-application-groups)

***

### Archive an Application Group

**POST** `https://core.push.express/api/b/v2/app/groups/:app_group_id/archive`

* **Description**: Archives a specific application group by its ID. This actions is idempotent, i.e. double archiving is valid.

Request

```bash
curl --url "https://core.push.express/api/b/v2/app/groups/:app_group_id/archive"
    --request POST
    --header "Authorization: Bearer ..."
```

Response:

* 204: No content

***

### Delete an Application Group

**DELETE** `https://core.push.express/api/b/v2/app/groups/:app_group_id`

* **Description**: Deletes a specific application group by its ID.

Request

```bash
curl --url "https://core.push.express/api/b/v2/app/groups/:app_group_id/archive"
    --request DELETE
    --header "Authorization: Bearer ..."
```

Response:

* 204: No content

> If an application group has successfully been deleted then it was automatically removed from all schedulers.

***

### Restore an Application Group

**POST** `https://core.push.express/api/b/v2/apps/:app_group_id/unarchive`

* **Description**: Restores a specific application group by its ID. This actions is idempotent, i.e. double unarchiving is valid.

Request

```bash
curl --url "https://core.push.express/api/b/v2/app/groups/:app_group_id/unarchive"
    --request POST
    --header "Authorization: Bearer ..."
```

Response:

* 204: No content

***

### Update an Application Group

**PUT** `https://core.push.express/api/b/v2/app/groups/:app_group_id`

* **Description**: Updates the base information of a specific app by its ID.

Request:

```bash
curl --url "https://core.push.express/api/b/v2/app/groups/:app_group_id"
    --request PUT
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
    "app_ids": [25329,25330],
    "name": "test",
    "all_apps": false
}
'
```

Response:

* 204: No content

***

## Error handling

All HTTP response codes 2xx SHOULD be considered as success. Requested action was executed successfully.

All HTTP response codes above 400 MUST be considered as error. Requested action failed. Retries policy should be hold according to HTTP specification.

Common API errors:

* 400 - request error. Request has invalid data. Check you request (url, headers, payload)
* 401 is returned when provided API token is invalid. Check your authentification data.
* 404 is returned when resource doesn't exist. Check your request data.

  Example: **PUT** `https://core.push.express/api/b/v2/app/groups/:app_group_id` returns 404 when provided `app_group_id` doesn't exist
* All HTTP response codes 5xx - other errors from proxy servers, load balancers, etc. There may or may not have some explanation in response body. These errors always require retries.

**API errors** have `content-type: application/json` header and json response body

Example: `{"error": "validation error: ...", "req_id":"<string>"}`

Response parameters:

* `req_id` *string* is a request ID. It is used by support for problem solving, please, provide it to support if problem emerged.
* `error` object, describing errors.

**Non-API errors** like 502, 504, etc., may or may not include a description.