Early Access

API- en MCP-documentatie

Wat de Pushrank MCP-server beschikbaar stelt en hoe u die handmatig via de API aanroept.

Beschikbare tools

De Pushrank MCP-server stelt 49 tools beschikbaar. Alle antwoorden zijn beperkt tot de projecten van uw organisatie; de 26 schrijfacties zijn hieronder gemarkeerd. Alleen de vermelde parameters worden geaccepteerd: een niet-gedeclareerde parameter wordt geweigerd met een foutmelding die de sleutel noemt, en nooit stilzwijgend genegeerd.

whoami

Toon de geverifieerde gebruiker, toegankelijke organisaties, toegekende scopes, tegoedsaldi en handige Pushrank-links.

Parameters: Geen. Alleen-lezen, zonder extra scope.

list_projects

Toon de Pushrank-projecten waartoe de geverifieerde gebruiker toegang heeft.

Parameters: limit (1–50, standaard 25).

get_project_overview

Compact overzicht van één project: verkeer, samenvatting van de digest en aantallen per status.

Parameters: projectId.

get_seo_forecast

SEO-prognose van één project, alleen-lezen: de schatting van Pushrank (schuifregelaar in de standaardpositie) met de curve, M6, M12, cumulatief totaal, kosten, drempel, dekking, consultantbenchmark, aannames en herkomst, of de reden waarom ze niet beschikbaar is. Hetzelfde detailniveau als de app voor het account. Een aanname, geen garantie.

Parameters: projectId.

list_seo_opportunities

Haal automatisch de volledige lijst SEO-acties op die bij uw verzoek passen, standaard de actieve, en laat de assistent ze als tabel weergeven. Bereik en levenscyclusstatussen komen overeen met het scherm Acties; het antwoord legt ook uit welke acties op dat scherm verborgen zijn.

Parameters: projectId; optioneel: status (standaard active | todo | in_progress | done | verified | still_present | ignored | all), type, severity, priority, source, query, pageUrl, priorityMin. Standaard pagination=all; pagination=page geeft technische toegang per pagina met page (standaard 1) en pageSize (standaard 10, maximaal 25).

update_seo_opportunity_statusSchrijven · mcp:actions:write

Werkt de status van een of meer SEO-kansen bij (tot 50 per aanroep) en geeft per kans een resultaat: toegepast, al in die status of geweigerd met de reden. Vereist de scope mcp:actions:write.

Parameters: projectId, status; opportunityId voor één kans, of opportunityIds (1 tot 50) voor een batch.

get_gsc_digest

Geef de laatste voltooide GSC-digest en de status van de laatste poging terug; genereert geen nieuwe digest.

Parameters: projectId; kind (dashboard_digest | weekly_gsc | monthly_gsc, standaard dashboard_digest).

get_gsc_snapshot

Leest alleen bewaarde Google Search Console-snapshots; roept GSC nooit live aan.

Parameters: projectId, dimension (date | page | query | query_page | page_date); optioneel: period, compareTo (zelfde duur), pageUrl, offset, limit (max. 50).

list_articles

Toon artikelen met scores, kwaliteitsstatus en publicatiemetadata, zonder de volledige inhoud.

Parameters: projectId; optioneel: status, search, limit (max. 25).

get_article

Geef één volledig artikel terug: inhoud, meta, kwaliteitsrapporten, publicatielogs, gekoppelde zoekwoorden, kansen en agent-runs.

Parameters: projectId, articleId.

get_article_generation_readiness

Controleer quota, volledigheid van de briefing, kannibalisatie en SERP-waarschuwingen vóór het genereren, zonder iets aan te maken.

Parameters: projectId, keyword, intent, articleType; optioneel: niche, languageCode.

generate_articleSchrijven · mcp:articles:generate

Start de normale workflow voor artikelgeneratie met quota en veiligheidscontroles. Vereist mcp:articles:generate.

Parameters: projectId, keyword, intent, idempotencyKey (UUID); optioneel: articleType, niche, languageCode, brief, opportunityId, acknowledgeWarnings.

