التوثيق

المصادقة

نقاط api-key تأخذ `Authorization: Bearer agw_…`. تُنشأ المفاتيح من لوحة التحكم وتحمل صلاحيات خطتك — المجانية فيها قراءة+بحث، وHobby/Pro تضيفان memory:read وmemory:write.

نقاط الجلسة (حسابات المتصفح) تستعمل كوكي ‏agw_session‏ الذي يُضبط بالدخول/التسجيل. تُذكر هنا للاكتمال — التكاملات الخدمية تستعمل مفاتيح API.

POST /auth/signup public #

إنشاء حساب وجلسة. يُرسَل رابط التحقق بالبريد — إصدار المفاتيح يتطلب بريدًا مُتحقَّقًا منه.

الطلب

الحقلالنوعالوصف
emailstringمطلوب
passwordstring (min 8)مطلوب
namestringاختياري

مثال

curl -X POST https://agw.orcanox.xyz/auth/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-real-password"}'

الاستجابة

json
{
  "user": {
    "id": "<id>",
    "email": "a@b.c",
    "name": "…",
    "emailVerified": false
  }
}

الأخطاء

الحالةcodeمثال
400bad_request{"code":"bad_request","message":"invalid email"}
409bad_request{"code":"bad_request","message":"email already registered"}
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}
POST /auth/login public #

بريد + كلمة مرور ← كوكي جلسة (HttpOnly · Secure · SameSite=Lax).

الطلب

الحقلالنوعالوصف
emailstringمطلوب
passwordstringمطلوب

مثال

curl -X POST https://agw.orcanox.xyz/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-real-password"}'

الاستجابة

json
{
  "user": {
    "id": "<id>",
    "email": "a@b.c",
    "name": "…",
    "emailVerified": true
  }
}

الأخطاء

الحالةcodeمثال
401unauthorized{"code":"unauthorized","message":"invalid credentials"}
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}
POST /auth/logout session #

إنهاء الجلسة الحالية.

مثال

curl -X POST https://agw.orcanox.xyz/auth/logout \
  -H "Cookie: agw_session=…"

الاستجابة

json
{
  "ok": true
}
POST /auth/verify-email public #

استهلاك توكن التحقق المُرسَل بالبريد.

الطلب

الحقلالنوعالوصف
tokenstringمطلوب

مثال

curl -X POST https://agw.orcanox.xyz/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token":"agwt_…from-email"}'

الاستجابة

json
{
  "ok": true,
  "verified": true
}

الأخطاء

الحالةcodeمثال
400bad_request{"code":"bad_request","message":"invalid or expired token"}
POST /auth/forgot-password public #

يرد {"ok":true} دائمًا — متطابق للمسجَّل والمجهول. رابط الاستعادة يُرسَل بالبريد ولا يُعاد في الرد.

الطلب

الحقلالنوعالوصف
emailstringمطلوب

مثال

curl -X POST https://agw.orcanox.xyz/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

الاستجابة

json
{
  "ok": true
}

الأخطاء

الحالةcodeمثال
429rate_limited{"code":"rate_limited","message":"rate limit exceeded"}
POST /auth/reset-password public #

استهلاك توكن الاستعادة وتعيين كلمة مرور جديدة. كل الجلسات القائمة تُسقَط.

الطلب

الحقلالنوعالوصف
tokenstringمطلوب
passwordstring (min 8)مطلوب

مثال

curl -X POST https://agw.orcanox.xyz/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token":"agwt_…from-email","password":"new-strong-password"}'

الاستجابة

json
{
  "ok": true
}

الأخطاء

الحالةcodeمثال
400bad_request{"code":"bad_request","message":"invalid or expired token"}
POST /auth/resend-verification session #

إعادة إرسال رابط التحقق إلى بريدك أنت.

مثال

curl -X POST https://agw.orcanox.xyz/auth/resend-verification \
  -H "Cookie: agw_session=…"

الاستجابة

json
{
  "ok": true
}
GET /me session #

حسابك: الخطة واستهلاك الشهر وحالة الاشتراك.

مثال

curl -X GET https://agw.orcanox.xyz/me \
  -H "Cookie: agw_session=…"

الاستجابة

