API e server MCP di GetLinkFast

A cosa serve

• Agenzie e team SEO: collega i tuoi strumenti interni e le tue dashboard di monitoraggio al tuo account. Catalogo, carrello, ordini e stati si leggono in JSON.
• Agenti IA: chiedi a Claude Code o Cursor «trovami 5 siti di finanza con DR 40+ e ordina». L'agente cerca, ti mostra il riepilogo e ordina solo dopo il tuo consenso.
• Make, n8n, Zapier: bastano un modulo HTTP e una chiave.

L'API vende l'articolo ospite (guest_post), l'inserimento di link (link_insertion) e i pacchetti SEO/GEO, solo in crediti. L'acquisto di crediti e le altre offerte restano nella dashboard.

Creare una chiave

1. Apri Dashboard → Accesso API.
2. Dai un nome alla chiave (ad esempio «Agente Claude» o «Report Make») e scegli i suoi permessi. Su una chiave che può ordinare, puoi fissare un tetto per ordine e un tetto sulle 24 ore.
3. Copia la chiave. Inizia con glf_live_ e viene mostrata una sola volta: ne conserviamo solo un'impronta.
4. Inviala nell'intestazione di ogni richiesta: Authorization: Bearer glf_live_…

Al massimo 10 chiavi attive per organizzazione. Una chiave revocata smette subito di funzionare, così come le chiavi di un membro che lascia l'organizzazione. Tieni la chiave fuori dai tuoi repository di codice: chi la possiede agisce a nome della tua organizzazione.

I permessi di una chiave

Ogni chiave porta uno o più permessi. Una richiesta senza il permesso necessario riceve 403 insufficient_scope, e un agente IA vede solo gli strumenti consentiti.

Avvio rapido

Tutte le rotte iniziano con https://www.getlinkfast.com/api/v1. Mantieni il www: l'indirizzo senza www reindirizza, e un client HTTP non invia più l'intestazione Authorization dopo un reindirizzamento.

Gli importi sono in euro IVA esclusa. Le risposte sono in JSON, i campi in snake_case.

curl https://www.getlinkfast.com/api/v1/account \
  -H "Authorization: Bearer glf_live_…"

curl "https://www.getlinkfast.com/api/v1/sites?dr_min=40&language=fr&product=guest_post&sort=dr&dir=desc&page_size=10" \
  -H "Authorization: Bearer glf_live_…"

curl -X POST https://www.getlinkfast.com/api/v1/cart/items \
  -H "Authorization: Bearer glf_live_…" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"8a1f0c3e-5b7d-4e2a-9c61-0f3b2d4e6a17","product_type":"guest_post","target_url":"https://www.example.com/invoicing","anchor":"invoicing software","topic":"How to choose invoicing software for a small business"}'

Sostituisci site_id con l'id di un sito del passo 2. Non inviare mai un prezzo: lo calcola il server.

curl -X POST https://www.getlinkfast.com/api/v1/checkout \
  -H "Authorization: Bearer glf_live_…" \
  -H "Idempotency-Key: order-2026-10-14-001"

La risposta indica l'id dell'ordine, l'importo addebitato e il saldo residuo. Poi seguine l'avanzamento con GET /orders/{id}.

Ordinare in crediti

L'API ordina solo in crediti e non avvia mai un pagamento con carta. I crediti si ricaricano nella dashboard.

Un ordine prende le righe guest_post e link_insertion del carrello. Le altre righe, aggiunte dalla dashboard, restano nel carrello e sono elencate in skipped_items.

Nessun tetto predefinito: il tuo saldo è l'unico limite. Su una chiave che può ordinare, fissa un tetto per ordine e un tetto sulle 24 ore mobili. Un ordine che li supera viene rifiutato (403 spending_limit_exceeded, con il residuo disponibile), senza addebito.

Saldo insufficiente: 402 insufficient_credits, con l'importo mancante e il link alla pagina Crediti, da inoltrare a una persona del tuo team. Nulla viene addebitato.

