API reference

Account

The account is the X account a key belongs to. Read it to check a key, change its settings, restart the sync of its X inbox or give Gemlead its X Chat passcode. The owner's time zone, language and name are shared by all their X accounts.

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

The account object

The X account a key belongs to. A key works on one X account, and an owner with several X accounts has a key for each.

Attributes

objectstring
Always account.
idstring
Unique identifier for the account.
usernamestring
The X username, without the @.
namestring
The display name on X.
profile_image_urlstring or null
The profile picture's URL.
planstring
The owner's plan.
businessenterprise

Account object

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

Retrieve the account

GET/v1/accountread scopeMCPget_account

Returns the X account the key belongs to. A good first call to check a key.

Returns

An account object.

Errors

401api_key_invalid
The key is wrong.
403plan_required
The account's owner is on the Free or Starter plan.

GET/v1/account

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

Response200

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

Refresh the X profile

POST/v1/account/refresh_profilewrite scopeMCPupdate_account_settings

Reads the account's X profile again, for a new name or photo.

Returns

The account object.

Errors

409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a minute.

POST/v1/account/refresh_profile

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

Response200

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

The account settings object

How the account syncs its X inbox, whether its DMs are paused, and its owner's profile. The owner's time zone, language and name are shared by all their X accounts.

Attributes

objectstring
Always account_settings.
account_idstring
The account's ID.
syncobject
The sync of the X inbox into Gemlead.
dms_paused_untilstring or null
While X limits the account, when its DMs start again, ISO 8601.
ownerobject
The owner of the account.

Account settings object

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

Retrieve account settings

GET/v1/account/settingsread scopeMCPget_account_settings

Returns the inbox sync, the DM pause and the owner's profile.

Returns

An account settings object.

GET/v1/account/settings

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

Response200

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

Update account settings

PATCH/v1/account/settingswrite scopeMCPupdate_account_settings

Changes the settings you send and keeps the others.

Body parameters

sync_all_conversationsboolean
true syncs every conversation of the X inbox and walks it again now. false keeps the conversations with leads only.
timezonestring
The owner's IANA time zone, like Europe/Paris. Charts and daily counts follow it.
languagestring
The owner's app language.
enfresitderuptnlja
first_namestring
The owner's first name, up to 60 characters.
last_namestring
The owner's last name, up to 60 characters.

Returns

The updated account settings object.

Errors

400parameter_invalid
A parameter has a value the API does not accept. param names it.
400parameter_unknown
The body has a field this endpoint does not take.
409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.

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

Response200

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

Restart the inbox sync

POST/v1/account/sync/restartwrite scopeMCPupdate_account_settings

Walks the X inbox again from the start, to bring back conversations Gemlead missed.

Returns

The account settings object.

Errors

409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.

POST/v1/account/sync/restart

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

Response200

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

Pause the inbox sync

POST/v1/account/sync/pausewrite scopeMCPupdate_account_settings

Pauses the sync of the X inbox.

Returns

The account settings object.

Errors

409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.

POST/v1/account/sync/pause

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

Response200

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

Resume the inbox sync

POST/v1/account/sync/resumewrite scopeMCPupdate_account_settings

Resumes a paused sync of the X inbox.

Returns

The account settings object.

Errors

409x_session_expired
The X account's session expired. Reconnect it in the app, then try again.

POST/v1/account/sync/resume

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

Response200

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

The X Chat object

X Chat is X's encrypted inbox. Gemlead reads its messages once it has the account's 4 digit X Chat passcode. Connecting X Chat happens in the app.

Attributes

objectstring
Always x_chat.
connectedboolean
true when the account is connected to X Chat in the app.
passcode_setboolean
true when Gemlead has the X Chat passcode. The passcode itself is never returned.
unlockobject or null
The decryption of the X Chat history after the passcode, null when none ran.

X Chat object

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

Retrieve X Chat

GET/v1/account/x_chatread scopeMCPget_account_settings

Returns whether the account is connected to X Chat, whether Gemlead has its passcode, and how far the decryption of its history went.

Returns

An X Chat object.

GET/v1/account/x_chat

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

Response200

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

The passcode result

What setting or removing the X Chat passcode returns.

Attributes

objectstring
Always x_chat.
passcode_setboolean
true when Gemlead keeps a passcode.
unlockedboolean
true when X accepted the passcode and Gemlead can read the encrypted messages.
reasonstring
Only when it did not unlock, why. passcode means X refused the passcode, and Gemlead removes it.
remaining_attemptsinteger or null
Only when it did not unlock, the tries X still allows, when X says.

Passcode result

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

Set the X Chat passcode

PUT/v1/account/x_chat/passcodewrite scope

Gives Gemlead the account's X Chat passcode, then unlocks the encrypted messages with it. You can try 5 times an hour, X counts every try. REST only. No MCP tool sets or removes a passcode, by design, so a passcode never goes through an AI chat.

Body parameters

passcodestringRequired
The X Chat passcode, 4 digits like 4821.

Returns

A passcode result, with reason and remaining_attempts when X refused the passcode.

Errors

400parameter_missing
A required parameter is missing. param names it.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
429passcode_rate_limited
More than 5 tries in the hour on the account.
502upstream_unavailable
X or a Gemlead service did not answer. Nothing changed, try again in a 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"
  }'

Response200

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

Remove the X Chat passcode

DELETE/v1/account/x_chat/passcodewrite scope

Removes the passcode from Gemlead. New X Chat messages stay encrypted until you set it again. REST only. No MCP tool sets or removes a passcode, by design, so a passcode never goes through an AI chat.

Returns

A passcode result, passcode_set at 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"

Response200

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