json
{
  "user": {
    "id": "<id>",
    "email": "a@b.c",
    "name": "…",
    "emailVerified": true
  },
  "plan": {
    "slug": "free",
    "name": "Free",
    "monthlyQuota": 500,
    "scopes": [
      "read",
      "search"
    ],
    "concurrency": null
  },
  "usage": {
    "month": "2026-10",
    "used": 12,
    "keys": 1
  },
  "subscription": {
    "status": "active",
    "interval": "monthly",
    "currentPeriodEnd": "2026-11-01T00: 00: 00.000Z",
    "expiresAt": null
  }
}

الأخطاء

الحالةcodeمثال
401unauthorized{"code":"unauthorized","message":"login required"}
POST /keys session #

إنشاء مفتاح ‏agw_‏. المفتاح الكامل يُعاد مرة واحدة — احفظه. يتطلب بريدًا مُتحقَّقًا منه.

الطلب

الحقلالنوعالوصف
namestringاختياري
scopesstring[]اختياري

مثال

curl -X POST https://agw.orcanox.xyz/keys \
  -H "Cookie: agw_session=…" \
  -H "Content-Type: application/json" \
  -d '{}'

الاستجابة

json
{
  "key": {
    "id": "<id>",
    "name": "default",
    "keyPrefix": "agw_abcd",
    "scopes": [
      "read",
      "search"
    ],
    "monthlyQuota": 500,
    "rawKey": "agw_… (shown once)"
  }
}

الأخطاء

الحالةcodeمثال
401unauthorized{"code":"unauthorized","message":"login required"}
403email_not_verified{"code":"email_not_verified","message":"verify your email before creating keys"}
403forbidden_scope{"code":"forbidden_scope","message":"scopes outside your plan: memory:read"}
GET /keys session #

سرد مفاتيحك باستهلاك الشهر الحي.

مثال

curl -X GET https://agw.orcanox.xyz/keys \
  -H "Cookie: agw_session=…"

الاستجابة

json
{
  "keys": [
    {
      "id": "<id>",
      "name": "default",
      "keyPrefix": "agw_abcd",
      "scopes": [
        "read"
      ],
      "monthlyQuota": 500,
      "used": 3
    }
  ]
}

الأخطاء

الحالةcodeمثال
401unauthorized{"code":"unauthorized","message":"login required"}
DELETE /keys/:id session #

تعطيل مفتاح — الطلبات به ترد 401 فورًا.

الطلب

الحقلالنوعالوصف
id (path)stringمطلوب

مثال

curl -X DELETE https://agw.orcanox.xyz/keys/<id> \
  -H "Cookie: agw_session=…" \
  -H "Content-Type: application/json" \
  -d '{}'

الاستجابة

json
{
  "ok": true
}

الأخطاء

الحالةcodeمثال
401unauthorized{"code":"unauthorized","message":"login required"}
404not_found{"code":"not_found","message":"key not found"}
POST /billing/checkout session #

إنشاء صفحة دفع Polar لخطة مدفوعة (شهرية أو سنوية).

الطلب

الحقلالنوعالوصف
plan'hobby' | 'pro'مطلوب
interval'monthly' | 'yearly'اختياري

مثال

curl -X POST https://agw.orcanox.xyz/billing/checkout \
  -H "Cookie: agw_session=…" \
  -H "Content-Type: application/json" \
  -d '{"plan":"hobby","interval":"monthly"}'

الاستجابة

json
{
  "checkoutUrl": "https://polar.sh/checkout/…"
}

الأخطاء

الحالةcodeمثال
401unauthorized{"code":"unauthorized","message":"login required"}
400bad_request{"code":"bad_request","message":"unknown plan"}
503internal{"code":"internal","message":"billing_not_configured"}
POST /billing/webhook public #

مستقبِل ويبهوك Polar — موقَّع ومُتحقَّق. ليس لنداء العملاء.

الطلب

الحقلالنوعالوصف
(Polar event payload)objectمطلوبظرف حدث Polar — ترويسات التوقيع مطلوبة.

مثال

curl -X POST https://agw.orcanox.xyz/billing/webhook \
  -H "Content-Type: application/json" \
  -d '{}'

الاستجابة

json
{
  "ok": true
}

الأخطاء

الحالةcodeمثال
400bad_request{"code":"bad_request","message":"invalid webhook signature"}