Referenz

API-Grundlagen

Adresse, Anmeldung, alle Aufrufe, Rate-Limit und alle Grenzen auf einen Blick.

Diese Seite gilt für alle Aufrufe. Die einzelnen Aufrufe mit ihren Feldern stehen auf den Seiten danach.

Adresse

Text

https://api.packlets.app

Alle Aufrufe laufen über https://. Anfragen und Antworten sind JSON in UTF-8.

Anmeldung

Jeder Aufruf trägt den Schlüssel deines Packlets im Header:

HTTP

Authorization: Bearer <SAMY_KEY>
Content-Type: application/json

Der Schlüssel bestimmt das Packlet und damit den Kanal. Eine Kanal-Angabe im Body gibt es nicht. Ausnahmen sind die Adressen für Slack, Discord und ntfy: Dort steht der Schlüssel in der Adresse, weil diese Tools keinen Header setzen können. Mehr zum Schlüssel steht unter Schlüssel und Sicherheit.

Alle Aufrufe

Aufruf	Zweck	Kanal-Art
`POST /v1/push`	Eine Nachricht schicken.	Kanal, App
`PUT /v1/ui`	Die Seite einer App setzen.	nur App
`POST /v1/slack/<SAMY_KEY>`	Eine Nachricht im Slack-Format schicken. Der Schlüssel steht in der Adresse.	Kanal, App
`POST /v1/discord/<SAMY_KEY>`	Eine Nachricht im Discord-Format schicken. Der Schlüssel steht in der Adresse.	Kanal, App
`POST /<SAMY_KEY>`	Eine Nachricht wie bei ntfy schicken (Text als Body, Angaben in Headern; auch `GET …/publish` und JSON an `/`).	Kanal, App
`POST /v1/session-token/verify`	Ein Session-Token prüfen lassen. Ohne Schlüssel.	nur App

In die andere Richtung schickt Samy Webhook-Ereignisse an dein Tool.

Mit dem Schlüssel kann dein Tool nur schicken. Nachrichten lesen, ändern oder löschen kann es nicht.

Anfragen

Der Body ist JSON und höchstens 64 KiB groß. Größere Anfragen lehnt Samy mit 413 ab.
Felder, die Samy nicht kennt, werden ignoriert.
Leere Texte ("") und null bei optionalen Feldern zählen als nicht angegeben.
POST /v1/push nimmt auch Formulardaten an. Für einen schnellen Test reicht also curl -d text=Hallo.
Aus einer Webseite im Browser lässt sich die API nicht direkt rufen (kein CORS). Ruf sie von deinem Server aus.

Antworten

Erfolg ist immer Status 200 mit JSON. Jeder Fehler hat eine feste Kennung im Feld error:

JSON

{
  "error": "invalid_body",
  "message": "Ungültige Daten.",
  "details": [{ "path": "text", "message": "text darf nicht leer sein" }]
}

Alle Kennungen stehen unter Fehlercodes.

Rate-Limit

Erlaubt sind 60 Aufrufe pro Minute und Packlet, für jeden Aufruf einzeln gezählt. Ein neuer Schlüssel für dasselbe Packlet zählt weiter. Aufrufe ohne gültigen Schlüssel zählen pro IP-Adresse. Dazu gilt ein Limit pro Konto: 300 Aufrufe pro Minute über alle deine Packlets zusammen. Beide Limits sind reiner Missbrauchsschutz.

Jede Antwort nennt den Stand in diesen Headern:

Header	Inhalt
`x-ratelimit-limit`	Erlaubte Aufrufe pro Minute.
`x-ratelimit-remaining`	Wie viele in dieser Minute noch übrig sind.
`x-ratelimit-reset`	Sekunden, bis die Zählung neu beginnt.
`retry-after`	Nur bei `429`: so viele Sekunden warten.

Grenzen

Was	Grenze
Anfrage	64 KiB
`text` einer Nachricht	1 bis 10.000 Zeichen
`title` einer Nachricht	80 Zeichen
`url`, `image`, `page`	2.048 Zeichen
Knöpfe pro Nachricht	3
Elemente pro Nachricht	12
`id` eines Elements	1 bis 40 Zeichen: Buchstaben, Ziffern, `_`, `-`
`id` eines Knopfs	1 bis 64 Zeichen
Deine Nachricht in einem Kanal mit Antworten	4.000 Zeichen
Aufrufe	60 pro Minute und Packlet, 300 pro Minute und Konto
Packlets pro Konto	100
Aufbewahrung	Nachrichten 365 Tage, Protokoll 30 Tage

Die Grenzen der einzelnen Elemente stehen unter Elemente.