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

Track a keyword daily, or stop

POST/sites/{siteId}/keywords/track

Scope: actions:write
ابزار MCP: track_keyword

Track a keyword daily, or stop The star on a Keywords row: Google positions are checked every day (once a week the top 100). The keyword must be in the list; POST /sites/{siteId}/actions adds a gap keyword. Starting counts against the plan's tracked keywords and posts the first check at once. Recorded in the website's Activity as the key owner.

توضیح ها از سند OpenAPI می آیند و انگلیسی اند.

پارامترها

نام	محل	توضیح
`siteId`اجباری	path	stringWebsite id, from GET /sites.

بدنه درخواست

فیلد	توضیح
`keyword_id`	string · Keyword id, from GET /keywords
`keyword`	string · Or the keyword text, in the website's current location
`on`	true or false · Default true; false stops tracking

{
  "keyword": "gravel bike tires"
}

پاسخ

200 · application/json

فیلد	توضیح
`keyword`	object · required
`keyword.id`	string · required; Keyword id
`keyword.keyword`	string · required; The search phrase
`keyword.tracked`	true or false · required; Checked daily now
`link`	address (URL) · required; The Keywords screen in the app

خطاها

کد	معنی
`400`	Bad request. Codes: `missing_keyword`, `bad_on`, `not_tracked`.
`401`	Missing, unknown or revoked key. Codes: `missing_key`, `invalid_key`.
`403`	The key lacks the scope, covers another website, or its owner lost access. Codes: `missing_scope`, `other_site`, `owner_left`, `no_owner`, forbidden.
`404`	Not found. Codes: `not_found`, `keyword_not_found`.
`429`	Too many requests this hour for this key. Codes: `rate_limited`.

نمونه درخواست

curl -X POST \
  -H "Authorization: Bearer mr_ws_…" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"gravel bike tires"}' \
  "https://app.monoranks.com/api/v1/sites/SITE_ID/keywords/track"

const res = await fetch("https://app.monoranks.com/api/v1/sites/SITE_ID/keywords/track", {
  method: "POST",
  headers: { Authorization: "Bearer mr_ws_…", "Content-Type": "application/json" },
  body: JSON.stringify({
    "keyword": "gravel bike tires"
  }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

import requests

res = requests.post(
    "https://app.monoranks.com/api/v1/sites/SITE_ID/keywords/track",
    headers={"Authorization": "Bearer mr_ws_…"},
    json={
        "keyword": "gravel bike tires",
    },
)
res.raise_for_status()
data = res.json()

<?php
$ch = curl_init("https://app.monoranks.com/api/v1/sites/SITE_ID/keywords/track");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer mr_ws_…", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"keyword":"gravel bike tires"}',
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

import axios from "axios";

const { data } = await axios.post(
  "https://app.monoranks.com/api/v1/sites/SITE_ID/keywords/track",
  {
    "keyword": "gravel bike tires"
  },
  { headers: { Authorization: "Bearer mr_ws_…" } },
);

نمونه پاسخ

{
  "keyword": {
    "id": "2d4f6b8d-0f2b-4d4f-9b6d-0f2b4d6f8b0d",
    "keyword": "gravel bike tires",
    "tracked": true
  },
  "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/keywords"
}

{
  "error": {
    "code": "missing_keyword",
    "message": "Send keyword (the text) or keyword_id (from GET /keywords)."
  }
}

{
  "error": {
    "code": "missing_key",
    "message": "Send the key as Authorization: Bearer mr_site_…"
  }
}

{
  "error": {
    "code": "missing_scope",
    "message": "This key does not have the scope this call needs."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Website not found."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "More than 1200 requests this hour for this key."
  }
}

سرور MCP همین کار را با ابزار track_keyword انجام می دهد.