# API basics

URL, authentication, all calls, rate limit and all limits at a glance.

This page applies to all calls. The individual calls and their fields are on the pages that follow.

## Address

```text
https://api.packlets.app
```

All calls use `https://`. Requests and responses are JSON in UTF-8.

## Authentication

Every call carries the key of your packlet in the header:

```http
Authorization: Bearer <PACKLETS_KEY>
Content-Type: application/json
```

The key determines the packlet and with it the channel. There is no channel field in the body. If a channel has several [services](https://packlets.app/en/docs/dienste.md), every call also works with the key of a service. The exceptions are the addresses for [Slack](https://packlets.app/en/docs/slack.md), [Discord](https://packlets.app/en/docs/discord.md) and [ntfy](https://packlets.app/en/docs/ntfy.md): there the key is in the address, because these tools can't set a header. More about the key in [Keys and security](https://packlets.app/en/docs/sicherheit.md).

## All calls

| Call | Purpose | Channel type |
|---|---|---|
| [`POST /v1/push`](https://packlets.app/en/docs/api-push.md) | Send a message. | channel, app |
| [`PUT /v1/ui`](https://packlets.app/en/docs/api-ui.md) | Set the page of an app. | app only |
| [`POST /v1/slack/<PACKLETS_KEY>`](https://packlets.app/en/docs/slack.md) | Send a message in Slack format. The key is in the address. | channel, app |
| [`POST /v1/discord/<PACKLETS_KEY>`](https://packlets.app/en/docs/discord.md) | Send a message in Discord format. The key is in the address. | channel, app |
| [`POST /<PACKLETS_KEY>`](https://packlets.app/en/docs/ntfy.md) | Send a message like ntfy (text as body, details in headers; also `GET …/publish` and JSON to `/`). | channel, app |
| [`POST /v1/session-token/verify`](https://packlets.app/en/docs/api-seiten.md#let-packlets-verify-the-token) | Have a session token verified. No key needed. | app only |

In the other direction, Packlets sends [webhook events](https://packlets.app/en/docs/ereignisse.md) to your tool.

With the key, your tool can only send. It can't read, change or delete messages.

## Requests

- The body is JSON and at most 64 KiB. Packlets rejects larger requests with `413`.
- Fields that Packlets doesn't know are ignored.
- Empty texts (`""`) and `null` on optional fields count as not provided.
- `POST /v1/push` also accepts form data. For a quick test, `curl -d text=Hello` is enough.
- You can't call the API directly from a web page in the browser (no CORS). Call it from your server.

## Responses

Success is always status `200` with JSON. Every error has a fixed code in the `error` field:

```json
{
  "error": "invalid_body",
  "message": "Invalid data.",
  "details": [{ "path": "text", "message": "text must not be empty" }]
}
```

All codes are listed under [Error codes](https://packlets.app/en/docs/fehler.md).

## Rate limit

**60 calls per minute** are allowed per packlet, counted separately for each call. A new key for the same packlet keeps counting. Calls without a valid key are counted per IP address. There is also a limit per account: **300 calls per minute** across all your packlets together. Both limits are purely abuse protection.

Every response reports the current state in these headers:

| Header | Content |
|---|---|
| `x-ratelimit-limit` | Allowed calls per minute. |
| `x-ratelimit-remaining` | How many are left in this minute. |
| `x-ratelimit-reset` | Seconds until the count starts over. |
| `retry-after` | Only on `429`: wait this many seconds. |

## Limits

| What | Limit |
|---|---|
| Request | 64 KiB |
| `text` of a message | 1 to 10,000 characters |
| `title` of a message | 80 characters |
| `url`, `image`, `page` | 2,048 characters |
| Buttons per message | 3 |
| Elements per message | 12 |
| `id` of an element | 1 to 40 characters: letters, digits, `_`, `-` |
| `id` of a button | 1 to 64 characters |
| Your message in a channel with replies | 4,000 characters |
| Calls | 60 per minute and packlet, 300 per minute and account |
| Services per channel | 20 |
| Packlets per account | 100 |
| Retention | Messages 365 days, activity log 30 days |

The limits of the individual elements are listed under [Elements](https://packlets.app/en/docs/elemente.md).
