مستندات توسعه دهندگان

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 می آیند و انگلیسی اند.

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

بررسی ها و مشکل ها

اکشن ها

صفحه ها

Google Analytics

کلمات کلیدی

رقبا

جذب لینک

دیده شدن در هوش مصنوعی

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

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

صفحه بندی

لیست ها صفحه به صفحه می آیند. این جدول هر endpoint صفحه بندی شده را نشان می دهد: با چه پارامترهایی صفحه می خورد و از کجا می فهمید صفحه بعدی هست.

Endpointپارامترهاپیش فرض / حداکثرخروجی
GET/portfoliopage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/reportslimitlimit 5 / 20–
GET/sites/{siteId}/issues/{issueId}suggestions_offset suggestions_limitsuggestions_offset 0 / 1,000,000
suggestions_limit 100 / 100
suggestionsNextOffset
GET/sites/{siteId}/auditslimitlimit 5 / 25–
GET/sites/{siteId}/actionslimitlimit 25 / 100–
GET/sites/{siteId}/pagespage perpage 1 / –
per 50 / 200
total
GET/sites/{siteId}/pages/{pageId}/historylimitlimit 30 / 100more
GET/sites/{siteId}/pages/historylimitlimit 30 / 100more
GET/sites/{siteId}/search/rowspage limit cursorlimit 1,000 / 10,000nextCursor
GET/sites/{siteId}/topicslimitlimit 50 / 200–
GET/sites/{siteId}/search/near-page-onepage perpage 1 / –
per 50 / 500
total hasMore
GET/sites/{siteId}/analytics/pageslimit offset cursorlimit 100 / 1,000
offset 0 / 1,000,000
total nextCursor nextOffset
GET/sites/{siteId}/keywordspage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/competitors/gapspage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/competitors/content-ideaspage perpage 1 / –
per 20 / 200
total hasMore
GET/sites/{siteId}/backlinkspage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/outreachpage perpage 1 / –
per 50 / 200
total hasMore
GET/sites/{siteId}/ai-visibilitylimitlimit 50 / 1,000–
GET/sites/{siteId}/agenticpage perpage 1 / 10,000
per 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 قیمت ها و یادداشت های انتشار را از همین ها نشان می دهد.