Añadir un objetivo de outreach
/sites/{siteId}/outreach- Permiso
actions:apply- Herramienta MCP
add_outreach_target
Add a page to the outreach list Like "Add a page" on the Outreach screen (source manual). A few minutes later MonoRanks measures it like a link gap target (reason.pageKind, reason.domainRank, reason.ourRank, reason.spamScore, inside the spending limits; reason.measureData says why some are missing; reason.measuredAt says when), then checks the page; measured again weekly. Answers 201 when added, 200 when the page was already listed: that target is returned with the given status, note and tags (tags replace its tags). Recorded in Activity as the key owner.
Las descripciones vienen del documento OpenAPI y están en inglés.
Parámetros
| Nombre | Dónde | Detalles |
|---|---|---|
siteIdObligatorio | ruta | stringWebsite id, from GET /sites. |
Cuerpo de la petición
| Campo | Detalles |
|---|---|
url | address (URL) · required; at most 2048 characters; Full http or https page address, not on the website itself and not a reserved test address |
note | string · at most 2000 characters; Your note, at most 2,000 characters |
status | to_contact | contacted | added | declined · Starting status (default to_contact) |
tags | list of string · at most 10 items; Labels for the target |
{
"url": "https://trailmag.example/gear/best-bike-shops/",
"note": "Editor asked for shop tips.",
"tags": [
"gear-review"
]
}Respuesta
200 · application/json
| Campo | Detalles |
|---|---|
created | true or false · required; True when the page was added now; false when it was already listed |
target | object · required |
target.id | string |
target.source | string |
target.url | string |
target.domain | string |
target.title | |
target.score | number |
target.class | string |
target.reason | object |
target.status | string |
target.statusAt | string |
target.statusAuto | true or false |
target.note | string |
target.tags | list of strings |
target.firstSeen | string |
target.lastSeen | string |
target.gone | true or false |
target.check | |
target.link | string |
Notas
GET /sites/{siteId}/outreach lista páginas y sitios a los que vale la pena pedir un enlace o una mención, ordenados: primero los objetivos abiertos por score (de 0 a 100), luego los contactados, añadidos y rechazados. Los objetivos que su fuente ya no encuentra (gone) van al final. MonoRanks no envía correos ni busca datos de contacto: lista los objetivos, tú haces el outreach y registras lo que pasó.
| Qué | Detalles |
|---|---|
source |
ai_source (las respuestas de IA a tus preguntas seguidas citan la página pero no te nombran), best_list (una lista de “los mejores X” que nombra a tus competidores pero no a ti), link_gap (un sitio que enlaza a dos o más de tus competidores, no a ti), lost_link (un sitio fuerte que dejó de enlazarte, donde la solución es pedirles que actualicen el enlace) o manual (añadido a mano). |
reason |
dice por qué, con los campos que conoce su fuente: por ejemplo questions, models y timesCited; keyword y position; competitors, domainRank, spamScore y outOf; o lostAt. |
status |
to_contact, contacted, added o declined. Filtra con status y source. counts tiene los totales por estado y por fuente. |
| Spam | Los objetivos con una puntuación de spam superior a 60 se dejan fuera salvo que pases spam=1; counts.spamHidden dice cuántos. |
| Escritura | POST /sites acepta status y/o note (como máximo 2.000 caracteres; una nota vacía la borra). El cambio queda registrado en la Activity del sitio web a nombre del dueño de la clave. El estado y la nota se mantienen cuando la fuente actualiza el objetivo. |
| Añadido por sí solo | Una vez por semana MonoRanks vuelve a leer cada página objetivo abierta, gratis. Cuando la página ya enlaza al sitio web o lo nombra, el objetivo pasa a added y statusAuto es true. |
Errores
| Estado | Significado |
|---|---|
400 | Bad request. Codes: bad_url, own_site, test_domain, bad_status, bad_note, note_too_long, bad_tags. |
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. |
429 | Too many requests this hour for this key. Codes: rate_limited. |
Petición de ejemplo
curl -X POST \
-H "Authorization: Bearer mr_ws_…" \
-H "Content-Type: application/json" \
-d '{"url":"https://trailmag.example/gear/best-bike-shops/","note":"Editor asked for shop tips.","tags":["gear-review"]}' \
"https://app.monoranks.com/api/v1/sites/SITE_ID/outreach"const res = await fetch("https://app.monoranks.com/api/v1/sites/SITE_ID/outreach", {
method: "POST",
headers: { Authorization: "Bearer mr_ws_…", "Content-Type": "application/json" },
body: JSON.stringify({
"url": "https://trailmag.example/gear/best-bike-shops/",
"note": "Editor asked for shop tips.",
"tags": [
"gear-review"
]
}),
});
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/outreach",
headers={"Authorization": "Bearer mr_ws_…"},
json={
"url": "https://trailmag.example/gear/best-bike-shops/",
"note": "Editor asked for shop tips.",
"tags": [
"gear-review",
],
},
)
res.raise_for_status()
data = res.json()<?php
$ch = curl_init("https://app.monoranks.com/api/v1/sites/SITE_ID/outreach");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => ["Authorization: Bearer mr_ws_…", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => '{"url":"https://trailmag.example/gear/best-bike-shops/","note":"Editor asked for shop tips.","tags":["gear-review"]}',
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/outreach",
{
"url": "https://trailmag.example/gear/best-bike-shops/",
"note": "Editor asked for shop tips.",
"tags": [
"gear-review"
]
},
{ headers: { Authorization: "Bearer mr_ws_…" } },
);Respuesta de ejemplo
{
"created": false,
"target": {
"id": "0b2d4f6a-8c0e-4a2c-9e4a-8c0e2a4c6e8a",
"source": "manual",
"url": "https://trailmag.example/gear/best-bike-shops/",
"domain": "trailmag.example",
"title": null,
"score": 50,
"class": "unknown",
"reason": {},
"status": "contacted",
"statusAt": "2026-10-06T10:20:00.000Z",
"statusAuto": false,
"note": "Editor asked for shop tips.",
"tags": [
"gear-review"
],
"firstSeen": "2026-10-06T10:15:00.000Z",
"lastSeen": "2026-10-06T10:15:00.000Z",
"gone": false,
"check": null,
"link": "https://app.monoranks.com/sites/3f6c2a1e-8b4d-4c7a-9e21-5d0b7a6f4c13/outreach?open=0b2d4f6a-8c0e-4a2c-9e4a-8c0e2a4c6e8a"
}
}{
"error": {
"code": "bad_url",
"message": "url must be a full http or https page address, like https://example.com/partners/."
}
}{
"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."
}
}El servidor MCP hace lo mismo con la herramienta add_outreach_target.