Documentación para desarrolladores

Añadir un objetivo de outreach

POST/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

NombreDóndeDetalles
siteIdObligatoriorutastringWebsite id, from GET /sites.

Cuerpo de la petición

CampoDetalles
urladdress (URL) · required; at most 2048 characters; Full http or https page address, not on the website itself and not a reserved test address
notestring · at most 2000 characters; Your note, at most 2,000 characters
statusto_contact | contacted | added | declined · Starting status (default to_contact)
tagslist 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

CampoDetalles
createdtrue or false · required; True when the page was added now; false when it was already listed
targetobject · required
target.idstring
target.sourcestring
target.urlstring
target.domainstring
target.title
target.scorenumber
target.classstring
target.reasonobject
target.statusstring
target.statusAtstring
target.statusAutotrue or false
target.notestring
target.tagslist of strings
target.firstSeenstring
target.lastSeenstring
target.gonetrue or false
target.check
target.linkstring

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/{siteId}/outreach/{targetId} 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

EstadoSignificado
400Bad request. Codes: bad_url, own_site, test_domain, bad_status, bad_note, note_too_long, bad_tags.
401Missing, unknown or revoked key. Codes: missing_key, invalid_key.
403The key lacks the scope, covers another website, or its owner lost access. Codes: missing_scope, other_site, owner_left, no_owner, forbidden.
404Not found. Codes: not_found.
429Too 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"

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

El servidor MCP hace lo mismo con la herramienta add_outreach_target.