Add a keyword to the action list · REST API

Add a keyword to the action list "Add to actions" on a Keywords or Keyword gaps row: a "New content" task, or "Improve page" when the website ranks on page 1–2. A keyword not in the list yet (a gap keyword) is added first, which uses one keyword lookup. One action per keyword: adding it again returns the action it has (200, created false), and a done or removed one is opened again. Recorded in the website's Activity as the key owner.

Parameters

Name	In	Details
`siteId`Required	path	stringWebsite id, from GET /sites.

Request body

Field	Details
`keyword`	string · at most 120 characters; The keyword text
`keyword_id`	string · Or the keyword id, from GET /keywords

{
  "keyword": "tubeless gravel tires"
}

Response

200 · application/json

Field	Details
`created`	true or false · required; True when the action was made now; false when the keyword already had one
`action`	object · required
`action.id`	string · required; Action id (issueId), for GET /issues/{issueId} and remove
`action.ruleId`	KW-OPP-001 \| KW-OPP-002 · required; KW-OPP-001: new content; KW-OPP-002: improve the page that ranks
`action.title`	string · required; Action title
`action.status`	open \| in_progress \| recheck_queued \| resolved \| ignored \| reopened · required; Where the action stands
`action.link`	address (URL) · required; The action in the app
`keyword`	object · required
`keyword.id`	string · required; Keyword id
`keyword.keyword`	string · required; The search phrase
`keyword.tracked`	true or false · required; Checked daily (starred)
`keyword.addedToList`	true or false · required; True when this call added the keyword to the list (one lookup)

Errors

Status	Meaning
`400`	Bad request. Codes: `missing_keyword`, `bad_keyword`, `not_added`.
`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`.

Example request

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

const res = await fetch("https://app.monoranks.com/api/v1/sites/SITE_ID/actions", {
  method: "POST",
  headers: { Authorization: "Bearer mr_ws_…", "Content-Type": "application/json" },
  body: JSON.stringify({
    "keyword": "tubeless gravel 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/actions",
    headers={"Authorization": "Bearer mr_ws_…"},
    json={
        "keyword": "tubeless gravel tires",
    },
)
res.raise_for_status()
data = res.json()

<?php
$ch = curl_init("https://app.monoranks.com/api/v1/sites/SITE_ID/actions");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer mr_ws_…", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => '{"keyword":"tubeless gravel 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/actions",
  {
    "keyword": "tubeless gravel tires"
  },
  { headers: { Authorization: "Bearer mr_ws_…" } },
);

Example response

{
  "created": false,
  "action": {
    "id": "b2e4c6a8-1d3f-4a5b-9c7d-0e2f4a6b8c1d",
    "ruleId": "KW-OPP-001",
    "title": "New content: tubeless gravel tires",
    "status": "open",
    "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/actions/b2e4c6a8-1d3f-4a5b-9c7d-0e2f4a6b8c1d"
  },
  "keyword": {
    "id": "2d4f6b8d-0f2b-4d4f-9b6d-0f2b4d6f8b0d",
    "keyword": "tubeless gravel tires",
    "tracked": false,
    "addedToList": false
  }
}

{
  "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."
  }
}

The MCP server does the same with the tool add_keyword_to_actions.