REST API

Q: SDK هم دارید؟

هنوز نه. اگر کلاینت تایپدار میخواهید، سند OpenAPI در /api/v1/openapi.json با ابزارهای رایج تولید کلاینت (openapi-generator، Kiota، oazapfts) کار میکند.

Q: endpointهای عمومی چطور؟

GET /api/v1/plans و GET /api/v1/changelog کلید نمیخواهند؛ سایت MonoRanks قیمتها و یادداشتهای انتشار را از همینها نشان میدهد.

یک base URL، یک bearer key، ورودی و خروجی JSON. هر چیزی که اپ برای یک سایت نشان می‌دهد، از اینجا هم در دسترس است.

نویسنده: MonoRanksبه‌روزرسانی 9 مهر 14058 دقیقه مطالعه

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 → API and MCP → New credential بسازید. این کلید یا به همه سایت‌ها دسترسی دارد یا فقط به سایت‌هایی که تیک می‌زنید. کلید سایت (mr_site_…) وقتی ساخته می‌شود که افزونه WordPress یا اپ Shopify وصل شود و فقط به همان یک سایت دسترسی دارد. هر کلید فقط یک بار نمایش داده می‌شود. جزئیات را در کلیدهای API و scopeها ببینید.

Endpointها

همه مسیرهای زیر بعد از base URL می‌آیند.

سایت‌ها و امتیازها

متد و مسیر	خروجی	Scope
`GET /sites`	سایت‌هایی که این کلید به آن‌ها دسترسی خواندن دارد، با id هرکدام	`sites:read`
`GET /portfolio`	همه سایت‌های این کلید در یک درخواست، مثل لیست Websites: امتیازها، تغییرشان نسبت به بررسی قبلی و هفته قبل، مشکل‌های باز، اکشن‌های منتظر، آخرین بررسی، بررسی بعدی و کلیک‌های Search Console (با `search:read`)	`sites:read`
`GET /sites/{siteId}`	خلاصه سایت: امتیازها، آخرین بررسی، مشکل‌های باز، دسترسی WordPress و اینکه داده هر اتصال چقدر تازه است	`sites:read`
`GET /sites/{siteId}/scores`	امتیاز فعلی و تاریخچه 13 هفته، همراه با نسخه امتیاز	`sites:read`
`GET /sites/{siteId}/performance`	سرعت هر صفحه‌ای که تست شده: نتیجه تست آزمایشگاهی کنار داده بازدیدکننده‌های واقعی Chrome، و اینکه هر یافته سرعت بر اساس کدام‌یک است	`sites:read`

مشکل‌ها و اکشن‌ها

متد و مسیر	خروجی	Scope
`GET /sites/{siteId}/issues`	مشکل‌ها، همان لیست صفحه Issues (پیش‌فرض: باز، دوباره‌باز، در حال انجام، در صف بررسی دوباره؛ `status=` لیستی جداشده با کاما می‌گیرد)	`issues:read`
`GET /sites/{siteId}/issues/{issueId}`	یک مشکل، با صفحه‌های درگیر، شواهد، توضیح هوش مصنوعی، مقدارهای جدید پیشنهادی و آخرین تغییر تأییدشده	`issues:read`
`POST /sites/{siteId}/issues/{issueId}/recheck`	بررسی دوباره را در صف می‌گذارد؛ مشکل فقط وقتی حل‌شده حساب می‌شود که بررسی دوباره دیگر پیدایش نکند	`issues:recheck`
`GET /sites/{siteId}/actions`	اکشن‌ها به ترتیب اولویت، با افزایش تخمینی امتیاز و مدتی که هرکدام باز مانده (`limit`، پیش‌فرض 25، حداکثر 100)	`issues:read`
`POST /sites/{siteId}/actions/{issueId}/apply`	عنوان سئو، توضیحات متا، canonical یا noindex جدید را تأیید می‌کند و از طریق اتصال WordPress روی سایت می‌نویسد	`actions:apply`

صفحه‌ها

متد و مسیر	خروجی	Scope
`GET /sites/{siteId}/pages`	صفحه‌هایی که کراول شده‌اند (`q` برای جست‌وجو، `page`، `per` تا 200)	`pages:read`
`GET /sites/{siteId}/pages/{pageId}`	مشخصات صفحه، امتیازها و یافته‌ها	`pages:read`
`GET /sites/{siteId}/pages/findings?url=`	همان، ولی با آدرس صفحه	`pages:read`

