Pick, dismiss or add a competitor

curl -X POST \
  -H "Authorization: Bearer mr_ws_…" \
  -H "Content-Type: application/json" \
  -d '{"action":"add","domain":"cyclehub.example"}' \
  "https://app.monoranks.com/api/v1/sites/SITE_ID/competitors"

const res = await fetch("https://app.monoranks.com/api/v1/sites/SITE_ID/competitors", {
  method: "POST",
  headers: { Authorization: "Bearer mr_ws_…", "Content-Type": "application/json" },
  body: JSON.stringify({
    "action": "add",
    "domain": "cyclehub.example"
  }),
});
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/competitors",
    headers={"Authorization": "Bearer mr_ws_…"},
    json={
        "action": "add",
        "domain": "cyclehub.example",
    },
)
res.raise_for_status()
data = res.json()

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

{
  "action": "add",
  "domain": "cyclehub.example",
  "competitors": [
    {
      "domain": "bikeworld.example",
      "kind": "picked",
      "score": 78,
      "review": {
        "status": "not_reviewed",
        "sameKind": null,
        "kind": null,
        "reason": null
      },
      "drivesGaps": true,
      "sharedKeywords": 412,
      "brandKeywords": 6,
      "theirKeywords": 5810,
      "ourKeywords": 1240,
      "aboveUs": 188,
      "domainRank": 41,
      "category": "Shop",
      "visibility": [
        32800,
        35600,
        37900,
        41600
      ],
      "visibilityMonths": [
        "2026-06",
        "2026-07",
        "2026-08",
        "2026-09"
      ],
      "dataUpdatedAt": "2026-10-01T04:20:00.000Z"
    },
    {
      "domain": "cyclehub.example",
      "kind": "suggested",
      "score": 64,
      "review": {
        "status": "reviewed",
        "sameKind": true,
        "kind": "Online bike shop",
        "reason": "Sells bikes and parts to riders, like Acme Bikes."
      },
      "drivesGaps": true,
      "sharedKeywords": 412,
      "brandKeywords": 6,
      "theirKeywords": 5810,
      "ourKeywords": 1240,
      "aboveUs": 188,
      "domainRank": 41,
      "category": "Shop",
      "visibility": [
        32800,
        35600,
        37900,
        41600
      ],
      "visibilityMonths": [
        "2026-06",
        "2026-07",
        "2026-08",
        "2026-09"
      ],
      "dataUpdatedAt": "2026-10-01T04:20:00.000Z"
    }
  ],
  "ourVisibility": [
    12400,
    13900,
    14800,
    15700
  ],
  "ourVisibilityMonths": [
    "2026-06",
    "2026-07",
    "2026-08",
    "2026-09"
  ],
  "driving": [
    "bikeworld.example"
  ],
  "hidden": 3,
  "note": "kind: picked (chosen by a person) or suggested. Suggestions stay suggestions until picked.",
  "link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/competitors"
}

{
  "error": {
    "code": "bad_action",
    "message": "action must be one of pick, dismiss, add."
  }
}

{
  "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": "cyclehub.example is not in the competitor set. GET /competitors lists it; use action add for a new domain."
  }
}

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