API REST et serveur MCP

Offres et limites

L'API et le serveur MCP sont inclus à partir de l'offre Growth. Les limites s'appliquent par clé ; le quota journalier se réinitialise à 00:00 UTC. Les prix sont sur la page Tarifs.

• Changement d'offre : une offre qui n'inclut plus l'API (passage à SEO ou Free, résiliation, fin de période) arrête toutes les clés en moins d'une minute, avec 402 PLAN_REQUIRED. Les clés ne sont pas supprimées : elles refonctionnent si l'offre inclut de nouveau l'API.
• Passer à une offre avec moins de clés ne coupe pas les clés existantes, mais aucune nouvelle clé ne peut être créée tant que le nombre de clés actives dépasse l'offre.
• La visibilité IA suit la même règle que le tableau de bord : elle n'est servie que si l'offre inclut la part de voix IA.

Créer et révoquer une clé

1. Ouvrez Sources et rapports › Intégrations, rapports, MCP et API › Connecteur MCP et API dans votre espace de travail.
2. Donnez un nom à la clé (l'outil qui l'utilisera) et, si vous le souhaitez, une expiration (30, 90, 180 jours ou 1 an).
3. Copiez la clé affichée : elle n'est montrée qu'une seule fois. NeoRank n'en conserve qu'une empreinte (HMAC-SHA-256) et ne peut pas la réafficher.

• Seuls les administrateurs de l'organisation (propriétaire, administrateur) et de l'espace de travail peuvent créer ou révoquer une clé ; les autres membres voient la liste (nom, préfixe, auteur, dernière utilisation, état) en lecture seule.
• Une clé révoquée cesse de fonctionner immédiatement. Une clé cesse aussi de fonctionner si son auteur quitte l'espace de travail.
• Chaque création et chaque révocation sont inscrites au journal d'audit.

Authentification

Chaque requête envoie la clé dans l'en-tête Authorization: Bearer nrk_live_…. Les cookies de session ne sont jamais lus sur l'API : une clé est le seul moyen d'y accéder. Aucune origine tierce n'est autorisée par CORS ; appelez l'API depuis un serveur ou un outil, pas depuis un navigateur.

curl -H "Authorization: Bearer nrk_live_…" https://neorank.ai/api/v1/sites

Points d'accès (lecture seule)

Format des réponses

Toute réponse est un objet data accompagné de meta (espace de travail, date de génération, source des chiffres, pagination). Une erreur est un objet error avec un code stable et un message. `null` signifie « non mesuré », jamais zéro ; un champ state indique pourquoi un bloc est vide (not-connected, not-measured, plan-required…).

{
  "data": [{ "id": "…", "name": "Example", "domain": "example.com", "createdAt": "…" }],
  "meta": { "workspaceId": "…", "generatedAt": "…", "source": "NeoRank workspace", "returned": 1 }
}

{ "error": { "code": "PLAN_REQUIRED", "message": "…" } }

Limites de débit

X-RateLimit-Limit / Remaining / Reset

La fenêtre d'une minute de la clé (Reset en secondes).

X-RateLimit-Daily-Limit / Daily-Remaining / Daily-Reset

Le quota du jour UTC de la clé (Reset en secondes jusqu'à minuit UTC).

Retry-After

Sur une réponse 429 : le nombre de secondes à attendre.

Erreurs

Serveur MCP

Le serveur MCP distant répond à https://neorank.ai/api/mcp (Streamable HTTP, sans état, réponses JSON) avec la même clé, les mêmes limites et la même vérification d'offre. Outils en lecture seule : list_sites, get_site_overview, get_ai_visibility, get_rankings, get_audit_issues, get_backlinks_summary. L'adresse exacte de votre instance et des configurations prêtes à copier figurent dans l'onglet Connecteur MCP et API.

Claude Code (terminal) :

claude mcp add --transport http neorank https://neorank.ai/api/mcp --header "Authorization: Bearer nrk_live_…"

Cursor et les clients MCP qui acceptent une adresse distante et des en-têtes (configuration JSON des serveurs MCP du client) :

{
  "mcpServers": {
    "neorank": {
      "url": "https://neorank.ai/api/mcp",
      "headers": { "Authorization": "Bearer nrk_live_…" }
    }
  }
}

Claude Desktop : par le pont mcp-remote (Node.js requis), qui relaie les requêtes vers le serveur distant avec l'en-tête :

{
  "mcpServers": {
    "neorank": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://neorank.ai/api/mcp", "--header", "Authorization:${NEORANK_AUTH}"],
      "env": { "NEORANK_AUTH": "Bearer nrk_live_…" }
    }
  }
}

Sécurité

• Clés : préfixe public indexé, secret de 256 bits, empreinte HMAC-SHA-256 avec un secret serveur, comparaison à temps constant.
• Isolation : chaque requête est limitée à l'espace de travail de la clé ; un identifiant de site d'un autre espace répond 404.
• Journal : méthode, route, statut, clé et durée de chaque requête ; jamais le corps ni la clé.
• Serveur MCP : corps limité à 64 Kio, origine de navigateur tierce refusée, aucun appel réseau vers l'extérieur.