Search Console

متد و مسیر	خروجی	Scope
`GET /sites/{siteId}/search/summary`	جمع 7، 28 یا 90 روز (`days=`) در مقایسه با دوره قبل، به‌همراه صفحه‌ها و عبارت‌های جست‌وجوی برتر	`search:read`
`GET /sites/{siteId}/search/rows`	ردیف‌های یک بازه تاریخ، به تفکیک عبارت جست‌وجو، صفحه، عبارت و صفحه با هم، یا روز؛ صفحه‌بندی‌شده، یا با `format=csv` در قالب یک فایل CSV	`search:read`

دیده‌شدن و آمادگی برای هوش مصنوعی

متد و مسیر	خروجی	Scope
`GET /sites/{siteId}/ai-visibility`	دستیارهای هوش مصنوعی هر هفته به سؤال‌هایی که برای سایت دنبال می‌کنید چه جوابی داده‌اند	`ai:read`
`GET /sites/{siteId}/ai-visibility/gaps`	سؤال‌هایی که در جواب هوش مصنوعی اسم سایت‌های دیگر می‌آید، ولی اسم این سایت هیچ‌وقت نمی‌آید	`ai:read`
`GET /sites/{siteId}/geo`	دسترسی خزنده‌های هوش مصنوعی در robots.txt، وضعیت llms.txt و سیگنال‌های هویت برند از آخرین بررسی	`ai:read`
`GET /sites/{siteId}/geo/llms-txt`	فایل `/llms.txt` فعلی سایت که همین لحظه خوانده می‌شود، به‌همراه یک پیش‌نویس آماده انتشار که از صفحه‌های شما ساخته شده	`ai:read`
`POST /sites/{siteId}/geo/llms-txt`	یک `/llms.txt` جدید را تأیید می‌کند و از طریق اتصال WordPress روی سایت می‌نویسد	`actions:apply`
`GET /sites/{siteId}/geo/ai-crawlers`	robots.txt فعلی، که همین لحظه خوانده می‌شود، به هر خزنده هوش مصنوعی چه می‌گوید، و آخرین قوانینی که MonoRanks نوشته	`ai:read`
`POST /sites/{siteId}/geo/ai-crawlers`	قوانین allow یا deny را برای هر خزنده هوش مصنوعی تأیید می‌کند و در robots.txt می‌نویسد	`actions:apply`
`GET /sites/{siteId}/agentic`	نتیجه‌های Agentic browsing (آیا یک ایجنت هوش مصنوعی می‌تواند با صفحه کار کند)، برای هر صفحه تست‌شده و هر دستگاه، با کارهایی که باید درست کنید	`ai:read`
`POST /sites/{siteId}/agentic/run`	تست Agentic browsing را برای یک صفحه دوباره اجرا می‌کند؛ پاسخ `202` با یک job id است	`issues:recheck`
`GET /sites/{siteId}/agentic/runs/{jobId}`	وضعیت و نتیجه یک اجرای دوباره	`ai:read`

بررسی‌ها

متد و مسیر	خروجی	Scope
`GET /sites/{siteId}/audits`	آخرین بررسی‌ها، بررسی‌ای که الان در حال اجراست، بررسی هفتگی بعدی، سقف صفحه‌ها و تعداد شروع‌هایی که امروز باقی مانده	`sites:read`
`POST /sites/{siteId}/audits`	همین حالا یک بررسی کامل شروع می‌کند، با `pageBudget` اختیاری؛ پاسخ `202` با یک audit id است	`audits:run`
`GET /sites/{siteId}/audits/{auditId}`	یک بررسی: وضعیت، تعداد صفحه‌هایی که تا الان کراول شده، پوشش نقشه سایت، و اگر زودتر تمام شده، دلیلش	`sites:read`

عمومی، بدون کلید

متد و مسیر	خروجی
`GET /openapi.json`	سند OpenAPI 3.1 برای همه endpointهای بالا
`GET /plans`	پلن‌ها و قیمت‌ها
`GET /changelog`	یادداشت‌های انتشار به فرمت Markdown

