Per iniziare

API Gemlead

Porta nei tuoi strumenti i lead caldi che Gemlead trova su X. Un'API REST, webhook firmati e un server MCP per gli assistenti IA, tutto con una sola chiave.

Prima di iniziare

L'API e il server MCP sono inclusi nei piani Business ed Enterprise, prova compresa. Ogni endpoint si trova sotto https://gemlead.ai/api/v1, riceve e restituisce JSON con campi in snake_case e scrive ogni data e ora in ISO 8601, in UTC.

URL di base

https://gemlead.ai/api/v1

Ottieni una chiave API

In Gemlead, apri API nel menu. Seleziona l'account X per cui è la chiave, dalle un nome e scegli i suoi scope, solo read oppure read e write.

La chiave inizia con gl_live_ e appare una sola volta, quindi salvala subito nel tuo secret manager o nel tuo ambiente. Una chiave appartiene a un solo account X e vede solo i suoi dati.

Terminale

export GEMLEAD_API_KEY="gl_live_..."

Fai la tua prima richiesta

Verifica la chiave con Recupera l'account. Ogni richiesta invia la chiave nell'header Authorization, come bearer token.

La risposta è l'account X a cui appartiene la chiave, con il suo piano.

GET/v1/account

curl https://gemlead.ai/api/v1/account \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Risposta200

{
  "object": "account",
  "id": "a9PzK2vRtM",
  "username": "acme",
  "name": "Acme",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg",
  "plan": "business"
}

Elenca i tuoi lead caldi

Un lead è caldo quando Dana AI gli dà un punteggio di 60 o più. Recupera i più recenti con hot=true e aggiungi persona, score_min o una data per restringere l'elenco.

Gli elenchi arrivano una pagina alla volta. Segui next_cursor finché has_more è true, come mostra Paginazione.

GET/v1/leads

curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=10

Risposta200

{
  "object": "list",
  "data": [
    {
      "id": "msgOtJ8dvT",
      "object": "lead",
      "profile": {
        "x_user_id": "1460283925",
        "username": "jane_builds",
        "name": "Jane Doe",
        "bio": "Runs a paid trading community. Daily setups, no hype.",
        "followers_count": 12400,
        "following_count": 380,
        "location": "Austin, TX",
        "website": "https://janedoe.com",
        "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
        "verified": true,
        "url": "https://x.com/jane_builds"
      },
      "score": 86,
      "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
      "hot": true,
      "status": "scored",
      "persona": {
        "id": "lvWBPnytpS",
        "name": "Tipsters"
      },
      "campaign": null,
      "conversation_id": null,
      "locked_to": null,
      "found_at": "2026-11-05T14:02:11.482Z",
      "scored_at": "2026-11-05T14:03:40.117Z",
      "updated_at": "2026-11-05T14:03:40.117Z",
      "metadata": {}
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0"
}

Ricevi il tuo primo webhook

I webhook inviano gli eventi al tuo server nel momento in cui accadono, così non devi mai fare polling. Registra un URL HTTPS pubblico per lead.hot e reply.received, conserva il secret della risposta, poi inviati un evento di test. lead.created invia ogni nuovo lead, caldo o no.

Verifica ogni richiesta con il suo header Gemlead-Signature, come mostra Verifica le firme. Puoi anche aggiungere l'endpoint nell'app, alla voce API.

POST/v1/webhook_endpoints

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot", "reply.received"],
    "description": "CRM sync",
    "filters": {
      "persona_ids": ["lvWBPnytpS"]
    }
  }'

POST/v1/webhook_endpoints/:id/test

curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Collega un assistente IA

Il server MCP di Gemlead su https://gemlead.ai/mcp permette a Claude, ChatGPT e Cursor di cercare i tuoi lead, leggere le tue conversazioni e gestire le tue campagne, direttamente nella chat.

In Claude Code basta un comando per collegarlo con la tua chiave. Per gli altri, segui il setup dell'MCP.

Claude Code

claude mcp add --transport http gemlead https://gemlead.ai/mcp \
  --header "Authorization: Bearer $GEMLEAD_API_KEY"

Prossimi passi

AutenticazioneChiavi, scope e come tenerle al sicuro.LeadTutti i filtri dell'elenco dei lead e l'oggetto lead.WebhookEventi, payload, firme e nuovi tentativi.Server MCPConfigura Claude, ChatGPT, Cursor e Claude Code.