Pushes

Version date: 20 December 2024

---

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

  • Endpoints

  • Create a Push

  • Bind Pushes to a Scheduler

  • 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

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

{
  "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.

---

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

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 and smart weekly 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

---

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.