Poi tutto funziona come dalla dashboard: email di conferma e monitoraggio nella schermata Ordini, dove l'ordine porta il nome della chiave che lo ha effettuato.

L'intestazione Idempotency-Key

• Obbligatoria su POST /checkout e POST /packs/orders: da 8 a 128 caratteri ASCII stampabili, senza spazi. Senza: 400 idempotency_key_required.
• Un valore equivale a un'intenzione d'acquisto. Reinviare lo stesso valore restituisce l'ordine originale (200, "replayed": true) senza secondo addebito, anche se nel frattempo il carrello è cambiato.
• Dopo un timeout o un'interruzione di rete, riprova con lo stesso valore: non pagherai due volte.
• Per un nuovo acquisto, genera un nuovo valore, ad esempio un UUID.
• Su POST /checkout come su POST /packs/orders, un valore già usato per un altro acquisto viene rifiutato: 409 idempotency_conflict, senza addebito. Per un pacchetto, viene rifiutato anche lo stesso valore inviato con un contenuto diverso.
• Lato MCP, il token di conferma svolge questo ruolo: non devi generare nulla.

Limiti

• 120 richieste al minuto per chiave per la lettura, e altrettante, separatamente, per il carrello: l'una non intacca l'altra.
• 10 chiamate al minuto per chiave verso le rotte o gli strumenti d'acquisto — ripetizioni, rifiuti e passo di riepilogo MCP compresi.
• 300 richieste HTTP al minuto per chiave sul server MCP. Ogni strumento chiamato conta in più nel limite del suo permesso.
• Oltre: 429 rate_limited. L'attesa, in secondi, è indicata dall'intestazione Retry-After in HTTP, e da details.retry_after_seconds nel risultato di uno strumento MCP.
• Al massimo 100 risultati per pagina (page_size).
• Corpo della richiesta: al massimo 1 MB.

Codici di errore

Ogni errore ha la stessa forma. Verifica code: è stabile. message è in inglese e si rivolge allo sviluppatore; details indica il campo errato o gli importi.

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this order. Nothing was debited. Ask a human to top up at credits_url, then retry with the same Idempotency-Key.",
    "details": {
      "missing_amount": 42,
      "credits_url": "https://www.getlinkfast.com/dashboard/credits"
    }
  }
}

Server MCP

Il server MCP dà al tuo agente IA le stesse funzioni dell'API, con la stessa chiave. Il suo indirizzo: https://www.getlinkfast.com/api/mcp.

Claude Code

Un comando nel tuo terminale:

claude mcp add --transport http getlinkfast https://www.getlinkfast.com/api/mcp --header "Authorization: Bearer glf_live_…"

Cursor

In ~/.cursor/mcp.json. Evita il file .cursor/mcp.json di un progetto: spesso finisce nel repository, insieme alla chiave.

{
  "mcpServers": {
    "getlinkfast": {
      "url": "https://www.getlinkfast.com/api/mcp",
      "headers": {
        "Authorization": "Bearer glf_live_…"
      }
    }
  }
}

Claude Desktop

Claude Desktop non invia intestazioni personalizzate a un server remoto: non può quindi trasmettere la tua chiave. Si collegherà in modo nativo con la connessione OAuth, prevista in una prossima versione. Oggi usa Claude Code o Cursor: inviano la chiave nell'intestazione Authorization.

Gli strumenti

L'agente vede solo gli strumenti consentiti dai permessi della chiave: una chiave senza il permesso di ordinare non ha alcuno strumento d'acquisto.

read

search_sitesget_sitelist_site_pageslist_categoriesget_accountlist_ordersget_orderget_auditquote_packlist_auditsget_plan

cart

get_cartadd_to_cartupdate_cart_itemremove_cart_itemadd_audit_pagerun_auditcancel_planned_link

purchase

