Getting started
Authentication
Every request carries a secret key of the X account it works on. You make keys in the app, can limit them to reading, and they stop working the moment you revoke them.
API keys
- A key is
gl_live_followed by 32 letters and digits. The app shows its first 12 characters, likegl_live_AbCd, so you can tell your keys apart. - Each key belongs to one X account in Gemlead and only sees that account's leads, personas, campaigns and conversations.
- The whole key shows once, when you create it. Gemlead keeps only a hash of it, so a lost key cannot be shown again. Create a new one.
- An account can have 20 active keys.
The API comes with the Business and Enterprise plans, trial included. When the account's owner is on the Free or Starter plan, requests answer 403 with the code plan_required. The keys stay and work again once the account is on Business or Enterprise.
Send the key
Send the key as a bearer token in the Authorization header. The X-Api-Key header works too, for the tools that cannot set a bearer token.
A request without a key answers 401 with the code api_key_missing, a wrong key api_key_invalid and a revoked one api_key_revoked.
# As a bearer token
curl https://gemlead.ai/api/v1/account \
-H "Authorization: Bearer $GEMLEAD_API_KEY"
# Or in X-Api-Key, for tools that cannot set a bearer token
curl https://gemlead.ai/api/v1/account \
-H "X-Api-Key: $GEMLEAD_API_KEY"Scopes
A key has the read scope, or read and write. Give write only to the tools that change data.
| Scope | Allows |
|---|---|
read | Every GET, and POST /v1/exports since an export only reads. |
write | Every request that changes data, POST, PATCH, PUT and DELETE. |
A read key that tries to change data gets 403 with the code insufficient_scope.
Retrieve the account
Returns the X account the key belongs to. A good first call to check a key.
Returns
The account object, its plan at business or enterprise.
Errors
- The key is wrong.
- The account's owner is on the Free or Starter plan.
curl https://gemlead.ai/api/v1/account \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"object": "account",
"id": "a9PzK2vRtM",
"username": "acme",
"name": "Acme",
"profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg",
"plan": "business"
}Keep keys safe
- Call the API from your server only, never from a browser, a mobile app or the code of a public repository.
- Keep keys in a secret manager or an environment variable like
GEMLEAD_API_KEY. - Give each tool its own key, so you can revoke one without touching the others.
- To rotate a key, create the new one, deploy it, then revoke the old one in the app.
AI assistants
Claude and ChatGPT connect to the MCP server with OAuth. You sign in to Gemlead and pick the X account, there is no key to copy. Cursor and Claude Code can use a key, sent the same way as above.