get_workflow_status

Lees de voortgang van een artikelgeneratie of CMS-publicatie.

Parameters: projectId en precies één van requestId of articleId; optioneel: publicationJobId.

get_article_publication_readiness

Controleer inhoud, kwaliteit, CMS-koppeling, mogelijkheden en herkomst van het artikel vóór publicatie.

Parameters: projectId, articleId.

publish_article_to_cmsSchrijven · mcp:articles:publish

Publiceer of werk het artikel daadwerkelijk bij in het gekoppelde CMS. Vereist mcp:articles:publish.

Parameters: projectId, articleId, idempotencyKey (UUID), confirmed=true; optioneel: acknowledgeQualityOverride.

list_content_plan

Geef het huidige redactieplan en de status van elk gepland onderwerp terug.

Parameters: projectId.

generate_article_from_plan_itemSchrijven · mcp:articles:generate

Start na bevestiging de normale generatieworkflow vanuit een planitem. Vereist mcp:articles:generate.

Parameters: projectId, itemId, confirmed=true; optioneel: acknowledgeWarnings.

edit_articleSchrijven · mcp:articles:write

Bekijk en pas daarna artikelwijzigingen toe met optimistische versiecontroles. Toepassen vereist mcp:articles:write.

Parameters: projectId, articleId, mode, expectedUpdatedAt, changes (title, slug, content, metaDescription, faqData, ctaData, robotsConfig{index, follow, noSnippet, noArchive}, featuredImageAlt); confirmed=true om toe te passen. Een ctaData met html "" of blocks [] blijft zonder CTA, ook met een URL; een CTA zonder geldige URL wordt niet weergegeven.

get_article_performance

Lees de bewaarde GSC-prestaties van de gepubliceerde pagina zonder Google live aan te roepen.

Parameters: projectId, articleId.

add_keywordsSchrijven · mcp:keywords:write

Bekijk en voeg daarna tot 100 zoekwoorden toe aan de strategie. Nieuwe zoekwoorden worden verrijkt (volume, moeilijkheid, SERP, intentie) zoals bij toevoegen via het dashboard, zonder tegoedkosten, met een actief abonnement. Een eerder verwijderd zoekwoord wordt teruggezet. Toepassen vereist mcp:keywords:write.

Parameters: projectId, mode, terms[], locale, intent; confirmed=true en idempotencyKey om toe te passen.

update_keywordSchrijven · mcp:keywords:write

Bekijk en overschrijf daarna de intentie, status of prioriteitsscore van één zoekwoord. Toepassen vereist mcp:keywords:write.

Parameters: projectId, mode, keywordId, changes (intent, status, priorityScore); confirmed=true en idempotencyKey om toe te passen.

set_keyword_statusesSchrijven · mcp:keywords:write

Bekijk en stel daarna één status in voor tot 100 zoekwoorden. Toepassen vereist mcp:keywords:write.

Parameters: projectId, mode, keywordIds[], status; confirmed=true en idempotencyKey om toe te passen.

get_page_reanalysis_readiness

Controleer de URL, bekende pagina, dubbel werk en tegoed voordat de analyse opnieuw wordt uitgevoerd.

Parameters: projectId, pageUrl.

reanalyze_pageSchrijven · mcp:analysis:run

Voer de normale SEO-analyse van één pagina opnieuw uit, met tegoedverbruik. Vereist mcp:analysis:run.

Parameters: projectId, pageUrl, idempotencyKey, confirmed=true.

get_editorial_context

Lees gestructureerde redactionele context zonder interne RAG-documenten vrij te geven.

Parameters: projectId.

edit_editorial_contextSchrijven · mcp:editorial:write

Bekijk en pas daarna gestructureerde redactionele context toe met versiecontroles. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedUpdatedAt, changes (brandName, primaryOffer, audience, benefits, positioning, tone, proofs[]{claim, sourceUrl, excerpt}); confirmed=true om toe te passen.

get_business_profile

Lees het volledige bedrijfsprofiel: elk feit met status, herkomst en beslissing, gereedheid, ontbrekende kernvelden en legacymodus.

