Primeiros passos

Autenticação

Toda requisição leva a chave secreta da conta do X em que ela atua. Você cria as chaves no app, pode limitá-las à leitura, e elas param de funcionar assim que você as revoga.

Chaves de API

Uma chave é gl_live_ seguido de 32 letras e dígitos. O app mostra os 12 primeiros caracteres, como gl_live_AbCd, para você distinguir suas chaves.
Cada chave pertence a uma conta do X no Gemlead e só vê os leads, as personas, as campanhas e as conversas dessa conta.
A chave completa aparece uma única vez, quando você a cria. O Gemlead guarda só um hash dela, então uma chave perdida não pode ser mostrada de novo. Crie uma nova.
Uma conta pode ter 20 chaves ativas.

A API está incluída nos planos Business e Enterprise, também durante o teste grátis. Quando o dono da conta está no plano Free ou Starter, as requisições retornam 403 com o código plan_required. As chaves continuam lá e voltam a funcionar quando a conta passa para Business ou Enterprise.

Enviar a chave

Envie a chave como bearer token no cabeçalho Authorization. O cabeçalho X-Api-Key também funciona, para as ferramentas que não conseguem definir um bearer token.

Uma requisição sem chave retorna 401 com o código api_key_missing, uma chave errada retorna api_key_invalid e uma revogada, api_key_revoked.

Terminal

# As a bearer token
curl https://gemlead.ai/api/v1/account \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

# Or in X-Api-Key, for tools that cannot set a bearer token
curl https://gemlead.ai/api/v1/account \
  -H "X-Api-Key: $GEMLEAD_API_KEY"

Scopes

Uma chave tem o scope read, ou read e write. Dê write só às ferramentas que alteram dados.

Scope	Permite
`read`	Todo `GET`, e `POST /v1/exports`, já que uma exportação só lê.
`write`	Toda requisição que altera dados, `POST`, `PATCH`, `PUT` e `DELETE`.

Uma chave read que tenta alterar dados recebe 403 com o código insufficient_scope.

Obter a conta

GET/v1/accountScope readMCPget_account

Retorna a conta do X à qual a chave pertence. Uma boa primeira chamada para testar uma chave.

Retorno

O objeto account, com o plan em business ou enterprise.

Erros

401api_key_invalid
A chave está errada.
403plan_required
O dono da conta está no plano Free ou Starter.

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

Proteger as chaves

Chame a API apenas do seu servidor, nunca de um navegador, de um app mobile ou do código de um repositório público.
Guarde as chaves num gerenciador de segredos ou numa variável de ambiente como GEMLEAD_API_KEY.
Dê a cada ferramenta a sua própria chave, para poder revogar uma sem mexer nas outras.
Para fazer a rotação de uma chave, crie a nova, faça o deploy dela e depois revogue a antiga no app.

Assistentes de IA

Claude e ChatGPT se conectam ao servidor MCP com OAuth. Você faz login no Gemlead e escolhe a conta do X, sem nenhuma chave para copiar. Cursor e Claude Code podem usar uma chave, enviada da mesma forma descrita acima.