المصادقة
نقاط api-key تأخذ `Authorization: Bearer agw_…`. تُنشأ المفاتيح من لوحة التحكم وتحمل صلاحيات خطتك — المجانية فيها قراءة+بحث، وHobby/Pro تضيفان memory:read وmemory:write.
نقاط الجلسة (حسابات المتصفح) تستعمل كوكي agw_session الذي يُضبط بالدخول/التسجيل. تُذكر هنا للاكتمال — التكاملات الخدمية تستعمل مفاتيح API.
إنشاء حساب وجلسة. يُرسَل رابط التحقق بالبريد — إصدار المفاتيح يتطلب بريدًا مُتحقَّقًا منه.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
email | string | مطلوب | |
password | string (min 8) | مطلوب | |
name | string | اختياري |
مثال
curl -X POST https://agw.orcanox.xyz/auth/signup \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"a-real-password"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/signup", json={"email":"you@example.com","password":"a-real-password"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/signup", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"email":"you@example.com","password":"a-real-password"}) }); console.log(r.status, await r.json());
الاستجابة
{
"user": {
"id": "<id>",
"email": "a@b.c",
"name": "…",
"emailVerified": false
}
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid email"} |
| 409 | bad_request | {"code":"bad_request","message":"email already registered"} |
| 429 | rate_limited | {"code":"rate_limited","message":"rate limit exceeded"} |
بريد + كلمة مرور ← كوكي جلسة (HttpOnly · Secure · SameSite=Lax).
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
email | string | مطلوب | |
password | string | مطلوب |
مثال
curl -X POST https://agw.orcanox.xyz/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com","password":"a-real-password"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/login", json={"email":"you@example.com","password":"a-real-password"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/login", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"email":"you@example.com","password":"a-real-password"}) }); console.log(r.status, await r.json());
الاستجابة
{
"user": {
"id": "<id>",
"email": "a@b.c",
"name": "…",
"emailVerified": true
}
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"invalid credentials"} |
| 429 | rate_limited | {"code":"rate_limited","message":"rate limit exceeded"} |
إنهاء الجلسة الحالية.
مثال
curl -X POST https://agw.orcanox.xyz/auth/logout \ -H "Cookie: agw_session=…"
import requests r = requests.post("https://agw.orcanox.xyz/auth/logout", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/logout", { method: "POST", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.json());
الاستجابة
{
"ok": true
}استهلاك توكن التحقق المُرسَل بالبريد.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
token | string | مطلوب |
مثال
curl -X POST https://agw.orcanox.xyz/auth/verify-email \ -H "Content-Type: application/json" \ -d '{"token":"agwt_…from-email"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/verify-email", json={"token":"agwt_…from-email"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/verify-email", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"token":"agwt_…from-email"}) }); console.log(r.status, await r.json());
الاستجابة
{
"ok": true,
"verified": true
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid or expired token"} |
يرد {"ok":true} دائمًا — متطابق للمسجَّل والمجهول. رابط الاستعادة يُرسَل بالبريد ولا يُعاد في الرد.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
email | string | مطلوب |
مثال
curl -X POST https://agw.orcanox.xyz/auth/forgot-password \ -H "Content-Type: application/json" \ -d '{"email":"you@example.com"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/forgot-password", json={"email":"you@example.com"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/forgot-password", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"email":"you@example.com"}) }); console.log(r.status, await r.json());
الاستجابة
{
"ok": true
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 429 | rate_limited | {"code":"rate_limited","message":"rate limit exceeded"} |
استهلاك توكن الاستعادة وتعيين كلمة مرور جديدة. كل الجلسات القائمة تُسقَط.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
token | string | مطلوب | |
password | string (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"}'
import requests r = requests.post("https://agw.orcanox.xyz/auth/reset-password", json={"token":"agwt_…from-email","password":"new-strong-password"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/reset-password", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({"token":"agwt_…from-email","password":"new-strong-password"}) }); console.log(r.status, await r.json());
الاستجابة
{
"ok": true
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid or expired token"} |
إعادة إرسال رابط التحقق إلى بريدك أنت.
مثال
curl -X POST https://agw.orcanox.xyz/auth/resend-verification \ -H "Cookie: agw_session=…"
import requests r = requests.post("https://agw.orcanox.xyz/auth/resend-verification", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/auth/resend-verification", { method: "POST", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.json());
الاستجابة
{
"ok": true
}حسابك: الخطة واستهلاك الشهر وحالة الاشتراك.
مثال
curl -X GET https://agw.orcanox.xyz/me \ -H "Cookie: agw_session=…"
import requests r = requests.get("https://agw.orcanox.xyz/me", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/me", { method: "GET", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.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 | مثال |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
إنشاء مفتاح agw_. المفتاح الكامل يُعاد مرة واحدة — احفظه. يتطلب بريدًا مُتحقَّقًا منه.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
name | string | اختياري | |
scopes | string[] | اختياري |
مثال
curl -X POST https://agw.orcanox.xyz/keys \ -H "Cookie: agw_session=…" \ -H "Content-Type: application/json" \ -d '{}'
import requests r = requests.post("https://agw.orcanox.xyz/keys", cookies={"agw_session": "…"}, json={}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/keys", { method: "POST", headers: { "Cookie": "agw_session=…", "Content-Type": "application/json" }, body: JSON.stringify({}) }); console.log(r.status, await r.json());
الاستجابة
{
"key": {
"id": "<id>",
"name": "default",
"keyPrefix": "agw_abcd",
"scopes": [
"read",
"search"
],
"monthlyQuota": 500,
"rawKey": "agw_… (shown once)"
}
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
| 403 | email_not_verified | {"code":"email_not_verified","message":"verify your email before creating keys"} |
| 403 | forbidden_scope | {"code":"forbidden_scope","message":"scopes outside your plan: memory:read"} |
سرد مفاتيحك باستهلاك الشهر الحي.
مثال
curl -X GET https://agw.orcanox.xyz/keys \ -H "Cookie: agw_session=…"
import requests r = requests.get("https://agw.orcanox.xyz/keys", cookies={"agw_session": "…"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/keys", { method: "GET", headers: { "Cookie": "agw_session=…" } }); console.log(r.status, await r.json());
الاستجابة
{
"keys": [
{
"id": "<id>",
"name": "default",
"keyPrefix": "agw_abcd",
"scopes": [
"read"
],
"monthlyQuota": 500,
"used": 3
}
]
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
تعطيل مفتاح — الطلبات به ترد 401 فورًا.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
id (path) | string | مطلوب |
مثال
curl -X DELETE https://agw.orcanox.xyz/keys/<id> \ -H "Cookie: agw_session=…" \ -H "Content-Type: application/json" \ -d '{}'
import requests
r = requests.delete("https://agw.orcanox.xyz/keys/<id>", cookies={"agw_session": "…"}, json={})
print(r.status_code, r.json())const r = await fetch("https://agw.orcanox.xyz/keys/<id>", {
method: "DELETE",
headers: { "Cookie": "agw_session=…", "Content-Type": "application/json" },
body: JSON.stringify({})
});
console.log(r.status, await r.json());
الاستجابة
{
"ok": true
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
| 404 | not_found | {"code":"not_found","message":"key not found"} |
إنشاء صفحة دفع 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"}'
import requests r = requests.post("https://agw.orcanox.xyz/billing/checkout", cookies={"agw_session": "…"}, json={"plan":"hobby","interval":"monthly"}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/billing/checkout", { method: "POST", headers: { "Cookie": "agw_session=…", "Content-Type": "application/json" }, body: JSON.stringify({"plan":"hobby","interval":"monthly"}) }); console.log(r.status, await r.json());
الاستجابة
{
"checkoutUrl": "https://polar.sh/checkout/…"
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 401 | unauthorized | {"code":"unauthorized","message":"login required"} |
| 400 | bad_request | {"code":"bad_request","message":"unknown plan"} |
| 503 | internal | {"code":"internal","message":"billing_not_configured"} |
مستقبِل ويبهوك Polar — موقَّع ومُتحقَّق. ليس لنداء العملاء.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
(Polar event payload) | object | مطلوب | ظرف حدث Polar — ترويسات التوقيع مطلوبة. |
مثال
curl -X POST https://agw.orcanox.xyz/billing/webhook \ -H "Content-Type: application/json" \ -d '{}'
import requests
r = requests.post("https://agw.orcanox.xyz/billing/webhook", json={})
print(r.status_code, r.json())const r = await fetch("https://agw.orcanox.xyz/billing/webhook", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({}) }); console.log(r.status, await r.json());
الاستجابة
{
"ok": true
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"invalid webhook signature"} |