Riferimento API

Account

L'account è l'account X a cui appartiene una chiave. Leggilo per verificare una chiave, cambiare le sue impostazioni, far ripartire la sincronizzazione della sua inbox di X o dare a Gemlead il suo codice X Chat. Il fuso orario, la lingua e il nome del proprietario valgono per tutti i suoi account X.

Endpoint

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'oggetto account

L'account X a cui appartiene una chiave. Una chiave funziona su un solo account X, e un proprietario con più account X ha una chiave per ognuno.

Attributi

objectstring
Sempre account.
idstring
Identificatore univoco dell'account.
usernamestring
Lo username X, senza la @.
namestring
Il nome visualizzato su X.
profile_image_urlstring o null
L'URL della foto profilo.
planstring
Il piano del proprietario.
businessenterprise

L'oggetto account

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

Recupera l'account

GET/v1/accountScope readMCPget_account

Restituisce l'account X a cui appartiene la chiave. Una buona prima chiamata per verificare una chiave.

Restituisce

Un oggetto account.

Errori

401api_key_invalid
La chiave è sbagliata.
403plan_required
Il proprietario dell'account è sul piano Free o Starter.

GET/v1/account

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

Risposta200

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

Aggiorna il profilo X

POST/v1/account/refresh_profileScope writeMCPupdate_account_settings

Rilegge il profilo X dell'account, per un nuovo nome o una nuova foto.

Restituisce

L'oggetto account.

Errori

409x_session_expired
La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.
502upstream_unavailable
X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra un minuto.

POST/v1/account/refresh_profile

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

Risposta200

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

L'oggetto impostazioni dell'account

Come l'account sincronizza la sua inbox di X, se i suoi DM sono in pausa, e il profilo del suo proprietario. Il fuso orario, la lingua e il nome del proprietario valgono per tutti i suoi account X.

Attributi

objectstring
Sempre account_settings.
account_idstring
L'ID dell'account.
syncobject
La sincronizzazione dell'inbox di X in Gemlead.
dms_paused_untilstring o null
Mentre X limita l'account, quando ripartono i suoi DM, ISO 8601.
ownerobject
Il proprietario dell'account.

L'oggetto impostazioni dell'account

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

Recupera le impostazioni dell'account

GET/v1/account/settingsScope readMCPget_account_settings

Restituisce la sincronizzazione dell'inbox, la pausa dei DM e il profilo del proprietario.

Restituisce

Un oggetto impostazioni dell'account.

GET/v1/account/settings

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

Risposta200

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

Aggiorna le impostazioni dell'account

PATCH/v1/account/settingsScope writeMCPupdate_account_settings

Modifica le impostazioni che invii e mantiene le altre.

Parametri del body

sync_all_conversationsboolean
true sincronizza tutte le conversazioni dell'inbox di X e la ripercorre subito. false mantiene solo le conversazioni con i lead.
timezonestring
Il fuso orario IANA del proprietario, come Europe/Paris. I grafici e i conteggi giornalieri si basano su questo fuso.
languagestring
La lingua dell'app del proprietario.
enfresitderuptnlja
first_namestring
Il nome del proprietario, fino a 60 caratteri.
last_namestring
Il cognome del proprietario, fino a 60 caratteri.

Restituisce

L'oggetto impostazioni dell'account aggiornato.

Errori

400parameter_invalid
Un parametro ha un valore che l'API non accetta. param lo indica.
400parameter_unknown
Il body ha un campo che questo endpoint non accetta.
409x_session_expired
La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.

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

Risposta200

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

Riavvia la sincronizzazione dell'inbox

POST/v1/account/sync/restartScope writeMCPupdate_account_settings

Ripercorre l'inbox di X dall'inizio, per recuperare le conversazioni che Gemlead ha perso.

Restituisce

L'oggetto impostazioni dell'account.

Errori

409x_session_expired
La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.

POST/v1/account/sync/restart

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

Risposta200

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

Metti in pausa la sincronizzazione dell'inbox

POST/v1/account/sync/pauseScope writeMCPupdate_account_settings

Mette in pausa la sincronizzazione dell'inbox di X.

Restituisce

L'oggetto impostazioni dell'account.

Errori

409x_session_expired
La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.

POST/v1/account/sync/pause

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

Risposta200

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

Riprendi la sincronizzazione dell'inbox

POST/v1/account/sync/resumeScope writeMCPupdate_account_settings

Riprende una sincronizzazione in pausa dell'inbox di X.

Restituisce

L'oggetto impostazioni dell'account.

Errori

409x_session_expired
La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.

POST/v1/account/sync/resume

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

Risposta200

{
  "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'oggetto X Chat

X Chat è l'inbox crittografata di X. Gemlead legge i suoi messaggi quando ha il codice X Chat a 4 cifre dell'account. Il collegamento a X Chat si fa nell'app.

Attributi

objectstring
Sempre x_chat.
connectedboolean
true quando l'account è collegato a X Chat nell'app.
passcode_setboolean
true quando Gemlead ha il codice X Chat. Il codice non viene mai restituito.
unlockobject o null
La decrittazione della cronologia di X Chat dopo il codice, null quando non ce n'è stata nessuna.

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

Recupera X Chat

GET/v1/account/x_chatScope readMCPget_account_settings

Indica se l'account è collegato a X Chat, se Gemlead ha il suo codice e a che punto è la decrittazione della sua cronologia.

Restituisce

Un oggetto X Chat.

GET/v1/account/x_chat

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

Risposta200

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

Il risultato del codice

Cosa restituisce l'impostazione o la rimozione del codice X Chat.

Attributi

objectstring
Sempre x_chat.
passcode_setboolean
true quando Gemlead conserva un codice.
unlockedboolean
true quando X ha accettato il codice e Gemlead può leggere i messaggi crittografati.
reasonstring
Solo se lo sblocco non è riuscito, il motivo. passcode significa che X ha rifiutato il codice, e Gemlead lo rimuove.
remaining_attemptsinteger o null
Solo se lo sblocco non è riuscito, i tentativi che X consente ancora, quando X lo indica.

Il risultato del codice

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

Imposta il codice X Chat

PUT/v1/account/x_chat/passcodeScope write

Dà a Gemlead il codice X Chat dell'account, poi lo usa per sbloccare i messaggi crittografati. Puoi provare 5 volte all'ora, X conta ogni tentativo. Solo REST. Per scelta, nessun tool MCP imposta o rimuove un codice, così il codice non passa mai da una chat IA.

Parametri del body

passcodestringObbligatorio
Il codice X Chat, 4 cifre come 4821.

Restituisce

Un risultato del codice, con reason e remaining_attempts quando X ha rifiutato il codice.

Errori

400parameter_missing
Manca un parametro obbligatorio. param lo indica.
400parameter_invalid
Un parametro ha un valore che l'API non accetta. param lo indica.
429passcode_rate_limited
Più di 5 tentativi in un'ora sull'account.
502upstream_unavailable
X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra 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"
  }'

Risposta200

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

Rimuovi il codice X Chat

DELETE/v1/account/x_chat/passcodeScope write

Rimuove il codice da Gemlead. I nuovi messaggi di X Chat restano crittografati finché non lo imposti di nuovo. Solo REST. Per scelta, nessun tool MCP imposta o rimuove un codice, così il codice non passa mai da una chat IA.

Restituisce

Un risultato del codice, con passcode_set su 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"

Risposta200

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