Referência da API

Conta

A conta é a conta do X à qual a chave pertence. Leia a conta para testar uma chave, alterar as configurações, reiniciar a sincronização da inbox do X ou passar ao Gemlead o código do X Chat. O fuso horário, o idioma e o nome do dono valem para todas as contas do X dele.

Endpoints

GET/v1/account
POST/v1/account/refresh_profile
GET/v1/account/settings
PATCH/v1/account/settings
POST/v1/account/sync/restart
POST/v1/account/sync/pause
POST/v1/account/sync/resume
GET/v1/account/x_chat
PUT/v1/account/x_chat/passcode
DELETE/v1/account/x_chat/passcode

O objeto account

A conta do X à qual a chave pertence. Uma chave funciona em uma única conta do X, e um dono com várias contas do X tem uma chave para cada uma.

Atributos

objectstring
Sempre account.
idstring
Identificador único da conta.
usernamestring
O username no X, sem o @.
namestring
O nome de exibição no X.
profile_image_urlstring ou null
A URL da foto do perfil.
planstring
O plano do dono.
businessenterprise

O objeto account

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

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

Um objeto account.

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

Recarregar o perfil do X

POST/v1/account/refresh_profileScope writeMCPupdate_account_settings

Lê de novo o perfil da conta no X, para obter um novo nome ou uma nova foto.

Retorno

O objeto account.

Erros

409x_session_expired
A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.
502upstream_unavailable
O X ou um serviço do Gemlead não respondeu. Nada mudou, tente de novo em um minuto.

POST/v1/account/refresh_profile

curl -X POST \
  https://gemlead.ai/api/v1/account/refresh_profile \
  -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"
}

O objeto account settings

Como a conta sincroniza a inbox do X, se as DMs dela estão pausadas e o perfil do dono. O fuso horário, o idioma e o nome do dono valem para todas as contas do X dele.

Atributos

objectstring
Sempre account_settings.
account_idstring
O ID da conta.
syncobject
A sincronização da inbox do X com o Gemlead.
dms_paused_untilstring ou null
Enquanto o X limita a conta, quando as DMs dela voltam a funcionar, em ISO 8601.
ownerobject
O dono da conta.

O objeto account settings

{
  "object": "account_settings",
  "account_id": "a9PzK2vRtM",
  "sync": {
    "all_conversations": true,
    "status": "done",
    "conversations": 1342
  },
  "dms_paused_until": null,
  "owner": {
    "first_name": "Alex",
    "last_name": "Martin",
    "timezone": "Europe/Paris",
    "language": "en"
  }
}

Obter as configurações da conta

GET/v1/account/settingsScope readMCPget_account_settings

Retorna a sincronização da inbox, a pausa das DMs e o perfil do dono.

Retorno

Um objeto account settings.

GET/v1/account/settings

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

Resposta200

{
  "object": "account_settings",
  "account_id": "a9PzK2vRtM",
  "sync": {
    "all_conversations": true,
    "status": "done",
    "conversations": 1342
  },
  "dms_paused_until": null,
  "owner": {
    "first_name": "Alex",
    "last_name": "Martin",
    "timezone": "Europe/Paris",
    "language": "en"
  }
}

Atualizar as configurações da conta

PATCH/v1/account/settingsScope writeMCPupdate_account_settings

Altera as configurações que você envia e mantém as outras.

Parâmetros do corpo

sync_all_conversationsboolean
true sincroniza todas as conversas da inbox do X e percorre a inbox de novo agora. false mantém só as conversas com leads.
timezonestring
O fuso horário IANA do dono, como Europe/Paris. Os gráficos e as contagens diárias seguem esse fuso.
languagestring
O idioma do app do dono.
enfresitderuptnlja
first_namestring
O nome do dono, com até 60 caracteres.
last_namestring
O sobrenome do dono, com até 60 caracteres.

Retorno

O objeto account settings atualizado.

Erros

400parameter_invalid
Um parâmetro tem um valor que a API não aceita. param diz qual.
400parameter_unknown
O corpo tem um campo que este endpoint não aceita.
409x_session_expired
A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.

PATCH/v1/account/settings

curl -X PATCH https://gemlead.ai/api/v1/account/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "Europe/Paris"
  }'

Resposta200

{
  "object": "account_settings",
  "account_id": "a9PzK2vRtM",
  "sync": {
    "all_conversations": true,
    "status": "done",
    "conversations": 1342
  },
  "dms_paused_until": null,
  "owner": {
    "first_name": "Alex",
    "last_name": "Martin",
    "timezone": "Europe/Paris",
    "language": "en"
  }
}

Reiniciar a sincronização da inbox

POST/v1/account/sync/restartScope writeMCPupdate_account_settings

Percorre de novo a inbox do X desde o início, para recuperar conversas que o Gemlead deixou passar.

Retorno

O objeto account settings.

Erros

409x_session_expired
A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.

POST/v1/account/sync/restart

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

Resposta200

{
  "object": "account_settings",
  "account_id": "a9PzK2vRtM",
  "sync": {
    "all_conversations": true,
    "status": "syncing",
    "conversations": 1342
  },
  "dms_paused_until": null,
  "owner": {
    "first_name": "Alex",
    "last_name": "Martin",
    "timezone": "Europe/Paris",
    "language": "en"
  }
}

