Reference
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
https://api.packlets.appAll calls use https://. Requests and responses are JSON in UTF-8.
Authentication
Every call carries the key of your packlet in the header:
Authorization: Bearer <PACKLETS_KEY>
Content-Type: application/jsonThe key determines the packlet and with it the channel. There is no channel field in the body. If a channel has several services, every call also works with the key of a service. The exceptions are the addresses for Slack, Discord and ntfy: there the key is in the address, because these tools can't set a header. More about the key in Keys and security.
All calls
| Call | Purpose | Channel type |
|---|---|---|
POST /v1/push | Send a message. | channel, app |
PUT /v1/ui | Set the page of an app. | app only |
POST /v1/slack/<PACKLETS_KEY> | Send a message in Slack format. The key is in the address. | channel, app |
POST /v1/discord/<PACKLETS_KEY> | Send a message in Discord format. The key is in the address. | channel, app |
POST /<PACKLETS_KEY> | Send a message like ntfy (text as body, details in headers; also GET …/publish and JSON to /). | channel, app |
POST /v1/session-token/verify | Have a session token verified. No key needed. | app only |
In the other direction, Packlets sends webhook events 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 (
"") andnullon optional fields count as not provided. POST /v1/pushalso accepts form data. For a quick test,curl -d text=Hellois 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:
{
"error": "invalid_body",
"message": "Invalid data.",
"details": [{ "path": "text", "message": "text must not be empty" }]
}All codes are listed under Error codes.
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.