Reference

API basics

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

Open as Markdown

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, 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

CallPurposeChannel type
POST /v1/pushSend a message.channel, app
PUT /v1/uiSet 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/verifyHave 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 ("") 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.

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:

HeaderContent
x-ratelimit-limitAllowed calls per minute.
x-ratelimit-remainingHow many are left in this minute.
x-ratelimit-resetSeconds until the count starts over.
retry-afterOnly on 429: wait this many seconds.

Limits

WhatLimit
Request64 KiB
text of a message1 to 10,000 characters
title of a message80 characters
url, image, page2,048 characters
Buttons per message3
Elements per message12
id of an element1 to 40 characters: letters, digits, _, -
id of a button1 to 64 characters
Your message in a channel with replies4,000 characters
Calls60 per minute and packlet, 300 per minute and account
Services per channel20
Packlets per account100
RetentionMessages 365 days, activity log 30 days

The limits of the individual elements are listed under Elements.