Pausar a sincronização da inbox

POST/v1/account/sync/pauseScope writeMCPupdate_account_settings

Pausa a sincronização da inbox do X.

Retorno

O objeto account settings.

Erros

409x_session_expired
A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.

POST/v1/account/sync/pause

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

Resposta200

{
  "object": "account_settings",
  "account_id": "a9PzK2vRtM",
  "sync": {
    "all_conversations": true,
    "status": "paused",
    "conversations": 1342
  },
  "dms_paused_until": null,
  "owner": {
    "first_name": "Alex",
    "last_name": "Martin",
    "timezone": "Europe/Paris",
    "language": "en"
  }
}

Retomar a sincronização da inbox

POST/v1/account/sync/resumeScope writeMCPupdate_account_settings

Retoma uma sincronização pausada da inbox do X.

Retorno

O objeto account settings.

Erros

409x_session_expired
A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.

POST/v1/account/sync/resume

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

Resposta200

{
  "object": "account_settings",
  "account_id": "a9PzK2vRtM",
  "sync": {
    "all_conversations": true,
    "status": "syncing",
    "conversations": 1342
  },
  "dms_paused_until": null,
  "owner": {
    "first_name": "Alex",
    "last_name": "Martin",
    "timezone": "Europe/Paris",
    "language": "en"
  }
}

O objeto X Chat

O X Chat é a inbox criptografada do X. O Gemlead lê as mensagens dele assim que tem o código do X Chat da conta, de 4 dígitos. A conexão do X Chat é feita no app.

Atributos

objectstring
Sempre x_chat.
connectedboolean
true quando a conta está conectada ao X Chat no app.
passcode_setboolean
true quando o Gemlead tem o código do X Chat. O código em si nunca é retornado.
unlockobject ou null
A descriptografia do histórico do X Chat após o envio do código, null quando nenhuma foi feita.

O objeto X Chat

{
  "object": "x_chat",
  "connected": true,
  "passcode_set": true,
  "unlock": {
    "running": false,
    "total": 214,
    "done": 214,
    "finished_at": "2026-11-06T07:58:30.000Z"
  }
}

Obter o X Chat

GET/v1/account/x_chatScope readMCPget_account_settings

Retorna se a conta está conectada ao X Chat, se o Gemlead tem o código dela e até onde foi a descriptografia do histórico.

Retorno

Um objeto X Chat.

GET/v1/account/x_chat

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

Resposta200

{
  "object": "x_chat",
  "connected": true,
  "passcode_set": true,
  "unlock": {
    "running": false,
    "total": 214,
    "done": 214,
    "finished_at": "2026-11-06T07:58:30.000Z"
  }
}

O resultado do código

O que definir ou remover o código do X Chat retorna.

Atributos

objectstring
Sempre x_chat.
passcode_setboolean
true quando o Gemlead guarda um código.
unlockedboolean
true quando o X aceitou o código e o Gemlead consegue ler as mensagens criptografadas.
reasonstring
Apenas quando o desbloqueio falha, o motivo. passcode significa que o X recusou o código, e o Gemlead o remove.
remaining_attemptsinteger ou null
Apenas quando o desbloqueio falha, as tentativas que o X ainda permite, se o X informar.

O resultado do código

{
  "object": "x_chat",
  "passcode_set": false,
  "unlocked": false,
  "reason": "passcode",
  "remaining_attempts": 3
}

Definir o código do X Chat

PUT/v1/account/x_chat/passcodeScope write

Passa ao Gemlead o código do X Chat da conta e depois desbloqueia as mensagens criptografadas com ele. Você pode tentar 5 vezes por hora, e o X conta cada tentativa. Apenas na API REST. Por design, nenhuma ferramenta MCP define ou remove um código, para que ele nunca passe por um chat de IA.

Parâmetros do corpo

passcodestringObrigatório
O código do X Chat, com 4 dígitos, como 4821.

Retorno

Um resultado do código, com reason e remaining_attempts quando o X recusou o código.

Erros

400parameter_missing
Falta um parâmetro obrigatório. param diz qual.
400parameter_invalid
Um parâmetro tem um valor que a API não aceita. param diz qual.
429passcode_rate_limited
Mais de 5 tentativas na mesma hora nesta conta.
502upstream_unavailable
O X ou um serviço do Gemlead não respondeu. Nada mudou, tente de novo em um minuto.

PUT/v1/account/x_chat/passcode

curl -X PUT \
  https://gemlead.ai/api/v1/account/x_chat/passcode \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "passcode": "4821"
  }'

Resposta200

{
  "object": "x_chat",
  "passcode_set": true,
  "unlocked": true
}

Remover o código do X Chat

DELETE/v1/account/x_chat/passcodeScope write

Remove o código do Gemlead. As novas mensagens do X Chat ficam criptografadas até você definir o código de novo. Apenas na API REST. Por design, nenhuma ferramenta MCP define ou remove um código, para que ele nunca passe por um chat de IA.

Retorno

Um resultado do código, com passcode_set em false.

DELETE/v1/account/x_chat/passcode

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

Resposta200

{
  "object": "x_chat",
  "passcode_set": false,
  "unlocked": false
}