Primeros pasos

API de Gemlead

Lleva a tus herramientas los leads calientes que Gemlead encuentra en X. Una API REST, webhooks firmados y un servidor MCP para asistentes de IA, todo con una sola clave.

Antes de empezar

La API y el servidor MCP vienen con los planes Business y Enterprise, prueba incluida. Todos los endpoints están bajo https://gemlead.ai/api/v1, reciben y devuelven JSON con campos en snake_case y escriben todas las fechas y horas en ISO 8601, en UTC.

URL base

https://gemlead.ai/api/v1

Consigue una clave API

En Gemlead, abre API en el menú. Elige la cuenta de X a la que irá la clave, ponle un nombre y elige sus scopes, solo read o read y write.

La clave empieza por gl_live_ y solo se muestra una vez, así que guárdala enseguida en tu gestor de secretos o en tu entorno. Una clave pertenece a una sola cuenta de X y solo ve sus datos.

Terminal

export GEMLEAD_API_KEY="gl_live_..."

Haz tu primera solicitud

Comprueba la clave con Obtener la cuenta. Cada solicitud envía la clave en el encabezado Authorization, como bearer token.

La respuesta es la cuenta de X a la que pertenece la clave, con su plan.

GET/v1/account

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

Respuesta200

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

Lista tus leads calientes

Un lead está caliente cuando Dana AI le da una puntuación de 60 o más. Pide los últimos con hot=true y añade persona, score_min o una fecha para acotar la lista.

Las listas llegan página a página. Sigue next_cursor mientras has_more sea true, como muestra Paginación.

GET/v1/leads

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

Respuesta200

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

Recibe tu primer webhook

Los webhooks envían los eventos a tu servidor en cuanto ocurren, sin que tengas que hacer polling. Registra una URL HTTPS pública para lead.hot y reply.received, guarda el secret de la respuesta y envíate un evento de prueba. lead.created envía cada lead nuevo, caliente o no.

Comprueba cada solicitud con su encabezado Gemlead-Signature, como muestra Verificar firmas. También puedes añadir el endpoint en la app, en 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"

Conecta un asistente de IA

Con el servidor MCP de Gemlead en https://gemlead.ai/mcp, Claude, ChatGPT y Cursor buscan tus leads, leen tus conversaciones y gestionan tus campañas desde el propio chat.

En Claude Code, basta un comando para conectarlo con tu clave. Para los demás, sigue Configuración del MCP.

Claude Code

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

Siguientes pasos

AutenticaciónClaves, scopes y cómo protegerlas.LeadsTodos los filtros de la lista de leads y el objeto lead.WebhooksEventos, payloads, firmas y reintentos.Servidor MCPConfigura Claude, ChatGPT, Cursor y Claude Code.