Referencia de la API

Cuenta

La cuenta es la cuenta de X a la que pertenece una clave. Léela para comprobar una clave, cambiar sus ajustes, reiniciar la sincronización de su inbox de X o dar a Gemlead su código de X Chat. La zona horaria, el idioma y el nombre del propietario son comunes a todas sus cuentas de 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

El objeto account

La cuenta de X a la que pertenece una clave. Una clave funciona con una sola cuenta de X, y un propietario con varias cuentas de X tiene una clave para cada una.

Atributos

objectstring
Siempre account.
idstring
Identificador único de la cuenta.
usernamestring
El nombre de usuario de X, sin la @.
namestring
El nombre visible en X.
profile_image_urlstring o null
La URL de la foto de perfil.
planstring
El plan del propietario.
businessenterprise

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

Obtener la cuenta

GET/v1/accountScope readMCPget_account

Devuelve la cuenta de X a la que pertenece la clave. Una buena primera llamada para comprobar una clave.

Devuelve

Un objeto account.

Errores

401api_key_invalid
La clave es incorrecta.
403plan_required
El propietario de la cuenta tiene el plan Free o Starter.

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

Actualizar el perfil de X

POST/v1/account/refresh_profileScope writeMCPupdate_account_settings

Vuelve a leer el perfil de X de la cuenta, para tener al día su nombre o su foto.

Devuelve

El objeto account.

Errores

409x_session_expired
La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.
502upstream_unavailable
X o un servicio de Gemlead no respondió. No ha cambiado nada, vuelve a intentarlo en un minuto.

POST/v1/account/refresh_profile

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

El objeto account settings

Cómo sincroniza la cuenta su inbox de X, si sus DM están en pausa y el perfil de su propietario. La zona horaria, el idioma y el nombre del propietario son comunes a todas sus cuentas de X.

Atributos

objectstring
Siempre account_settings.
account_idstring
El ID de la cuenta.
syncobject
La sincronización del inbox de X con Gemlead.
dms_paused_untilstring o null
Mientras X limita la cuenta, cuándo se reanudan sus DM, en ISO 8601.
ownerobject
El propietario de la cuenta.

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

Obtener los ajustes de la cuenta

GET/v1/account/settingsScope readMCPget_account_settings

Devuelve la sincronización del inbox, la pausa de DM y el perfil del propietario.

Devuelve

Un objeto account settings.

GET/v1/account/settings

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

Respuesta200

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

Actualizar los ajustes de la cuenta

PATCH/v1/account/settingsScope writeMCPupdate_account_settings

Cambia los ajustes que envías y conserva los demás.

Parámetros del cuerpo

sync_all_conversationsboolean
true sincroniza todas las conversaciones del inbox de X y vuelve a recorrerlo ahora. false conserva solo las conversaciones con leads.
timezonestring
La zona horaria IANA del propietario, como Europe/Paris. Los gráficos y los totales diarios se basan en ella.
languagestring
El idioma de la app del propietario.
enfresitderuptnlja
first_namestring
El nombre del propietario, hasta 60 caracteres.
last_namestring
El apellido del propietario, hasta 60 caracteres.

Devuelve

El objeto account settings actualizado.

Errores

400parameter_invalid
Un parámetro tiene un valor que la API no acepta. param lo indica.
400parameter_unknown
El cuerpo tiene un campo que este endpoint no acepta.
409x_session_expired
La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.

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

Respuesta200

{
  "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 la sincronización del inbox

POST/v1/account/sync/restartScope writeMCPupdate_account_settings

Vuelve a recorrer el inbox de X desde el principio, para recuperar las conversaciones que se le escaparon a Gemlead.

Devuelve

El objeto account settings.

Errores

409x_session_expired
La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.

POST/v1/account/sync/restart

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

Respuesta200

{
  "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 la sincronización del inbox

POST/v1/account/sync/pauseScope writeMCPupdate_account_settings

Pausa la sincronización del inbox de X.

Devuelve

El objeto account settings.

Errores

409x_session_expired
La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.

POST/v1/account/sync/pause

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

Respuesta200

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

Reanudar la sincronización del inbox

POST/v1/account/sync/resumeScope writeMCPupdate_account_settings

Reanuda una sincronización del inbox de X en pausa.

Devuelve

El objeto account settings.

Errores

409x_session_expired
La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.

POST/v1/account/sync/resume

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

Respuesta200

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

El objeto X Chat

X Chat es el inbox cifrado de X. Gemlead lee sus mensajes en cuanto tiene el código de X Chat de 4 cifras de la cuenta. X Chat se conecta desde la app.

Atributos

objectstring
Siempre x_chat.
connectedboolean
true si la cuenta está conectada a X Chat en la app.
passcode_setboolean
true si Gemlead tiene el código de X Chat. El código en sí nunca se devuelve.
unlockobject o null
El descifrado del historial de X Chat tras introducir el código, null si no se ha hecho ninguno.

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

Obtener X Chat

GET/v1/account/x_chatScope readMCPget_account_settings

Indica si la cuenta está conectada a X Chat, si Gemlead tiene su código y hasta dónde llegó el descifrado de su historial.

Devuelve

Un objeto X Chat.

GET/v1/account/x_chat

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

Respuesta200

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

El resultado del código

Lo que devuelve definir o eliminar el código de X Chat.

Atributos

objectstring
Siempre x_chat.
passcode_setboolean
true si Gemlead guarda un código.
unlockedboolean
true si X aceptó el código y Gemlead puede leer los mensajes cifrados.
reasonstring
Solo si no se desbloqueó, el motivo. passcode significa que X rechazó el código, y Gemlead lo elimina.
remaining_attemptsinteger o null
Solo si no se desbloqueó, los intentos que X aún permite, cuando X lo indica.

El resultado del código

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

Definir el código de X Chat

PUT/v1/account/x_chat/passcodeScope write

Da a Gemlead el código de X Chat de la cuenta y desbloquea con él los mensajes cifrados. Puedes probar 5 veces por hora, X cuenta cada intento. Solo REST. Ninguna herramienta MCP define ni elimina un código, por diseño, para que un código nunca pase por un chat de IA.

Parámetros del cuerpo

passcodestringObligatorio
El código de X Chat, 4 cifras, como 4821.

Devuelve

Un resultado del código, con reason y remaining_attempts si X rechazó el código.

Errores

400parameter_missing
Falta un parámetro obligatorio. param lo indica.
400parameter_invalid
Un parámetro tiene un valor que la API no acepta. param lo indica.
429passcode_rate_limited
Más de 5 intentos en una hora en la cuenta.
502upstream_unavailable
X o un servicio de Gemlead no respondió. No ha cambiado nada, vuelve a intentarlo en un 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"
  }'

Respuesta200

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

Eliminar el código de X Chat

DELETE/v1/account/x_chat/passcodeScope write

Elimina el código de Gemlead. Los nuevos mensajes de X Chat siguen cifrados hasta que lo vuelvas a definir. Solo REST. Ninguna herramienta MCP define ni elimina un código, por diseño, para que un código nunca pase por un chat de IA.

Devuelve

Un resultado del código, con passcode_set en 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"

Respuesta200

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