Kurzlinks und Geheimnisse, direkt aus Ihrem Code.

1. Authentifizierung

Erstellen Sie einen Schlüssel unter /app/api-keys (Workspace-Inhaber und Admins). Der vollständige Schlüssel wird einmal angezeigt; LinkPilot speichert nur seinen SHA-256-Hash. Senden Sie ihn bei jeder Anfrage mit:

Authorization: Bearer lp_live_...

Schlüssel gehören zu einem Workspace, deshalb gibt es nirgends einen Mandanten-Parameter. Widerrufene, abgelaufene, unbekannte und fehlerhafte Schlüssel liefern alle dasselbe 401 unauthorized. Schlüssel landen nie in Logs.

Basis-URL: https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1

2. Routen

Listen liefern { data, next_cursor }. Geben Sie next_cursor als cursor zurück, um weiterzublättern. limit liegt zwischen 1 und 100.

3. Beispiele

Einen Link mit curl erstellen

curl -X POST "https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/links" \
  -H "Authorization: Bearer $LINKPILOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/launch","slug":"launch","tags":["campaign"]}'

Ein Geheimnis mit JavaScript erstellen

const b64u = (b) => btoa(String.fromCharCode(...new Uint8Array(b)))
  .replace(/+/g, "-").replace(///g, "_").replace(/=+$/, "");

// 1. Encrypt locally. This key is generated here and never sent anywhere.
const key = crypto.getRandomValues(new Uint8Array(32));
const iv = crypto.getRandomValues(new Uint8Array(12));
const k = await crypto.subtle.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
const ct = await crypto.subtle.encrypt(
  { name: "AES-GCM", iv, tagLength: 128 },
  k,
  new TextEncoder().encode("staging db password"),
);
const ciphertext = `v1.${b64u(iv)}.${b64u(ct)}`;

// 2. Store the blob. LinkPilot cannot read it.
const res = await fetch("https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/secrets", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LINKPILOT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ciphertext, enc_version: 1, ttl_seconds: 3600 }),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const { secret_url } = await res.json();

// 3. Attach the key. Without this the link can never be opened, by anyone.
const shareUrl = `${secret_url}#k=${b64u(key)}`;

Links mit Python auflisten

import os, requests

r = requests.get(
    "https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/links",
    params={"limit": 20},
    headers={"Authorization": f"Bearer {os.environ['LINKPILOT_API_KEY']}"},
)
r.raise_for_status()
for link in r.json()["data"]:
    print(link["short_url"], "->", link["url"])
print("remaining this hour:", r.headers["X-RateLimit-Remaining"])

Einen anonymen Link ohne Schlüssel erstellen

curl -X POST "https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1/public/links" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","client_id":"my-cli-0123456789abcdef"}'

Der formale Vertrag wird hier veröffentlicht, nicht in einem Repository: OpenAPI-3.1-Dokument, Postman-Collection und die schriftliche Referenz. Richten Sie Ihren Codegenerator direkt auf die OpenAPI-URL.

4. Wie Geheimnisse gespeichert werden

Hier wollen wir genau sein, denn ein API-Client hat an dieser Stelle echte Arbeit zu leisten: Die API nimmt ein payload im Klartext überhaupt nicht an.

• Sie verschlüsseln, wir speichern einen Blob. Senden Sie ciphertext (AES-GCM-256, v1.<iv>.<ct>) mit enc_version: 1. Ein gesendetes payload wird abgelehnt, nicht stillschweigend angenommen.
• Den Schlüssel hängen Sie selbst an. Die secret_url, die wir zurückgeben, enthält keinen Schlüssel und kann keinen enthalten: Wir haben ihn nie gesehen. Hängen Sie #k=<base64url key> an. Browser übertragen den Teil des Links nach dem # nie, deshalb entschlüsselt der Empfänger lokal.
• Es gibt keine Wiederherstellung. Ist der Schlüssel verloren, ist das Geheimnis weg, für Sie und für uns. Genau so funktioniert die Garantie.
• Vernichtet beim Löschen nach dem Lesen, bei Ablauf oder Widerruf. Der gespeicherte Geheimtext wird auf dem Server überschrieben.
• Die API gibt ihn nie zurück. Keine Route liefert einen Inhalt oder Geheimtext aus. Lesen kann ihn nur die Anzeigeseite des Empfängers, und sie protokolliert den Aufruf.
• Passphrasen (ab Pro) sind ein echter zweiter Faktor: Sie werden mit PBKDF2-SHA256 gestreckt und per HKDF in den Schlüssel eingerechnet, sodass weder der Link allein noch die Passphrase allein entschlüsselt. Senden Sie nur passphrase_hash, den SHA-256-Hex-Wert der NFKC-normalisierten Passphrase, niemals die Passphrase selbst, denn sie ist die Hälfte des Schlüssels. Leiten Sie den Schlüssel aus derselben NFKC-Form ab, damit eine auf einer anderen Tastatur eingegebene Passphrase das Geheimnis trotzdem öffnet.
• Was das nicht abdeckt. Wer den vollständigen Link hat, hat den Schlüssel. Kurze Ablaufzeiten und Löschen nach dem Lesen bleiben deshalb wichtig. Dateianhänge werden genauso verschlüsselt, mit einem Schlüssel, der aus demselben Link abgeleitet ist.

Das Übertragungsformat ist in der API-Referenz spezifiziert, und @uselinkpilot/sdk erledigt den gesamten Austausch mit einem Aufruf, wenn Sie ihn nicht selbst implementieren wollen. Dasselbe Modell beschreibt die Seite zur Sicherheitsarchitektur.

5. Tarif-Limits und Rate-Limits

Die API wendet dieselben Tarifregeln an wie das Dashboard und liest sie aus derselben Quelle. Eine Agentur-Bündelung gilt also auch hier. GET /me liefert die aktuellen Werte für Ihren Workspace. Jede authentifizierte Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset.

Tarife vergleichen

6. Öffentliche Routen ohne Schlüssel

POST /public/links und POST /public/secrets gibt es für Clients, die keine Browser-Prüfung anzeigen können: CLIs, MCP-Server, den Launcher. Sie erwarten eine opake client_id (16 bis 64 Zeichen, einmal pro Installation erzeugt) und legen Einträge im selben anonymen Pool an wie die kostenlosen Web-Tools.

• 20 Erstellungen pro Client und Tag und 60 pro Netzwerk und Stunde, dazu die eigenen Netzwerk-Limits des Pools.
• Dieselbe Prüfung gegen Bedrohungs-Feeds, dieselbe Google-Abfrage zu gefährlichen URLs und dieselben geplanten Nachprüfungen wie bei jedem anderen Weg, Links zu erstellen.
• Keine eigene Domain, kein eigenes Kürzel, keine Passphrase. Öffentliche Geheimnisse werden immer nach einmaligem Lesen gelöscht und laufen innerhalb von 24 Stunden ab.
• Die Antwort enthält ein claim_token, mit dem ein angemeldeter Nutzer den Eintrag später in einen Workspace übernehmen kann. Behandeln Sie es wie Zugangsdaten.

7. Fehler

Jeder Fehler hat die Form { "error": { "code", "message", "upgrade_url"? } }. Meldungen nennen das Feld, nie Ihre Daten. Ressourcen in anderen Workspaces ergeben 404, nicht 403.