صفحه‌بندی

صفحه‌بندی هر لیست کمی فرق دارد و جزئیاتش در سند OpenAPI هست:

GET /portfolio، GET /sites/{siteId}/pages و GET /sites/{siteId}/agentic پارامترهای page (از 1) و per (پیش‌فرض 50، حداکثر 200) را می‌گیرند.
GET /sites/{siteId}/search/rows مقدار nextCursor را برمی‌گرداند؛ آن را به‌عنوان cursor دوباره بفرستید تا وقتی null شود. limit بین 1 تا 10,000 است (پیش‌فرض 1,000).
پیشنهادهای هر مشکل 100 تا 100 تا برمی‌گردند؛ پایین‌تر توضیح داده‌ایم.
GET /sites/{siteId}/actions پارامتر limit می‌گیرد؛ GET /sites/{siteId}/audits هم limit می‌گیرد (پیش‌فرض 5، حداکثر 25).

مقدارهای پیشنهادی برای یک مشکل

برای مشکل‌هایی که MonoRanks می‌تواند اصلاحشان کند (عنوان سئو، توضیحات متا، canonical یا ریدایرکت)، GET /sites/{siteId}/issues/{issueId} فیلد suggestions را هم برمی‌گرداند: برای هر صفحه درگیر، مقدار فعلی و مقداری که MonoRanks پیشنهاد می‌کند. این‌ها همان مقدارهایی هستند که اپ قبل از زدن Apply نشان می‌دهد.

"suggestions": [
  { "url": "https://example.com/pricing/", "pageId": "…", "current": "Pricing", "suggested": "Pricing | Example", "writable": true }
],
"suggestionsTotal": 240,
"suggestionsOffset": 0,
"suggestionsLimit": 100,
"suggestionsNextOffset": 100,
"suggestionsTruncated": true

صفحه‌بندی. هر درخواست حداکثر 100 مورد برمی‌گرداند. برای بقیه، دوباره درخواست بدهید و ?suggestions_offset= را برابر suggestionsNextOffset بگذارید؛ بعد از آخرین صفحه این مقدار null است. اندازه هر صفحه را با suggestions_limit (1 تا 100) تعیین کنید. نوشتن به شکل suggestionsOffset و suggestionsLimit هم کار می‌کند.
suggested وقتی null است که MonoRanks مقدار جدید خوبی برای آن صفحه ندارد. عنوان‌های خیلی بلند با قوانین ثابت کوتاه می‌شوند؛ موضوع صفحه حفظ می‌شود و هیچ عبارتی از وسط بریده نمی‌شود. اگر هیچ عنوان کوتاه‌تری جواب ندهد، suggested برابر null است و می‌توانید خودتان در اپ عنوان بنویسید.
suggestionsNote (فقط برای عنوان‌ها) وقتی پر می‌شود که سایت حروف بزرگ و کوچک عنوان‌ها را روی صفحه تغییر می‌دهد؛ مثلاً تنظیم Capitalize Titles در Rank Math.
writable وقتی false است (همراه با notWritableReason) که apply نمی‌تواند روی آن صفحه بنویسد؛ مثلاً آرشیو یک دسته‌بندی که پست یا برگه WordPress نیست. این صفحه‌ها را برای apply نفرستید.
advice (فقط برای توضیحات متا) می‌گوید کدام صفحه شاید اصلاً توضیحات لازم نداشته باشد: صفحه حقوقی یا آرشیو (خالی بگذارید یا noindex کنید)، آرشیو خالی (پست اضافه کنید یا noindex کنید)، یا صفحه ورود، حساب کاربری، سبد خرید یا پرداخت (noindex کنید؛ برای این‌ها توضیحاتی پیشنهاد نمی‌شود).
titleTemplate (برای عنوان‌های خیلی بلند) وقتی پر می‌شود که یک بخش مشترک در انتهای قالب عنوان افزونه سئو بیشتر عنوان‌ها را بلند کرده؛ در این حالت با یک تغییر در قالب، همه درست می‌شوند.
lastRecheck نتیجه آخرین بررسی دوباره است. بررسی دوباره همه صفحه‌های لیست را از نو می‌خواند، پس صفحه‌هایی که درستشان کرده‌اید از لیست بیرون می‌روند. صفحه‌ای که پاسخ نداده در لیست می‌ماند و در lastRecheck.notRechecked شمرده می‌شود.
lastChange آخرین دسته تغییر تأییدشده است، با وضعیت هر تغییر. not_live یعنی مقدار نوشته شده، ولی صفحه هنوز مقدار دیگری نشان می‌دهد؛ notLiveReason دلیلش را می‌گوید، از جمله اینکه کش صفحه‌های سایت بعد از نوشتن پاک شده یا نه. بررسی دوباره این تغییرها را هم دوباره چک می‌کند. اگر عنوان یا توضیحات فقط در حروف بزرگ و کوچک، فاصله، گیومه یا خط‌تیره فرق داشته باشد، live حساب می‌شود؛ در این حالت liveNote می‌گوید چه چیزی آن را تغییر داده است.

