Primeiros passos

API do Gemlead

Leve os leads quentes que o Gemlead encontra no X para as suas próprias ferramentas. Uma API REST, webhooks assinados e um servidor MCP para assistentes de IA, tudo com uma só chave.

Antes de começar

A API e o servidor MCP estão incluídos nos planos Business e Enterprise, também durante o teste grátis. Todos os endpoints ficam em https://gemlead.ai/api/v1, recebem e retornam JSON com campos em snake_case e usam ISO 8601, em UTC, para todas as datas e horas.

URL base

https://gemlead.ai/api/v1

Gerar uma chave de API

No Gemlead, abra API no menu. Escolha a conta do X que vai usar a chave, dê um nome a ela e defina os scopes, só read ou read e write.

A chave começa com gl_live_ e aparece uma única vez, então salve-a na hora no seu gerenciador de segredos ou no seu ambiente. Uma chave pertence a uma conta do X e só vê os dados dela.

Terminal

export GEMLEAD_API_KEY="gl_live_..."

Fazer sua primeira requisição

Teste a chave com Obter a conta. Toda requisição envia a chave no cabeçalho Authorization, como bearer token.

A resposta traz a conta do X à qual a chave pertence e o plano dela.

GET/v1/account

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

Resposta200

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

Listar seus leads quentes

Um lead é quente quando a Dana AI dá a ele score 60 ou mais. Peça os mais recentes com hot=true e adicione persona, score_min ou uma data para refinar a lista.

As listas vêm uma página por vez. Siga next_cursor enquanto has_more for true, como mostra Paginação.

GET/v1/leads

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

Resposta200

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

Receber seu primeiro webhook

Os webhooks enviam os eventos ao seu servidor no momento em que acontecem, então você nunca precisa fazer polling. Cadastre uma URL HTTPS pública para lead.hot e reply.received, guarde o secret da resposta e envie um evento de teste para você mesmo. lead.created envia cada novo lead, quente ou não.

Verifique cada requisição pelo cabeçalho Gemlead-Signature, como mostra Verificar assinaturas. Você também pode adicionar o endpoint no app, em 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"

Conectar um assistente de IA

O servidor MCP do Gemlead em https://gemlead.ai/mcp permite que Claude, ChatGPT e Cursor busquem seus leads, leiam suas conversas e rodem suas campanhas, direto no chat.

No Claude Code, basta um comando para conectar o servidor com a sua chave. Para os outros, siga o setup do MCP.

Claude Code

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

Próximos passos

AutenticaçãoChaves, scopes e como mantê-las seguras.LeadsTodos os filtros da lista de leads e o objeto lead.WebhooksEventos, payloads, assinaturas e novas tentativas.Servidor MCPConfigure Claude, ChatGPT, Cursor e Claude Code.