Parameters: projectId.

declare_business_factSchrijven · mcp:editorial:write

Bekijk en declareer daarna één feit in het bedrijfsprofiel (aanbod, doelgroep, markt, doelstelling, regel, beperking, seizoensgebondenheid of term). Bij een ingevuld adres wordt de waarde vervangen. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, address, value; confirmed=true om toe te passen.

replace_business_factSchrijven · mcp:editorial:write

Bekijk en overschrijf daarna de waarde van één bedrijfsfeit. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, value; confirmed=true om toe te passen.

confirm_business_factSchrijven · mcp:editorial:write

Bekijk en bevestig daarna één voorgesteld bedrijfsfeit. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true om toe te passen.

reject_business_factSchrijven · mcp:editorial:write

Bekijk een voorstel of bevestigd bedrijfsfeit en wijs het daarna af; u kunt het later herstellen. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true om toe te passen.

withdraw_business_factSchrijven · mcp:editorial:write

Bekijk een bedrijfsfeit en verwijder het daarna definitief; het kan niet worden hersteld. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId, reason; confirmed=true om toe te passen.

restore_business_factSchrijven · mcp:editorial:write

Bekijk een afgewezen bedrijfsfeit en zet het daarna terug naar voorgesteld. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, factId; confirmed=true om toe te passen.

reorder_business_offersSchrijven · mcp:editorial:write

Bekijk en vervang daarna de volgorde van de aanbiedingen. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, offerIds[]; confirmed=true om toe te passen.

adopt_business_profileSchrijven · mcp:editorial:write

Alleen in legacymodus: bekijk en bevestig daarna het profiel dat uit bestaande gegevens is hersteld, waarbij u in dezelfde wijziging onjuiste feiten afwijst en ontbrekende kernvelden opgeeft. Kan niet ongedaan worden gemaakt. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode, expectedRevision, idempotencyKey, rejectFactIds[], missingFacts[]{address, value}; confirmed=true om toe te passen.

retry_project_contextSchrijven · mcp:editorial:write

Start de herbouw van de projectcontext opnieuw na een mislukking (projectContext.retry = available in get_article_generation_readiness), net als de knop in de instellingen. Bekijk de status en zet de herbouw daarna opnieuw in de wachtrij; een herhaalde aanroep geeft de al geplande herbouw terug; na een nieuwe mislukking is elke toepassing een nieuwe poging. Toepassen vereist mcp:editorial:write.

Parameters: projectId, mode; confirmed=true om toe te passen.

get_cms_config

Lees het CMS-type, de verbindingsstatus, de datum van de laatste test en de niet-geheime instellingen. Geheimen worden nooit teruggegeven, alleen of ze zijn opgeslagen.

Parameters: projectId.

configure_cmsSchrijven · mcp:integrations:write

Bekijk en sla daarna de niet-geheime instellingen van een bestaande WordPress-, Webflow-, Wix-, Framer- (indien ingeschakeld) of aangepaste webhookverbinding op en test ze. Inloggegevens voert u alleen in het PushRank-dashboard in en blijven ongewijzigd. Shopify blijft in het dashboard. Toepassen vereist mcp:integrations:write en de rol eigenaar.

Parameters: projectId, mode, cmsType; per type: wpUrl, wpUsername | webflowCollectionId | wixSiteId, wixMemberId | framerProjectId, framerCollectionId, framerFieldMapping (Framer, indien ingeschakeld) | webhookUrl; confirmed=true en idempotencyKey om toe te passen.

get_publishing_schedule

Lees de artikelplanning van de kaart Onderwerpen: aan/uit, dagen, uur, tijdzone en Publiceren zonder controle, het volgende geplande artikel en wat het artikelquotum toestaat tot het wordt vernieuwd.

Parameters: projectId.

update_publishing_scheduleSchrijven · mcp:articles:generate, mcp:articles:publish

