API
مرجع API
مرجع API نسخه ۱ برای تیم‌های فنی که می‌خواهند بررسی سایت، یافته‌ها، کلیدواژه‌ها، گزارش و وضعیت محتوا را از کد خودکار کنند. احراز هویت با کوکی نشست یا توکن Bearer است، همهٔ پاسخ‌ها JSON هستند و خطاها کد ماشینی برمی‌گردانند. این صفحه نحو و قراردادها را توضیح می‌دهد؛ SDK رسمی، محیط sandbox جداگانه یا تضمین زمان پاسخ ندارد.
آخرین به‌روزرسانی: 2026-11-05·نویسنده: تیم تحریریهٔ کستریلیا
احراز هویت
دو روش: کوکی نشست (برای رابط وب، با هدر x-csrf-token در درخواست‌های نوشتاری) یا توکن Bearer با پیشوند kst_. توکن‌ها فقط در پلن‌های دارای دسترسی API ساخته می‌شوند و فقط هش آن‌ها ذخیره می‌شود.
curl -s https://your-host/api/v1/projects \
-H "Authorization: Bearer kst_xxxxxxxx"پاسخ‌ها و خطاها
موفق: { ok: true, ... }. خطا:
{ "ok": false, "error": "Human readable", "code": "machine_code" }کدهای رایج: 401 invalid_token، 403 forbidden، 402 plan_limit، 409 invalid_transition، 422 validation_error، 429 rate_limited.
محدودیت نرخ
- ورود: ۱۰ تلاش در ۱۵ دقیقه به ازای IP
- ثبت‌نام: ۵ در ساعت به ازای IP
- بررسی عمومی: ۵ در ساعت به ازای IP
- سایر درخواست‌ها: محدود به سقف پلن (خزش، پرسش GEO، پیش‌نویس)
نقاط پایانی
| GET | /api/v1/health | Liveness and database check |
| POST | /api/v1/auth/signup | Create user, workspace and session |
| POST | /api/v1/auth/login | Email + password login |
| POST | /api/v1/audit/preview | Public sample audit (rate limited, 5/hour/IP) |
| GET | /api/v1/projects | List projects |
| POST | /api/v1/projects | Create a project |
| GET | /api/v1/projects/:id | Project detail and history |
| POST | /api/v1/projects/:id/crawl | Run an audit (synchronous, bounded by plan) |
| GET | /api/v1/projects/:id/issues | Findings from the latest crawl |
| GET | /api/v1/projects/:id/keywords | Keyword map; ?format=csv for export |
| POST | /api/v1/projects/:id/geo | Run authorized AI measurements |
| POST | /api/v1/projects/:id/content | Generate a brief or draft |
| PUT | /api/v1/content/:id | Update content, re-run quality gates |
| POST | /api/v1/content/:id/status | Approve / publish / reject |
| GET | /api/v1/projects/:id/reports | List reports |
| POST | /api/v1/projects/:id/reports | Generate a report snapshot |
| POST | /api/v1/integrations | Connect and test a CMS or provider |
| GET | /api/v1/tokens | List API tokens |
| POST | /api/v1/billing/checkout | Start a plan change |
| POST | /api/v1/billing/webhook | Stripe webhook (signature verified) |
نمونه: اجرای بررسی
curl -X POST https://your-host/api/v1/projects/PROJECT_ID/crawl \
-H "Authorization: Bearer kst_xxxxxxxx" \
-H "content-type: application/json"خزش همگام اجرا می‌شود و تا سقف صفحات پلن محدود است. برای کارهای طولانی، worker را اجرا کنید و از صف استفاده کنید.
آنچه API انجام نمی‌دهد
- بدون توکن معتبر، هیچ داده‌ای برنمی‌گرداند.
- دسترسی نوشتن بدون scope نوشتن رد می‌شود.
- هیچ endpointای پاسخ AI شبیه‌سازی‌شده تولید نمی‌کند.
پیش از اتصال چه باید بدانید؟
برای اسکریپت سرور به سرور کدام روش احراز هویت بهتر است؟
توکن Bearer با پیشوند kst_ برای ارتباط سرور به سرور مناسب‌تر است، چون به کوکی مرورگر و هدر CSRF وابسته نیست. توکن فقط یک‌بار نمایش داده می‌شود و تنها هش آن ذخیره می‌شود؛ آن را در متغیر محیطی نگه دارید و در پلن‌های دارای دسترسی API بسازید.
وقتی پاسخ 429 می‌گیرم چه کنم؟
به‌جای تلاش پشت‌سرهم، عقب‌گرد نمایی و صف‌کردن درخواست‌ها را انتخاب کنید؛ پاسخ 429 فیلد retryAt دارد. محدودیت‌ها: ورود ۱۰ تلاش در ۱۵ دقیقه به ازای IP، ثبت‌نام و بررسی عمومی ۵ در ساعت، و بقیهٔ فراخوانی‌ها تا سقف پلن.
تفاوت بررسی عمومی با خزش پروژه چیست؟
بررسی عمومی بدون حساب کار می‌کند، فقط یک نمونه از صفحات را می‌خواند و ۵ بار در ساعت به ازای IP محدود است. خزش پروژه احراز هویت می‌خواهد، تا سقف صفحات پلن اجرا می‌شود، در تاریخچه ذخیره می‌شود و یافته‌های آن از endpointهای issues و reports قابل خواندن است.