---
title: "Notifications"
description: "Compose, send, schedule, and read notifications for one app and environment. These routes use a workspace server API key."
canonical: https://docs.notifiable.sh/api/notifications
source: https://docs.notifiable.sh/api/notifications.md
---

# Notifications

Compose, send, schedule, and read notifications for one app and environment. These routes use a workspace server API key.

These routes are the public API. Send `Authorization: Bearer` with a workspace server API key. The key can act on every app in the workspace. A route that names an app uses that app id. `environment` is `development` or `production`.

## `GET /api/v1/public/apps/{app}/environments/{environment}/notifications`

The notifications were listed.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.

Responses

- `200` `NOTIFICATIONS_LISTED` — The notifications were listed.
  - `page` (integer, required)
  - `per_page` (integer, required)
  - `total` (integer, required)
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `APP_NOT_FOUND` — The app could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `POST /api/v1/public/apps/{app}/environments/{environment}/notifications`

The notification was accepted.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.

Body

- `title` (string, required) — Notification title. Required. At most 200 characters.
- `body` (string, required) — Notification message. Required. At most 1000 characters.
- `url` (string, optional) — Optional address opened when the notification is tapped. At most 2048 characters.
- `image_url` (uri, optional) — Optional image URL. At most 2048 characters.
- `data` (array of string, optional) — Optional object of up to 20 short keys and simple values.
- `alert` (boolean, optional) — Whether the notification shows an alert. Defaults to true.
- `audience_type` (`all`, `segment`, `subscriber`, `event`, required)
- `audience_id` (string, optional) — Segment id when audience_type is segment. Event name when audience_type is event.
- `subscriber_id` (uuid, optional) — Subscriber id. Required when audience_type is subscriber.
- `intent` (`draft`, `send`, `schedule`, required) — draft, send, or schedule.
- `timezone_strategy` (optional)
- `scheduled_at` (date-time, optional) — UTC time. Required when intent is schedule.
- `idempotency_key` (string, optional) — Optional key, at most 80 characters. The same key in this app and environment returns the notification already accepted.

Responses

- `201` `NOTIFICATION_ACCEPTED` — The notification was accepted.
  - `id` (string, required)
  - `title` (string, required)
  - `body` (string, required)
  - `audience` (string, required)
  - `audience_type` (string, required)
  - `targeted` (integer, required)
  - `delivered` (integer, required)
  - `failed` (integer, required)
  - `skipped` (integer, required)
  - `url` (string, required)
  - `image_url` (string, required)
  - `data` (object, required)
- `200` `NOTIFICATION_ACCEPTED` — The notification was accepted.
  - `id` (string, required)
  - `title` (string, required)
  - `body` (string, required)
  - `audience` (string, required)
  - `audience_type` (string, required)
  - `targeted` (integer, required)
  - `delivered` (integer, required)
  - `failed` (integer, required)
  - `skipped` (integer, required)
  - `url` (string, required)
  - `image_url` (string, required)
  - `data` (object, required)
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `APP_NOT_FOUND` — The app could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `POST /api/v1/public/apps/{app}/environments/{environment}/notifications/images`

The image was stored.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.

Responses

- `201` `IMAGE_STORED` — The image was stored.
  - `url` (string, required)
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `APP_NOT_FOUND` — The app could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `POST /api/v1/public/apps/{app}/environments/{environment}/notifications/preview`

The audience was counted.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.

Body

- `audience_type` (string, required)
- `audience_id` (string, optional)
- `subscriber_id` (uuid, optional)

Responses

- `200` `NOTIFICATION_PREVIEWED` — The audience was counted.
  - `name` (string, required)
  - `audience` (integer, required)
  - `reachable` (integer, required)
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `APP_NOT_FOUND` — The app could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `GET /api/v1/public/apps/{app}/environments/{environment}/notifications/recipients`

The recipients were listed.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.

Query

- `search` (string)

Responses

- `200` `RECIPIENTS_LISTED` — The recipients were listed.
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `APP_NOT_FOUND` — The app could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `GET /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}`

The notification was found.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.
- `notification` — Notification id returned when the notification was accepted.

Responses

- `200` `NOTIFICATION_FETCHED` — The notification was found.
  - `id` (string, required)
  - `title` (string, required)
  - `body` (string, required)
  - `audience` (string, required)
  - `audience_type` (string, required)
  - `targeted` (integer, required)
  - `delivered` (integer, required)
  - `failed` (integer, required)
  - `skipped` (integer, required)
  - `url` (string, required)
  - `image_url` (string, required)
  - `data` (object, required)
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `NOTIFICATION_NOT_FOUND` — The notification could not be found.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `POST /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}/cancel`

The notification was cancelled.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.
- `notification` — Draft or scheduled notification id.

Responses

- `200` `NOTIFICATION_CANCELLED` — The notification was cancelled.
  - `id` (string, required)
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `NOTIFICATION_NOT_FOUND` — The notification could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `GET /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}/outcomes`

The outcomes were listed.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.
- `notification` — Notification id.

Query

- `search` (string)
- `status` (`pending`, `delivered`, `failed`, `skipped`)
- `page` (integer)
- `per_page` (`10`, `25`, `50`)

Responses

- `200` `OUTCOMES_LISTED` — The outcomes were listed.
  - `page` (integer, required)
  - `per_page` (integer, required)
  - `total` (integer, required)
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `NOTIFICATION_NOT_FOUND` — The notification could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.

## `POST /api/v1/public/apps/{app}/environments/{environment}/notifications/{notification}/send`

The notification was sent.

Path

- `app` — App id in this workspace.
- `environment` — `development` or `production`.
- `notification` — Draft notification id.

Responses

- `200` `NOTIFICATION_SENT` — The notification was sent.
- `401` `INVALID_API_KEY` — The API key is invalid.
- `404` `NOTIFICATION_NOT_FOUND` — The notification could not be found.
- `422` `VALIDATION_FAILED` — The request contains invalid fields.
- `429` `RATE_LIMIT_EXCEEDED` — Too many requests. Please try again later.
- `500` `SERVER_ERROR` — Something went wrong. Please try again.