nsindocs جستجو در مستندات⌘K
API
  1. مستندات
  2. API و MCP

REST API

Base URL، authentication، قراردادها و محدودیت‌های REST API انسین، به‌علاوه محل مرجع کامل endpointها.

در این صفحه

Authenticate

bash
curl -H "Authorization: Bearer nsin_your_key_here" https://api.nsin.ir/domains/
curl -H "X-Api-Key: nsin_your_key_here"            https://api.nsin.ir/domains/

یک key به‌جای شما عمل می‌کند: domainهای شما، به‌علاوه domainهایی که با شما share شده‌اند، با نقش‌های روی آن‌ها. کلیدهای Read-only فقط می‌توانند GET، HEAD، OPTIONS بفرستند — به‌علاوه POST /analytics/query که چیزی نمی‌نویسد. GET /whoami می‌گوید چه نوع keyای دارید.

قراردادها

{domain} اسم domain است، نه یک id عددی:

bash
curl -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.ir/domains/example.com/records/

Trailing slash مهم است: /domains/ و /domains/{domain}/records/ یکی دارند؛ /domains/{domain} ندارد.

خطاها: {"error": "human readable message"}. Timestampها: RFC 3339 UTC. تعداد byte: بر حسب byte.

کارهایی که یک key نمی‌تواند بکند

برای هر key مسدود است، تا یک leak نتواند پول خرج کند:

بخش چرا
/users/** پروفایل، پسورد، session، keyها — نمی‌تواند key بسازد یا revoke کند.
/auth/** Login، ثبت‌نام، OTP.
/billing/** فهرست plan، تنظیمات billing.
/admin/** بخش admin.
POST /wallet/topup, …/subscriptions/purchase, /switch, /auto-renew پول جابه‌جا می‌کند.
PUT /domains/{domain}/billing-member تعیین می‌کند از wallet چه کسی پرداخت شود.

خواندن traffic usage، فاکتورها و وضعیت wallet مشکلی ندارد — فقط write مسدود است.

Rate limit و status codeها

هر key، 300 request در دقیقه — traffic پنل limit جدا دارد.

کد معنی
400 ورودی نامعتبر.
401 key نداده‌اید، نامعتبر است یا revoke شده.
402 domain هیچ plan فعالی ندارد (این قابلیت plan می‌خواهد).
403 write با read-only، نقش اشتباه، بخش مسدود، یا کمبود plan.
404 پیدا نشد، یا از شما پنهان است.
409 تداخل — domain وجود دارد یا غیرفعال است.
429 Rate limit خورده — {"error": "rate limit exceeded"}.

داخل مرجع چیست

گروه شامل چه چیزی
Domains اضافه کردن، تنظیم، verify، فعال‌سازی، حذف؛ dev mode؛ بررسی NS.
DNS Records CRUD، batch update/delete، اسکن zone، import از BIND.
SSL وضعیت، صدور دستی، آپلود/parse گواهی سفارشی.
Rules 15 نوع، هرکدام 7 endpoint (list، create، reorder، get، update، delete، toggle).
Cache آمار footprint، مرور entryها، purge، refresh.
Analytics Traffic، بازدیدکننده، bandwidth، cache، status code، جغرافیا، logها، WAF logها، query دلخواه.
Uptime حوادث قطعی، وضعیت زنده هر host، تنظیمات تشخیص.
Recommendations چک‌لیست توصیه‌ای، رد کردن‌ها.
Sharing اعضا، نقش‌ها، دعوت‌نامه‌ها.
Billing subscriptionها، featureها، usage traffic، فاکتورها، wallet (فقط خواندن).
Support تیکت‌ها، پاسخ‌ها.

اولین request

bash
export NSIN_KEY=nsin_your_key_here

curl -H "X-Api-Key: $NSIN_KEY" https://api.nsin.ir/domains/

curl -X POST -H "X-Api-Key: $NSIN_KEY" -H "Content-Type: application/json" \
  -d '{"name":"www","type":"A","destination":"203.0.113.10","proxied":true}' \
  https://api.nsin.ir/domains/example.com/records/

curl -X DELETE -H "X-Api-Key: $NSIN_KEY" \
  https://api.nsin.ir/domains/example.com/cache/
ویرایش این صفحه در GitHub
esc