Enlaces cortos y secretos, desde tu código.

1. Autenticación

Crea una clave en /app/api-keys (propietarios y administradores del espacio de trabajo). La clave completa se muestra una sola vez; LinkPilot guarda solo su hash SHA-256. Envíala en cada petición:

Authorization: Bearer lp_live_...

Cada clave está vinculada a un espacio de trabajo, así que no hay ningún parámetro de tenant. Las claves revocadas, expiradas, desconocidas o mal formadas devuelven todas el mismo 401 unauthorized. Las claves nunca se escriben en los registros.

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

2. Rutas

Las listas devuelven { data, next_cursor }; para seguir, envía next_cursor como cursor. limit va de 1 a 100.

3. Ejemplos

Crear un enlace con 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"]}'

Crear un secreto desde 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)}`;

Listar enlaces desde 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"])

Crear un enlace anónimo sin clave

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

El contrato formal se publica aquí, no en un repositorio: el documento OpenAPI 3.1, la colección de Postman y la referencia escrita. Apunta tu generador de código directamente a la URL de OpenAPI.

4. Cómo se guardan los secretos

Queremos ser precisos, porque aquí un cliente de la API tiene trabajo real que hacer: la API no acepta en ningún caso un payload sin cifrar.

• Tú cifras; nosotros guardamos un blob. Envía ciphertext (AES-GCM-256, v1.<iv>.<ct>) con enc_version: 1. Si envías payload, la petición se rechaza; no se acepta en silencio.
• Tienes que añadir la clave tú mismo. El secret_url que devolvemos no lleva la clave, y no puede llevarla: nunca la hemos visto. Añade #k=<base64url key>. Los navegadores nunca transmiten la parte del enlace que va después del #, así que el destinatario descifra en su dispositivo.
• No hay recuperación posible. Si pierdes la clave, el secreto se pierde, para ti y para nosotros. Así es como funciona la garantía.
• Se destruye al leerse, al expirar o al revocarse. El texto cifrado almacenado se sobrescribe en el servidor.
• La API nunca lo devuelve. Ninguna ruta devuelve un contenido ni un texto cifrado. Solo lo lee la página donde el destinatario lo muestra, que registra la visualización.
• Las frases de contraseña (Pro y superiores) son un segundo factor real: se refuerzan con PBKDF2-SHA256 y se integran en la clave con HKDF, así que ni el enlace solo ni la frase de contraseña sola bastan para descifrar. Envía solo passphrase_hash, el hash SHA-256 en hexadecimal de la frase de contraseña normalizada con NFKC, nunca la frase en sí, que es la mitad de la clave. Deriva la clave de esa misma forma NFKC, para que una frase de contraseña escrita con otro teclado siga abriendo el secreto.
• Lo que no cubre. Quien tenga el enlace completo tiene la clave, así que una expiración corta y la destrucción tras la primera lectura siguen siendo importantes. Los archivos adjuntos se cifran del mismo modo, con una clave derivada del mismo enlace.

El formato de intercambio está especificado en la referencia de la API, y @uselinkpilot/sdk hace todo el intercambio en una sola llamada si prefieres no implementarlo a mano. El mismo modelo se describe en la página de arquitectura de seguridad.

5. Límites del plan y límites de peticiones

La API aplica las mismas reglas de plan que el panel, leídas del mismo sitio, así que la agrupación de una agencia también cuenta aquí. GET /me devuelve las cifras actuales de tu espacio de trabajo. Cada respuesta autenticada incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

Comparar planes

6. Rutas públicas sin clave

POST /public/links y POST /public/secrets existen para los clientes que no pueden mostrar una verificación en el navegador: CLI, servidores MCP, el lanzador. Reciben un client_id opaco (de 16 a 64 caracteres, generado una vez por instalación) y crean registros en el mismo grupo anónimo que las herramientas web gratuitas.

• 20 creaciones por cliente al día y 60 por red cada hora, además de los límites por red del propio grupo.
• El mismo filtrado con fuentes de amenazas, la misma consulta de URL en Google y las mismas revisiones programadas que cualquier otra forma de crear enlaces.
• Sin dominio propio, sin slug personalizado, sin frase de contraseña; los secretos públicos siempre se destruyen tras la primera lectura y expiran en un máximo de 24 horas.
• La respuesta incluye un claim_token para que un usuario con sesión iniciada pueda reclamar después el registro para un espacio de trabajo. Trátalo como una credencial.

7. Errores

Todos los errores tienen la forma { "error": { "code", "message", "upgrade_url"? } }. Los mensajes nombran el campo, nunca tus datos. Un recurso de otro espacio de trabajo devuelve 404, no 403.