checkoutorder_packplan_links

L'acquisto in due tempi

1. L'agente chiama checkout o order_pack senza confirmation_token: nulla viene addebitato. Riceve il riepilogo (righe, totale, saldo dopo l'addebito, tetto residuo) e un confirmation_token.
2. Ti mostra questo riepilogo. Se accetti, richiama lo strumento con il confirmation_token: l'ordine viene effettuato e addebitato.
3. Il token vale 10 minuti. Se nel frattempo cambiano il carrello, un prezzo o la chiave, viene rifiutato (confirmation_expired) e l'agente ripete il passo 1. Richiamare con lo stesso token dopo un'interruzione restituisce lo stesso ordine, senza secondo addebito.

Client scritto a mano

Il server è senza sessione: ogni messaggio JSON-RPC parte in POST e la risposta arriva in JSON. Invia Accept: application/json, text/event-stream e Content-Type: application/json, altrimenti il server risponde 406. GET e DELETE rispondono 405.

curl -X POST https://www.getlinkfast.com/api/mcp \
  -H "Authorization: Bearer glf_live_…" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Auditare e pianificare

Un agente può fare l'audit di un sito e distribuire link su più mesi a partire dal rapporto. Quattro passaggi, con gli strumenti del server MCP.

1. run_audit avvia l'audit completo di un dominio: controlli tecnici, visibilità su ChatGPT e siti dove un link aiuterebbe. Servono alcuni minuti. Non viene addebitato nulla, e il rapporto si sblocca con la quota di audit dell'organizzazione, se ne ha una. Limite: 10 audit per chiave ogni 24 ore; chiedendo di nuovo lo stesso dominio entro un'ora si ottiene l'audit esistente.
2. get_audit restituisce lo stato e il passaggio in corso, poi il rapporto in summary quando lo stato diventa ready. Richiamalo ogni 30-60 secondi. list_audits elenca gli audit dell'organizzazione, dal più recente.
3. plan_links prepara un calendario da un audit pronto: un budget mensile in euro IVA esclusa (almeno 100 €), da 2 a 12 mesi e, in opzione, una data di inizio e le pagine di destinazione. Come per un acquisto, sono due passaggi. Senza token non si salva nulla: l'agente riceve il calendario (link, date di invio, totale) e un confirmation_token valido 10 minuti. Dopo il tuo consenso richiama lo strumento con gli stessi campi e il token, e il piano viene salvato.
4. get_plan segue ogni link: pagina di destinazione, ancora, prezzo e stato (programmato, ordinato, pubblicato, annullato o non riuscito, con la causa dell'errore, per esempio insufficient_credits). cancel_planned_link annulla un link pianificato tramite l'API, o tutti quelli di un dominio non ancora ordinati. I link programmati dal nostro team restano al loro posto: team_planned per un link, skipped_team_planned per il loro numero.

Al salvataggio del piano non viene addebitato nulla. Ogni link viene addebitato in crediti il giorno del suo invio, al prezzo riletto quel giorno, nel passaggio quotidiano del mattino (verso le 06:20 UTC). Se quel giorno il saldo non basta, il link non viene ordinato e compare come non riuscito in get_plan. Un link già ordinato non si può più annullare.

Permessi: run_audit e cancel_planned_link richiedono cart, plan_links richiede purchase, e get_audit, list_audits e get_plan richiedono read. I tetti di spesa della chiave valgono anche per i link pianificati.

Nella dashboard, la pagina Delega mostra questi link nel blocco «Link programmati». Il proprietario dell'organizzazione può rimuovere lì i link pianificati tramite l'API. Quelli pianificati dal nostro team sono in sola lettura.

Riferimento

Ogni rotta con il suo permesso e lo strumento MCP corrispondente. Parametri, schemi di risposta ed errori rotta per rotta: la descrizione OpenAPI 3.1.

Una domanda sull'API? Scrivici, una persona del team ti risponde.