# REST API

> Send a push from your server with one JSON call, and read its counts. One REST key per app.

URL: https://docs.xulo.io/api

The REST API sends a push to one app from your server, and reads the counts of a send.

## Base URL

```text
https://api.xulo.io
```

Requests and responses are JSON. Send `Content-Type: application/json`.

## Endpoints

| Method | Path | Does |
| --- | --- | --- |
| `POST` | `/api/v1/notifications` | Send a push, now or at a set time. See [Send notification](https://docs.xulo.io/api/send-notification). |
| `GET` | `/api/v1/notifications/{id}` | Read the counts of one send. See [Notification stats](https://docs.xulo.io/api/notification-stats). |

## Keys

Each call uses the REST API key of one app, from **Settings → Keys & IDs**. The key stays on your server. See [Authentication](https://docs.xulo.io/api/authentication).

The App ID in your iOS app cannot call these endpoints.

## Sends are not held for approval

A call without `send_after` starts the send at once and answers before it ends. Xulo finishes it in the background. A call with `send_after` sends when that time arrives. There is no approval step in the dashboard for REST API sends. The send is recorded with the source API and shows in the dashboard like any other. See [Drafts and approval](https://docs.xulo.io/concepts/drafts-and-approval).

## A first call

```bash
curl https://api.xulo.io/api/v1/notifications \
  -H "Authorization: Key $XULO_REST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "contents": {"en": "Hello from Xulo"},
    "included_segments": ["Test devices"]
  }'
```

A segment send answers `202 Accepted` and goes out in the background:

```json
{
  "id": 42,
  "status": "queued",
  "sent": 0,
  "failed": 0,
  "skipped": 0,
  "estimate": 1,
  "message": "Queued for 1 device. It sends in the background."
}
```

## Limits at a glance

| Limit | Value |
| --- | --- |
| Requests | Per REST key: 50 a second for list sends, 30 a minute for segment and tag sends, 20 a second for reads. See [Rate limits](https://docs.xulo.io/api/rate-limits). |
| Ids per list | 500 |
| Devices per send | Every match, up to 1,000,000 for a segment or tag send. |
| Throttle | `throttle_rate_per_minute` from 1 to 100,000 |
| Message | 2,000 characters |
| Title | 120 characters |
| Apple payload | 4KB |
| Buttons | 1 |