Short links and secrets, from code.

1. Authentication

Create a key at /app/api-keys (workspace owners and admins). The raw key is shown once; LinkPilot keeps only its SHA-256 hash. Send it on every request:

Authorization: Bearer lp_live_...

Keys are tied to a workspace, so there is no tenant parameter anywhere. Revoked, expired, unknown and malformed keys all return the same 401 unauthorized. Keys are never written to logs.

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

2. Routes

Lists return { data, next_cursor }; pass next_cursor back as cursor to continue. limit is 1 to 100.

3. Examples

Create a link with curl

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"]}'

Create a secret from JavaScript

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)}`;

List links from Python

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"])

Create an anonymous link with no key

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"}'

A Postman collection and an OpenAPI 3.1 document live next to the contract in the repository under docs/api/.

4. How secrets are stored

We want to be precise, because an API client has real work to do here: the API will not accept a plaintext payload at all.

• You encrypt, we store a blob. Send ciphertext (AES-GCM-256, v1.<iv>.<ct>) with enc_version: 1. Sending payload is rejected rather than quietly accepted.
• You must append the key yourself. The secret_url we return has no key in it and cannot: we have never seen one. Add #k=<base64url key>. Browsers never transmit the part after the #, so the recipient decrypts locally.
• There is no recovery. Lose the key and the secret is gone, for you and for us. That is the guarantee working.
• Destroyed on burn, expiry or revoke. The stored ciphertext is overwritten server-side.
• Never returned by the API. No route echoes a payload or a ciphertext. The only reader is the recipient's reveal page, which records the view.
• Passphrases (Pro and above) are a real second factor: stretched with PBKDF2-SHA256 and folded into the key with HKDF, so neither the link alone nor the passphrase alone decrypts. Send only passphrase_hash, the SHA-256 hex \u2014 never the raw passphrase, which is half the key.
• What it does not cover. Anyone holding the full link holds the key, so short expiry and burn-after-read still matter. File attachments are encrypted the same way, with a key derived from the same link.

The wire format is specified in the API reference, and @uselinkpilot/sdk does the whole exchange in one call if you would rather not hand-roll it. The same model is described on the security architecture page.

5. Plan limits and rate limits

The API applies the same plan rules as the dashboard, read from the same place, so an agency roll-up applies here too. GET /me returns the live numbers for your workspace. Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Compare plans

6. Public routes without a key

POST /public/links and POST /public/secrets exist for clients that cannot show a browser challenge: CLIs, MCP servers, the launcher. They take an opaque client_id (16 to 64 characters, generated once per install) and create records in the same anonymous pool as the free web tools.

• 20 creations per client per day and 60 per network per hour, plus the pool's own per-network caps.
• Same Google Safe Browsing and threat-feed screening as every other creation path.
• No custom domain, no custom slug, no passphrase; public secrets always burn after one read and expire within 24 hours.
• The response includes a claim_token so a signed-in user can claim the record into a workspace later. Treat it as a credential.

7. Errors

Every error is { "error": { "code", "message", "upgrade_url"? } }. Messages name the field, never your data. Resources in other workspaces are a 404, not a 403.