Bekijk en pas daarna een wijziging in de artikelplanning toe, met dezelfde regels als de kaart Onderwerpen. Toepassen vereist mcp:articles:generate om aan/uit, dagen, uur of tijdzone te wijzigen, en mcp:articles:publish om Publiceren zonder controle te wijzigen.

Parameters: projectId, mode; optioneel enabled, publishDays (0 tot 7 dagen uit mon…sun), publishHour (0–23), timezone (Europe/Paris, Europe/London, America/New_York, America/Los_Angeles, Asia/Tokyo), autoPublish; confirmed=true en idempotencyKey om toe te passen.

update_article_statusSchrijven · mcp:actions:write

Schrijf de opgeslagen publicatiestatus van een artikel terug en leg de MCP-herkomst vast. Vereist de scope mcp:actions:write.

Parameters: projectId, articleId, status (draft | published); optioneel: cmsUrl (alleen HTTPS), publishedAt (ISO 8601, alleen bij published; standaard nu). Inplannen wordt niet ondersteund, omdat deze tool geen planningstijdstempel heeft.

schedule_article_publicationSchrijven · mcp:actions:write

Plan een toekomstige artikelpublicatie in met de bestaande kwaliteitscontrole en bescherming tegen gelijktijdigheid. Vereist de scope mcp:actions:write.

Parameters: projectId, articleId, scheduledAt (toekomstige ISO 8601-tijdstempel met expliciete offset).

cancel_article_publication_scheduleSchrijven · mcp:actions:write

Annuleer een openstaande publicatieplanning van een artikel. Wordt geweigerd zodra de publicatieworker deze heeft opgepakt. Vereist de scope mcp:actions:write.

Parameters: projectId, articleId.

list_keywords

Toon verrijkte zoekwoorden met statistieken, status, prioriteit, artikeldekking en canonieke intentie.

Parameters: projectId; optioneel: intent, source, status, search, limit (max. 25), offset (pagineren met pagination.nextOffset).

get_keyword_metrics

Geef al opgeslagen statistieken terug voor maximaal 20 termen; roept nooit een provider aan en start geen vernieuwing.

Parameters: projectId, terms (1–20); optioneel: locale (standaard fr), locationCode (standaard 2250).

get_onboarding_checklist

Toon de vijf startstappen van een project, wat er nog te doen is, de dashboardlink voor elke stap en de status van de welkomstbacklink. Clients die MCP Apps ondersteunen, tonen dit als interactieve checklist.

Parameters: projectId.

claim_welcome_giftSchrijven · mcp:backlinks:write

Bekijk en claim daarna de backlink die u krijgt zodra de vijf stappen zijn voltooid: een pagina van de projectsite en de ankertekst. Alleen voor de eigenaar, met een proefperiode of actief abonnement; één per organisatie. Tijdens de proefperiode wordt de backlink alleen gereserveerd: hij wordt besteld wanneer de proefperiode eindigt, met de eerste betaalde maand. Toepassen vereist mcp:backlinks:write.

Parameters: projectId, mode, targetUrl, anchorText; confirmed=true om toe te passen.

get_ai_visibility

Leest de AI-zichtbaarheid van een project: gevolgde prompts, score, resultaten per prompt en per AI-engine (geciteerd, genoemd, positie, fragment), meetperiodes en optioneel de vergelijking met concurrenten. Geeft nooit de volledige antwoordtekst terug en start geen meting.

Parameters: projectId; optioneel: collectionId, prompt, provider, offset, limit (1–25, standaard 15), includeCompetitors.

manage_ai_visibility_promptsSchrijven · mcp:ai-visibility:write

Toont eerst een voorbeeld en past daarna het toevoegen, verwijderen of herformuleren van gevolgde prompts toe. Een geherformuleerde prompt begint zonder historie. Start geen meting: nieuwe prompts worden bij de volgende meting gemeten. Toepassen vereist mcp:ai-visibility:write.

Parameters: projectId, mode, operation (add met prompts, remove met prompts, of rename met from en to); confirmed=true om toe te passen.

OAuth-verbinding

MCP-clients zoals Claude of ChatGPT verbinden via OAuth: geef ze het endpoint en ze vinden de rest in de metadata hieronder.