مقدارهایی را که تأیید می‌کنید با این شکل به POST /sites/{siteId}/actions/{issueId}/apply بفرستید: { "changes": [ { "url": "…", "value": "…" } ] } (حداکثر 500 مورد). apply از طریق API فقط عنوان سئو، توضیحات متا، canonical و noindex را می‌نویسد؛ متن alt تصویرها و ریدایرکت‌ها را باید در اپ اعمال کنید.

آدرس‌های ایمیل شخصی در متن صفحه‌هایی که MonoRanks ذخیره می‌کند پنهان می‌شوند؛ مثلاً j•••@gmail.com.

مثال

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/…" }
  ]
}

شروع یک بررسی

curl -X POST -H "Authorization: Bearer mr_ws_…" -H "Content-Type: application/json" \
  -d '{ "pageBudget": 1000 }' "https://app.monoranks.com/api/v1/sites/SITE_ID/audits"

پاسخ فوراً با 202، یک auditId و یک آدرس poll برمی‌گردد. بعد حدوداً هر دقیقه یک بار با GET /sites/{siteId}/audits/{auditId} وضعیت را چک کنید. pageBudget اختیاری است و حداکثرش تعداد صفحه‌های هر بررسی در پلن شماست: Free 200، Starter 500، Agency 1,000، Enterprise 10,000. برای هر سایت در هر لحظه فقط یک کراول اجرا می‌شود، و از طریق API و MCP روزانه حداکثر 3 بررسی برای هر سایت می‌توانید شروع کنید. بررسی هفتگی هم طبق روال اجرا می‌شود.

خطاها و محدودیت‌ها

خطاها این شکل را دارند: { "error": { "code": "…", "message": "…" } }

Status	معنی
400	پارامتر یا body اشتباه است؛ مثلاً بازه تاریخ نامعتبر، سقف صفحه بیشتر از پلن، یا صفحه‌ای که نمی‌شود رویش نوشت
401	کلید ارسال نشده، ناشناخته است یا باطل شده
403	scope لازم را ندارد، سایت جزو سایت‌های کلید نیست، یا صاحب کلید دسترسی‌اش را از دست داده
404	چنین سایت، مشکل، صفحه، بررسی یا مسیری وجود ندارد
409	چیزی از قبل در صف یا در حال اجراست (بررسی دوباره، بررسی کامل، یا همان اجرای Agentic browsing)، یا سایت اتصال WordPress‌ای ندارد که بتواند بنویسد
429	به سقف ساعتی رسیده‌اید (1,200 درخواست برای هر کلید در ساعت)، سهمیه روزانه تست سرعت تمام شده، یا امروز 3 بررسی شروع کرده‌اید
503	API یا این قابلیت فعلاً خاموش است

هر کلید با دسترسی کسی کار می‌کند که آن را ساخته. اگر آن شخص از فضای کاری خارج شود یا نقشش به بیننده مشتری (client viewer) تغییر کند، کلید دیگر کار نمی‌کند.

سؤال‌های رایج

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 روز در اپ می‌توانید برگردانید. بقیه endpointها فقط خواندنی‌اند.

endpointهای عمومی چطور؟

GET /api/v1/plans و GET /api/v1/changelog کلید نمی‌خواهند؛ سایت MonoRanks قیمت‌ها و یادداشت‌های انتشار را از همین‌ها نشان می‌دهد.