# Pushes

Version date: 27 January 2026

***

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

## Endpoints

* [PushExpress -- pushes API reference](#pushexpress----pushes-api-reference)
  * [Endpoints](#endpoints)
  * [Create a Push](#create-a-push)
  * [Update a Push](#update-a-push)
  * [Delete a Push](#delete-a-push)
  * [Activate a Push](#activate-a-push)
  * [Deactivate a Push](#deactivate-a-push)
  * [Bind Pushes to a Scheduler](#bind-pushes-to-a-scheduler)
  * [Get a Push](#get-a-push)
  * [Error handling](#error-handling)

***

## Create a Push

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

* **Description**: Creates a new push. Each push must have at least 1 translation. In the moment of sending PushExpress choses which translation is to be sent according to device language. If push does not have translation for current devices then default language translation is sent.

Request

```bash
curl --url "https://core.push.express/api/b/v2/pushes"
    --request POST
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
  "default_lang": "en",
  "translations": [
    {
      "language": "en",
      "title": "Title Of My Push",
      "text": "Text of my push",
      "image": "link-to/image/for.my.push",
      "icon": "link-to/icon/for.my.push",
      "link": "link-for.my.push"
    },
    {
      "language": "pt",
      "title": "Título do meu push",
      "text": "Texto do meu push"
    },
    ...
  ]
}
```

Body params:

* `default_lang`, *required*. Must be 2-digit language code. Follow bcp47 standard. This language will be chosen for devices with languages not mentioned in
* `translations`, *required*. List of translations for this push. Must include translation for language set by `default_lang` parameter.
* `language`, *required*. Must be 2-digit language code. Follow bcp47 standard.
* `title`, *required*. This is a short text in the head of notification.
* `text`, *required*. This is a longer text under the title.
* `image`, *optional*. An image to be shown in push body.
* `icon`, *optional*. An icon to be shown in push preview.
* `link`, *optional*. Link to be followed when user clicks on push.

Response:

* 201: New push with translations created

```json
{
  "id": 12345,
  "translations": [
    {
      "id": 111,
      "language": "en"
    },
    {
      "id": 222,
      "language": "pt"
    },
    ...
  ]
}
```

* `id`, *int*. ID of newly created push.
* `translations`, *object*. List of translations created.

> If you want to send some push via scheduler you should first create push and then bind it to some scheduler. Newly created push is not attached to any scheduler.

***

## Update a Push

**PUT** `https://core.push.express/api/b/v2/pushes/:push_id`

* **Description**: Updates an existing push notification. All translations will be replaced with new ones provided in the request. The push must belong to the authenticated user.

Request

```bash
curl --url "https://core.push.express/api/b/v2/pushes/:push_id"
    --request PUT
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
  "default_lang": "en",
  "translations": [
    {
      "language": "en",
      "title": "Updated Title",
      "text": "Updated text content",
      "image": "link-to/updated-image.jpg",
      "icon": "link-to/updated-icon.jpg",
      "link": "updated-link.com"
    },
    {
      "language": "de",
      "title": "Aktualisierter Titel",
      "text": "Aktualisierter Textinhalt"
    }
  ]
}
```

URL params:

* `push_id`, *int*. ID of the push to update.

Body params:

* `default_lang`, *required*. Must be 2-digit language code. Follow bcp47 standard.
* `translations`, *required*. List of translations for this push. Must include translation for language set by `default_lang` parameter.
* `language`, *required*. Must be 2-digit language code. Follow bcp47 standard.
* `title`, *required*. This is a short text in the head of notification.
* `text`, *required*. This is a longer text under the title.
* `image`, *optional*. An image to be shown in push body.
* `icon`, *optional*. An icon to be shown in push preview.
* `link`, *optional*. Link to be followed when user clicks on push.

Response:

* 204: Push successfully updated, no content returned
* 404: Push not found or doesn't belong to user
* 400: Validation error (e.g., duplicate language codes, missing default language translation)

***

## Delete a Push

**DELETE** `https://core.push.express/api/b/v2/pushes/:push_id`

* **Description**: Deletes a push notification and all its translations. The push must belong to the authenticated user. This action cannot be undone.

Request

```bash
curl --url "https://core.push.express/api/b/v2/pushes/:push_id"
    --request DELETE
    --header "Authorization: Bearer ..."
```

URL params:

* `push_id`, *int*. ID of the push to delete.

Response:

* 204: Push successfully deleted, no content returned
* 404: Push not found or doesn't belong to user

***

## Activate a Push

**POST** `https://core.push.express/api/b/v2/pushes/:push_id/activate`

* **Description**: Activates a push notification, making it eligible for sending. The push must belong to the authenticated user.

Request

```bash
curl --url "https://core.push.express/api/b/v2/pushes/:push_id/activate"
    --request POST
    --header "Authorization: Bearer ..."
```

URL params:

* `push_id`, *int*. ID of the push to activate.

Response:

* 204: Push successfully activated, no content returned
* 404: Push not found or doesn't belong to user

***

## Deactivate a Push

**POST** `https://core.push.express/api/b/v2/pushes/:push_id/deactivate`

* **Description**: Deactivates a push notification, preventing it from being sent. The push must belong to the authenticated user. Deactivated pushes can be reactivated later.

Request

```bash
curl --url "https://core.push.express/api/b/v2/pushes/:push_id/deactivate"
    --request POST
    --header "Authorization: Bearer ..."
```

URL params:

* `push_id`, *int*. ID of the push to deactivate.

Response:

* 204: Push successfully deactivated, no content returned
* 404: Push not found or doesn't belong to user

***

## Bind Pushes to a Scheduler

**PUT** `https://core.push.express/api/b/v2/sched/:sched_type/:sched_id/pushes`

* **Description**: Binds a list of pushes \[]P to scheduler S with unbinding all pushes previously bound to S. If S already had any pushes attached they all will be unattached. You can only bind pushes P that are not attached to any other scheduler.

Request

```bash
curl --url "https://core.push.express/api/b/v2/sched/:sched_type/:sched_id/pushes"
    --request PUT
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
    "push_ids": [123, 234, ...]
}
```

URL params:

* `sched_type`, *string*, only **onesend** value = 'onesend' and **smart weekly** value = 'list' available now. This is a type of scheduler pushes are to be bound to.
* `sched_id`, *int*. This is an ID of scheduler pushes are to be bound to.

Body params:

* `push_ids`, *required*. A list of push IDs to be bound to scheduler. All of them must not be attached to any other scheduler to execute binding. If an empty list is provided then all pushes previously bound to scheduler become unbound and no new pushes are attached to scheduler. Null value is prohibited.

Response:

* 204: No content

***

## Get a Push

**GET** `https://core.push.express/api/b/v2/pushes/:push_id`

* **Description**: Retrieves details of a specific push notifications by its ID.

Request

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

Response:

* 201: New push with translations created

```json
{
  "id": 484772,
  "shed_id": 0,
  "archived": false,
  "default_lang": "en",
  "translations": [
    {
      "id": 4019723,
      "language": "en",
      "title": "Title Of My Push",
      "text": "Text of my push",
      "image": "",
      "icon": "",
      "link": ""
    },
    {
      "id": 4019724,
      "language": "pt",
      "title": "Título do meu push",
      "text": "Texto do meu push",
      "image": "",
      "icon": "",
      "link": ""
    }
  ]
}
```

***

## 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.
* 403 is returned when access to resource for current user is denied.
* 404 is returned when resource doesn't exist. Check your request data.

  Example: **PUT** `https://core.push.express/api/b/v2/sched/:sched_type/:sched_id/pushes` returns 404 when provided `sched_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.