مستندات توسعه دهندگان
REST API
یک base URL، یک bearer key، ورودی و خروجی JSON. امتیازها، مشکل ها، اصلاح ها، داده های جست وجو و آمادگی برای هوش مصنوعی، برای همه سایت هایی که کلیدتان پوشش می دهد.
Base URL و احراز هویت
https://app.monoranks.com/api/v1
Authorization: Bearer mr_ws_… (or mr_site_…)
توضیح ماشین خوان همه endpointها و eventهای webhook: https://app.monoranks.com/api/v1/openapi.json (OpenAPI 3.1). این آدرس را در Postman، Insomnia، Bruno یا یک ابزار تولید کلاینت وارد کنید.
کلید فضای کاری (workspace key) را در اپ از مسیر Settings → Developer access → New key بسازید. این کلید یا به همه سایت ها دسترسی دارد یا فقط به سایت هایی که تیک می زنید. کلید سایت (mr_site_…) وقتی ساخته می شود که افزونه WordPress وصل شود و فقط به همان یک سایت دسترسی دارد. هر کلید فقط یک بار نمایش داده می شود. جزئیات را در کلیدهای API و scopeها ببینید.
Endpointها
هر endpoint صفحه خودش را دارد: پارامترها، درخواست و پاسخ، خطاها و یک مثال curl. همه مسیرها با Base URL شروع می شوند.
توضیح ها از سند OpenAPI می آیند و انگلیسی اند.
سایت ها و امتیازها
بررسی ها و مشکل ها
اکشن ها
صفحه ها
/sites/{siteId}/pages/applyGET/sites/{siteId}/pagesGET/sites/{siteId}/pages/{pageId}GET/sites/{siteId}/pages/findingsGET/sites/{siteId}/pages/{pageId}/historyGET/sites/{siteId}/pages/historyGET/sites/{siteId}/pages/{pageId}/title-comparePOST/sites/{siteId}/pages/{pageId}/title-compareGET/sites/{siteId}/pages/{pageId}/faq-suggestPOST/sites/{siteId}/pages/{pageId}/faq-suggestPOST/sites/{siteId}/pages/{pageId}/faq-suggest/actionGET/sites/{siteId}/pages/{pageId}/claim-checkPOST/sites/{siteId}/pages/{pageId}/claim-checkSearch Console
Google Analytics
کلمات کلیدی
رقبا
بک لینک ها
جذب لینک
دیده شدن در هوش مصنوعی
آمادگی برای هوش مصنوعی
عمومی، بدون کلید
صفحه بندی
لیست ها صفحه به صفحه می آیند. این جدول هر endpoint صفحه بندی شده را نشان می دهد: با چه پارامترهایی صفحه می خورد و از کجا می فهمید صفحه بعدی هست.
| Endpoint | پارامترها | پیش فرض / حداکثر | خروجی |
|---|---|---|---|
GET/portfolio | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/reports | limit | limit 5 / 20 | – |
GET/sites/{siteId}/issues/{issueId} | suggestions_offset suggestions_limit | suggestions_offset 0 / 1,000,000suggestions_limit 100 / 100 | suggestionsNextOffset |
GET/sites/{siteId}/audits | limit | limit 5 / 25 | – |
GET/sites/{siteId}/actions | limit | limit 25 / 100 | – |
GET/sites/{siteId}/pages | page per | page 1 / –per 50 / 200 | total |
GET/sites/{siteId}/pages/{pageId}/history | limit | limit 30 / 100 | more |
GET/sites/{siteId}/pages/history | limit | limit 30 / 100 | more |
GET/sites/{siteId}/search/rows | page limit cursor | limit 1,000 / 10,000 | nextCursor |
GET/sites/{siteId}/topics | limit | limit 50 / 200 | – |
GET/sites/{siteId}/search/near-page-one | page per | page 1 / –per 50 / 500 | total hasMore |
GET/sites/{siteId}/analytics/pages | limit offset cursor | limit 100 / 1,000offset 0 / 1,000,000 | total nextCursor nextOffset |
GET/sites/{siteId}/keywords | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/competitors/gaps | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/competitors/content-ideas | page per | page 1 / –per 20 / 200 | total hasMore |
GET/sites/{siteId}/backlinks | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/outreach | page per | page 1 / –per 50 / 200 | total hasMore |
GET/sites/{siteId}/ai-visibility | limit | limit 50 / 1,000 | – |
GET/sites/{siteId}/agentic | page per | page 1 / 10,000per 50 / 200 | total hasMore |
خطاها و محدودیت ها
خطاها این شکل را دارند: { "error": { "code": "…", "message": "…" } }. مقدار code ثابت است؛ message با کلمه ها می گوید چه اتفاقی افتاده.
| Status | معنی |
|---|---|
| 400 | پارامتر یا body اشتباه است؛ مثلاً بازه تاریخ نامعتبر (bad_period، period_too_long)، سقف صفحه بیشتر از پلن (over_plan_limit)، فیلتری که داده ذخیره شده نمی تواند جوابش را بدهد (not_stored) صفحه ای که نمی شود رویش نوشت (not_a_wordpress_post)، درخواست تاریخچه نامعتبر (bad_limit، missing_page) به روزرسانی نامعتبر یک مورد جذب لینک (nothing_to_change، bad_status، bad_note، note_too_long) یا تغییر نامعتبر در رقبا (bad_action، bad_domain) |
| 401 | کلید ارسال نشده (missing_key)، یا ناشناخته است یا باطل شده (invalid_key) |
| 403 | scope لازم را ندارد (missing_scope)، سایت جزو سایت های کلید نیست (other_site)، یا صاحب کلید دسترسی اش را از دست داده (owner_left) |
| 404 | چنین سایت، مشکل، صفحه، بررسی، مورد جذب لینک یا رقیبی وجود ندارد (not_found)، یا چنین مسیری وجود ندارد (no_route) |
| 409 | چیزی از قبل در صف یا در حال اجراست (already_queued، already_running)، سایت اتصال WordPress ای ندارد که بتواند بنویسد (wordpress_not_connected، wordpress_not_writable)، یا Google Analytics وصل نیست یا اجازه دسترسی نمی دهد (ga4_not_connected، ga4_no_access) |
| 429 | به سقف ساعتی رسیده اید (rate_limited، 1,200 درخواست برای هر کلید در ساعت)، سهمیه روزانه تست سرعت تمام شده (budget_used)، امروز 3 بررسی شروع کرده اید (too_many_audits)، موضوع ها در یک دقیقه گذشته بیش از حد محاسبه شده اند، یا سهمیه API پراپرتی GA4 تمام شده (ga4_quota) |
| 502 | Google Analytics جواب نداد (ga4_unavailable) |
| 503 | API یا این قابلیت فعلاً خاموش است (api_disabled، feature_off) |
مثال
curl -H "Authorization: Bearer mr_ws_…" \
"https://app.monoranks.com/api/v1/sites/SITE_ID/actions?limit=5"
{
"waiting": 1,
"actions": [
{ "rank": 1, "issueId": "…", "title": "Missing meta description", "severity": "serious", "effort": "low",
"priority": 8.4, "estimatedScoreGain": 3.2, "status": "open", "ageDays": 16, "waitingWeeks": 2,
"writableField": "seo_description", "link": "https://app.monoranks.com/sites/SITE_ID/actions/…" }
]
}سؤال های رایج
SDK هم دارید؟
هنوز نه. اگر کلاینت تایپ دار می خواهید، سند OpenAPI در /api/v1/openapi.json با ابزارهای رایج تولید کلاینت (openapi-generator، Kiota، oazapfts) کار می کند.
با API می شود داده نوشت؟
چند عملیات نوشتن داریم و هرکدام scope خودش را دارد: گذاشتن بررسی دوباره در صف یا اجرای دوباره تست Agentic browsing (issues:recheck)، شروع بررسی کامل (audits:run)، و تأیید عنوان سئو، توضیحات متا، canonical، فایل llms.txt یا قوانین خزنده های هوش مصنوعی که MonoRanks بعد از تأیید، از طریق اتصال WordPress روی سایت می نویسد (actions:apply). هر تغییر تأییدشده را تا 30 روز در اپ می توانید برگردانید. همین scope وضعیت و یادداشت یک مورد جذب لینک را هم تعیین می کند و رقبا را انتخاب می کند، کنار می گذارد یا اضافه می کند؛ هیچ کدام چیزی را در سایت شما عوض نمی کند. بقیه endpointها فقط خواندنی اند.
چرا درآمد هر صفحه ga4_not_connected برمی گرداند؟
این endpoint از پراپرتی Google Analytics (GA4) خود سایت می خواند. اول در صفحه «بازدیدهای سایت» همان سایت، Google Analytics را وصل کنید. کلید هم باید scope analytics:read را داشته باشد؛ کلیدهایی که قبل از اضافه شدن این scope ساخته شده اند آن را ندارند، پس با Edit اضافه اش کنید.
endpointهای عمومی چطور؟
GET /api/v1/plans و GET /api/v1/changelog کلید نمی خواهند؛ سایت MonoRanks قیمت ها و یادداشت های انتشار را از همین ها نشان می دهد.