روابط مختصرة وأسرار، من الكود مباشرة

1. المصادقة

أنشئ مفتاحًا من /app/api-keys (لمالكي مساحة العمل ومسؤوليها). يظهر المفتاح الكامل مرة واحدة، ولا تحتفظ خدمة LinkPilot إلا بقيمة تجزئة SHA-256 للمفتاح. أرسله مع كل طلب:

Authorization: Bearer lp_live_...

يرتبط كل مفتاح بمساحة عمل، فلا يوجد معامل tenant في أي مكان. المفاتيح المُبطلة والمنتهية الصلاحية وغير المعروفة والمشوهة تعيد كلها الاستجابة نفسها 401 unauthorized. ولا تُكتب المفاتيح في السجلات أبدًا.

عنوان URL الأساسي: https://khiydxamyihofmtmgvjz.supabase.co/functions/v1/api-v1

2. المسارات

تعيد القوائم { data, next_cursor }. لمتابعة القائمة أعد إرسال next_cursor في cursor. قيمة limit من 1 إلى 100.

3. أمثلة

إنشاء رابط باستخدام 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"]}'

إنشاء سر من 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)}`;

عرض الروابط من 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"])

إنشاء رابط مجهول المصدر بلا مفتاح

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

ننشر العقد الرسمي هنا، لا في مستودع كود: مستند OpenAPI 3.1 و مجموعة Postman و المرجع المكتوب. وجّه مولّد الكود لديك مباشرة إلى عنوان OpenAPI.

4. كيف تُخزَّن الأسرار

نريد أن نكون دقيقين هنا، لأن على عميل API عملًا حقيقيًا: الواجهة لا تقبل payload بنص غير مشفر إطلاقًا.

• أنت تشفّر، ونحن نخزن كتلة بيانات. أرسل ciphertext (AES-GCM-256، v1.<iv>.<ct>) مع enc_version: 1. إرسال payload يُرفض، ولا يُقبل بصمت.
• عليك أن تضيف المفتاح بنفسك. لا يحتوي secret_url الذي نعيده على أي مفتاح، ولا يمكن أن يحتويه، لأننا لم نرَ المفتاح قط. أضف #k=<base64url key>. لا ترسل المتصفحات أبدًا الجزء الذي يلي علامة #، فيفك المستلم التشفير على جهازه.
• لا يوجد استرجاع. إذا فقدت المفتاح ضاع السر، عليك وعلينا. هكذا يعمل الضمان.
• يُتلف عند الحذف بعد القراءة أو انتهاء الصلاحية أو الإبطال. نكتب فوق النص المشفر المخزن على الخادم.
• لا تعيده الواجهة أبدًا. لا يوجد مسار يعيد المحتوى أو النص المشفر. القارئ الوحيد هو صفحة الإظهار لدى المستلم، وهي تسجل المشاهدة.
• عبارات المرور (في خطة Pro وما فوقها) عامل ثانٍ حقيقي: تُقوّى باستخدام PBKDF2-SHA256 وتُدمج في المفتاح باستخدام HKDF، فلا الرابط وحده ولا عبارة المرور وحدها تكفي لفك التشفير. أرسل passphrase_hash فقط، وهو قيمة تجزئة SHA-256 بالصيغة الست عشرية لعبارة المرور بعد توحيدها بصيغة NFKC. لا ترسل عبارة المرور الأصلية أبدًا، فهي نصف المفتاح. اشتق المفتاح من صيغة NFKC نفسها، حتى تفتح عبارة المرور السر إذا كُتبت على لوحة مفاتيح أخرى.
• ما لا يغطيه. من يملك الرابط كاملًا يملك المفتاح، لذلك يبقى قِصر مدة الصلاحية والحذف بعد القراءة مهمين. تُشفَّر المرفقات بالطريقة نفسها، بمفتاح مشتق من الرابط نفسه.

صيغة البيانات المتبادلة موصوفة في مرجع API، وتنفذ @uselinkpilot/sdk العملية كلها في استدعاء واحد إن لم ترغب في كتابتها بنفسك. والنموذج نفسه موصوف في صفحة بنية الأمان.

5. حدود الخطط وحدود معدل الطلبات

تطبق الواجهة قواعد الخطة نفسها المطبقة في لوحة التحكم وتقرؤها من المصدر نفسه، فيسري هنا أيضًا تجميع حدود الوكالة. يعيد GET /me الأرقام الحالية لمساحة عملك. وتحمل كل استجابة مصادَق عليها الترويسات X-RateLimit-Limit و X-RateLimit-Remaining و X-RateLimit-Reset.

مقارنة الخطط

6. مسارات عامة بلا مفتاح

يوجد POST /public/links و POST /public/secrets للعملاء الذين لا يستطيعون عرض اختبار تحقق في المتصفح: أدوات CLI وخوادم MCP والمشغّل. يأخذ كلاهما client_id مُبهمًا (من 16 إلى 64 حرفًا، يُولَّد مرة واحدة لكل تثبيت)، وينشئ سجلات في المجموعة المجهولة المصدر نفسها التي تستخدمها أدوات الويب المجانية.

• 20 عملية إنشاء لكل عميل في اليوم و60 لكل شبكة في الساعة، إضافة إلى حدود هذه المجموعة نفسها لكل شبكة.
• الفحص نفسه بمصادر التهديدات، والاستعلام نفسه عن التهديدات في عناوين URL لدى Google، وإعادة الفحص المجدولة نفسها كما في كل طرق الإنشاء الأخرى.
• لا نطاق مخصص ولا نهاية مخصصة ولا عبارة مرور. الأسرار العامة تُحذف نهائيًا دائمًا بعد قراءة واحدة، وتنتهي صلاحيتها خلال 24 ساعة.
• تتضمن الاستجابة claim_token حتى يتمكن مستخدم سجّل الدخول لاحقًا من ضمّ السجل إلى مساحة عمل. تعامل معه كما تتعامل مع بيانات الدخول.

7. الأخطاء

كل خطأ يأتي بالشكل { "error": { "code", "message", "upgrade_url"? } }. تذكر الرسائل اسم الحقل، ولا تذكر بياناتك أبدًا. الموارد الموجودة في مساحات عمل أخرى تعيد 404، لا 403.