Premiers pas

API Gemlead

Récupère dans tes propres outils les leads chauds que Gemlead trouve sur X. Une API REST, des webhooks signés et un serveur MCP pour les assistants IA, le tout avec une seule clé.

Avant de commencer

L'API et le serveur MCP sont inclus dans les plans Business et Enterprise, essai compris. Chaque endpoint se trouve sous https://gemlead.ai/api/v1, reçoit et renvoie du JSON aux champs en snake_case, et écrit toutes les dates et heures en ISO 8601, en UTC.

URL de base

https://gemlead.ai/api/v1

Obtenir une clé API

Dans Gemlead, ouvre API dans le menu. Sélectionne le compte X concerné, nomme la clé et choisis ses scopes, read seul ou read et write.

La clé commence par gl_live_ et ne s'affiche qu'une fois. Range-la tout de suite dans ton gestionnaire de secrets ou dans ton environnement. Une clé appartient à un seul compte X et ne voit que ses données.

Terminal

export GEMLEAD_API_KEY="gl_live_..."

Faire ta première requête

Vérifie la clé avec Récupérer le compte. Chaque requête envoie la clé dans le header Authorization, en bearer token.

La réponse contient le compte X de la clé et son plan.

GET/v1/account

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

Réponse200

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

Lister tes leads chauds

Un lead est chaud quand Dana AI lui donne un score de 60 ou plus. Demande les derniers avec hot=true, et ajoute persona, score_min ou une date pour affiner la liste.

Les listes arrivent page par page. Suis next_cursor tant que has_more vaut true, comme le montre Pagination.

GET/v1/leads

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

Réponse200

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

Recevoir ton premier webhook

Les webhooks envoient les événements à ton serveur dès qu'ils se produisent, sans que tu aies à interroger l'API. Enregistre une URL HTTPS publique pour lead.hot et reply.received, garde le secret de la réponse, puis envoie-toi un événement test. lead.created envoie chaque nouveau lead, chaud ou non.

Vérifie chaque requête avec son header Gemlead-Signature, comme le montre Vérifier les signatures. Tu peux aussi ajouter l'endpoint dans l'app, sur la page 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"

Connecter un assistant IA

Le serveur MCP de Gemlead, à l'adresse https://gemlead.ai/mcp, permet à Claude, ChatGPT et Cursor de chercher tes leads, de lire tes conversations et de piloter tes campagnes, directement dans le chat.

Dans Claude Code, une seule commande le connecte avec ta clé. Pour les autres, suis la configuration MCP.

Claude Code

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

Pour aller plus loin

AuthentificationLes clés, les scopes et comment les protéger.LeadsTous les filtres de la liste des leads, et l'objet lead.WebhooksÉvénements, payloads, signatures et nouvelles tentatives.Serveur MCPConfigure Claude, ChatGPT, Cursor et Claude Code.