Apply a title or description to any page · REST API

Apply a title or description to any page Approves a new SEO title or meta description for any crawled page of a connected WordPress site, not only the pages of an action (for example the main page picked for a keyword), writes it through the WordPress connector, then rechecks. Recorded against the page and the keyword you send, not an action, so no action changes status. The key owner is recorded as approver; undo is in the app (Activity) for 30 days. A category or tag archive is written too when the WordPress plugin supports it (update the plugin otherwise); a page MonoRanks cannot write is refused with not_writable and the reason.

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

پارامترها

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

بدنه درخواست

فیلد	توضیح
`field`	seo_title \| seo_description · required; The field to write
`changes`	list of object · required; at most 100 items; One change per page, at most 100
`changes[].url`	string · required; A crawled page that is a published WordPress post, page or product synced to MonoRanks
`changes[].value`	string · required; The new value
`keyword`	string · Optional: the keyword the page targets, recorded with the change

{
  "field": "seo_title",
  "keyword": "trail bikes",
  "changes": [
    {
      "url": "https://acmebikes.com/",
      "value": "Trail Bikes Built for Real Trails | Acme Bikes"
    }
  ]
}

پاسخ

200 · application/json

فیلد	توضیح
`approved`	integer · required; Changes approved
`batchId`	string · required; Batch id; the change shows in Activity
`field`	seo_title \| seo_description · required; The field written
`keyword`	string or null · required; The keyword recorded, or null
`note`	string · required; What happens next
`link`	string · required; Activity in the app, where Undo is

خطاها

کد	معنی
`400`	Bad request. Codes: `field_not_supported`, `no_changes`, `no_change`, `too_many`.
`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`, `page_not_found`.
`409`	Conflict with the current state. Codes: `not_connected`, `not_writable_site`, `seo_plugin`.
`422`	The request cannot be carried out. Codes: `not_writable`.
`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 '{"field":"seo_title","keyword":"trail bikes","changes":[{"url":"https://acmebikes.com/","value":"Trail Bikes Built for Real Trails | Acme Bikes"}]}' \
  "https://app.monoranks.com/api/v1/sites/SITE_ID/pages/apply"

const res = await fetch("https://app.monoranks.com/api/v1/sites/SITE_ID/pages/apply", {
  method: "POST",
  headers: { Authorization: "Bearer mr_ws_…", "Content-Type": "application/json" },
  body: JSON.stringify({
    "field": "seo_title",
    "keyword": "trail bikes",
    "changes": [
      {
        "url": "https://acmebikes.com/",
        "value": "Trail Bikes Built for Real Trails | Acme Bikes"
      }
    ]
  }),
});
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/pages/apply",
    headers={"Authorization": "Bearer mr_ws_…"},
    json={
        "field": "seo_title",
        "keyword": "trail bikes",
        "changes": [
            {
                "url": "https://acmebikes.com/",
                "value": "Trail Bikes Built for Real Trails | Acme Bikes",
            },
        ],
    },
)
res.raise_for_status()
data = res.json()

<?php
$ch = curl_init("https://app.monoranks.com/api/v1/sites/SITE_ID/pages/apply");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer mr_ws_…", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"field":"seo_title","keyword":"trail bikes","changes":[{"url":"https://acmebikes.com/","value":"Trail Bikes Built for Real Trails | Acme Bikes"}]}',
    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/pages/apply",
  {
    "field": "seo_title",
    "keyword": "trail bikes",
    "changes": [
      {
        "url": "https://acmebikes.com/",
        "value": "Trail Bikes Built for Real Trails | Acme Bikes"
      }
    ]
  },
  { headers: { Authorization: "Bearer mr_ws_…" } },
);

نمونه پاسخ

{
  "approved": 1,
  "batchId": "f6b8d0f2-4a6c-4e8a-ac2e-6a8cae2a4c6d",
  "field": "seo_title",
  "keyword": "trail bikes",
  "note": "Written by the worker, then rechecked. A value the recheck does not find on the live page gets status not_live. Undo is available in the app (Activity) for 30 days.",
  "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/activity"
}

{
  "error": {
    "code": "field_not_supported",
    "message": "field must be seo_title or seo_description."
  }
}

{
  "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": "not_connected",
    "message": "Connect WordPress first."
  }
}

{
  "error": {
    "code": "not_writable",
    "message": "https://acmebikes.com/category/gravel/ is a category or tag archive. Update the MonoRanks plugin in WordPress so MonoRanks can write its title and description."
  }
}

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

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