Resource-metadatahttps://ai.pushrank.io/.well-known/oauth-protected-resource/mcp
Autorisatieserverhttps://app.pushrank.io/.well-known/oauth-authorization-server
  1. Detectie — een niet-geauthenticeerde aanroep van het endpoint geeft 401 met een WWW-Authenticate-header die naar de resource-metadata verwijst; die noemen de autorisatieserver en de ondersteunde scopes.
  2. Registratie — de client registreert zich via dynamische clientregistratie (registration_endpoint) als publieke client, zonder secret.
  3. Autorisatie — authorization-code-flow met PKCE (S256) en de parameter resource gelijk aan het MCP-endpoint; de gebruiker logt in bij Pushrank en keurt de gevraagde scopes goed.
  4. Tokens — het token_endpoint geeft een toegangstoken van 1 uur en, als offline_access wordt gevraagd, een vernieuwingstoken van 30 dagen. Stuur het toegangstoken mee als Authorization: Bearer.

Handmatig API-gebruik

Voor een script of een client zonder OAuth roept u het JSON-RPC 2.0-endpoint aan met een bearer-token dat u aanmaakt via het tabblad "API / handmatig".

Endpointhttps://ai.pushrank.io/mcp

Vereiste headers

  • Authorization: Bearer <token> — verplicht bij elk verzoek.
  • Content-Type: application/json.
  • Accept: application/json, text/event-stream.
  • mcp-session-id — teruggegeven in de responseheaders van initialize; herhaal deze bij elke volgende aanroep.
  • mcp-protocol-version: 2025-06-18 bij de aanroepen na initialize.

Volgorde van aanroepen

1. initialize — opent een sessie. Lees de responseheader mcp-session-id (curl -i).

terminal
curl -i -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"pushrank-manual-client","version":"1.0"}}}'

2. tools/list — toont de beschikbare tools en hun invoerschema's.

terminal
curl -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id>" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. tools/call — voert een tool uit met de bijbehorende argumenten.

terminal
curl -X POST "https://ai.pushrank.io/mcp" \
  -H "Authorization: Bearer pushrank_mcp_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id>" \
  -H "mcp-protocol-version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{"limit":10}}}'
De server is stateful: zonder geldige mcp-session-id-header geeft elke aanroep na initialize "Session not found" (404) terug.

Scopes, limieten en intrekking

MCP-tokens zijn speciaal bedoeld hiervoor en staan los van uw sessie.

Handmatig token

Een handmatig token heeft standaard de scopes mcp:projects:read en mcp:actions:read. Het verloopt nooit en kan op elk moment worden ingetrokken.

Schrijfacties

Status- en planningsupdates vereisen mcp:actions:write. Genereren gebruikt mcp:articles:generate, publiceren mcp:articles:publish, artikelen bewerken mcp:articles:write, zoekwoordwijzigingen mcp:keywords:write, heranalyse mcp:analysis:run, redactionele context mcp:editorial:write, wijzigingen in de CMS-verbinding mcp:integrations:write, het claimen van de welkomstbacklink mcp:backlinks:write en de gevolgde prompts van AI-zichtbaarheid mcp:ai-visibility:write. Wijzigingen in de artikelplanning gebruiken mcp:articles:generate, en Publiceren zonder controle mcp:articles:publish. Deze specifieke scopes worden via OAuth toegekend of aangevinkt bij een handmatige sleutel, bij het aanmaken of later. Een token zonder de vereiste scope krijgt insufficientScope.

OAuth-geldigheidsduur

Voor OAuth-clients (Claude, ChatGPT…) is het toegangstoken 1 u geldig en het vernieuwingstoken 30 dagen.

Intrekking

Trek een handmatig token in via het tabblad "API / handmatig". Intrekking gaat direct in en heeft geen invloed op uw sessie; OAuth-toegang trekt u in vanuit de verbonden client.

Organisatiebereik

De server beperkt elk antwoord tot de projecten van de organisaties waarvan u lid bent.