Référence API

Compte

Le compte est le compte X auquel une clé appartient. Lis-le pour tester une clé, modifier ses réglages, relancer la synchronisation de son inbox X ou donner à Gemlead son code X Chat. Le fuseau horaire, la langue et le nom du propriétaire sont communs à tous ses comptes X.

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

L'objet compte

Le compte X auquel une clé appartient. Une clé ne sert qu'à un seul compte X, et un propriétaire avec plusieurs comptes X a une clé pour chacun.

Attributs

objectstring
Toujours account.
idstring
Identifiant unique du compte.
usernamestring
Le nom d'utilisateur X, sans le @.
namestring
Le nom affiché sur X.
profile_image_urlstring ou null
L'URL de la photo de profil.
planstring
Le plan du propriétaire.
businessenterprise

L'objet compte

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

Récupérer le compte

GET/v1/accountScope readMCPget_account

Renvoie le compte X auquel appartient la clé. Un bon premier appel pour tester une clé.

Renvoie

Un objet compte.

Erreurs

401api_key_invalid
La clé est incorrecte.
403plan_required
Le propriétaire du compte est sur le plan Free ou Starter.

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

Actualiser le profil X

POST/v1/account/refresh_profileScope writeMCPupdate_account_settings

Relit le profil X du compte, pour un nouveau nom ou une nouvelle photo.

Renvoie

L'objet compte.

Erreurs

409x_session_expired
La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.
502upstream_unavailable
X ou un service Gemlead n'a pas répondu. Rien n'a changé, réessaie dans une minute.

POST/v1/account/refresh_profile

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

L'objet réglages du compte

Comment le compte synchronise son inbox X, si ses DM sont en pause, et le profil de son propriétaire. Le fuseau horaire, la langue et le nom du propriétaire sont communs à tous ses comptes X.

Attributs

objectstring
Toujours account_settings.
account_idstring
L'ID du compte.
syncobject
La synchronisation de l'inbox X dans Gemlead.
dms_paused_untilstring ou null
Tant que X limite le compte, la date de reprise de ses DM, en ISO 8601.
ownerobject
Le propriétaire du compte.

L'objet réglages du compte

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

Récupérer les réglages du compte

GET/v1/account/settingsScope readMCPget_account_settings

Renvoie la synchronisation de l'inbox, la pause des DM et le profil du propriétaire.

Renvoie

Un objet réglages du compte.

GET/v1/account/settings

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

Réponse200

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

Modifier les réglages du compte

PATCH/v1/account/settingsScope writeMCPupdate_account_settings

Modifie les réglages que tu envoies et ne touche pas aux autres.

Paramètres du corps

sync_all_conversationsboolean
true synchronise toutes les conversations de l'inbox X et la reparcourt tout de suite. false ne garde que les conversations avec des leads.
timezonestring
Le fuseau horaire IANA du propriétaire, comme Europe/Paris. Les graphiques et les compteurs du jour le suivent.
languagestring
La langue de l'app du propriétaire.
enfresitderuptnlja
first_namestring
Le prénom du propriétaire, 60 caractères au plus.
last_namestring
Le nom du propriétaire, 60 caractères au plus.

Renvoie

L'objet réglages du compte à jour.

Erreurs

400parameter_invalid
Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
400parameter_unknown
Le corps contient un champ que cet endpoint n'accepte pas.
409x_session_expired
La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.

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

Réponse200

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

Relancer la synchronisation de l'inbox

POST/v1/account/sync/restartScope writeMCPupdate_account_settings

Reparcourt l'inbox X depuis le début, pour récupérer les conversations que Gemlead a manquées.

Renvoie

L'objet réglages du compte.

Erreurs

409x_session_expired
La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.

POST/v1/account/sync/restart

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

Réponse200

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

Mettre la synchronisation de l'inbox en pause

POST/v1/account/sync/pauseScope writeMCPupdate_account_settings

Met la synchronisation de l'inbox X en pause.

Renvoie

L'objet réglages du compte.

Erreurs

409x_session_expired
La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.

POST/v1/account/sync/pause

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

Réponse200

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

Reprendre la synchronisation de l'inbox

POST/v1/account/sync/resumeScope writeMCPupdate_account_settings

Reprend la synchronisation de l'inbox X mise en pause.

Renvoie

L'objet réglages du compte.

Erreurs

409x_session_expired
La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.

POST/v1/account/sync/resume

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

Réponse200

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

L'objet X Chat

X Chat est l'inbox chiffrée de X. Gemlead lit ses messages dès qu'il a le code X Chat à 4 chiffres du compte. La connexion à X Chat se fait dans l'app.

Attributs

objectstring
Toujours x_chat.
connectedboolean
true quand le compte est connecté à X Chat dans l'app.
passcode_setboolean
true quand Gemlead a le code X Chat. Le code lui-même n'est jamais renvoyé.
unlockobject ou null
Le déchiffrement de l'historique X Chat qui suit l'envoi du code, null s'il n'a pas eu lieu.

L'objet 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"
  }
}

Récupérer l'état de X Chat

GET/v1/account/x_chatScope readMCPget_account_settings

Indique si le compte est connecté à X Chat, si Gemlead a son code, et où en est le déchiffrement de son historique.

Renvoie

Un objet X Chat.

GET/v1/account/x_chat

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

Réponse200

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

Le résultat du code

Ce que renvoie la définition ou le retrait du code X Chat.

Attributs

objectstring
Toujours x_chat.
passcode_setboolean
true quand Gemlead conserve un code.
unlockedboolean
true quand X a accepté le code et que Gemlead peut lire les messages chiffrés.
reasonstring
Seulement en cas d'échec du déverrouillage, la raison. passcode signifie que X a refusé le code, et Gemlead le retire.
remaining_attemptsinteger ou null
Seulement en cas d'échec du déverrouillage, les essais que X autorise encore, quand X l'indique.

Le résultat du code

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

Définir le code X Chat

PUT/v1/account/x_chat/passcodeScope write

Donne à Gemlead le code X Chat du compte, qui s'en sert pour déverrouiller les messages chiffrés. Tu as 5 essais par heure, X compte chaque essai. REST uniquement. Aucun outil MCP ne définit ni ne retire de code, et c'est voulu, pour qu'un code ne passe jamais par un chat IA.

Paramètres du corps

passcodestringObligatoire
Le code X Chat à 4 chiffres, comme 4821.

Renvoie

Un résultat du code, avec reason et remaining_attempts quand X a refusé le code.

Erreurs

400parameter_missing
Il manque un paramètre obligatoire. param indique lequel.
400parameter_invalid
Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
429passcode_rate_limited
Plus de 5 essais dans l'heure sur le compte.
502upstream_unavailable
X ou un service Gemlead n'a pas répondu. Rien n'a changé, réessaie dans une minute.

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

Réponse200

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

Retirer le code X Chat

DELETE/v1/account/x_chat/passcodeScope write

Retire le code de Gemlead. Les nouveaux messages X Chat restent chiffrés jusqu'à ce que tu le redéfinisses. REST uniquement. Aucun outil MCP ne définit ni ne retire de code, et c'est voulu, pour qu'un code ne passe jamais par un chat IA.

Renvoie

Un résultat du code, avec passcode_set à 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"

Réponse200

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