Per iniziare

Autenticazione

Ogni richiesta include una chiave segreta dell'account X su cui opera. Crei le chiavi nell'app, puoi limitarle alla lettura e smettono di funzionare appena le revochi.

Chiavi API

Una chiave è gl_live_ seguito da 32 lettere e cifre. L'app mostra i suoi primi 12 caratteri, come gl_live_AbCd, così distingui le tue chiavi.
Ogni chiave appartiene a un solo account X in Gemlead e vede solo i lead, le buyer persona, le campagne e le conversazioni di quell'account.
La chiave completa appare una sola volta, quando la crei. Gemlead ne conserva solo un hash, quindi una chiave persa non si può più mostrare. Creane una nuova.
Un account può avere 20 chiavi attive.

L'API è inclusa nei piani Business ed Enterprise, prova compresa. Quando il proprietario dell'account è sul piano Free o Starter, le richieste rispondono 403 con il codice plan_required. Le chiavi restano e tornano a funzionare appena l'account passa a Business o Enterprise.

Invia la chiave

Invia la chiave come bearer token nell'header Authorization. Funziona anche l'header X-Api-Key, per gli strumenti che non possono impostare un bearer token.

Una richiesta senza chiave risponde 401 con il codice api_key_missing, una chiave sbagliata con api_key_invalid e una revocata con api_key_revoked.

Terminale

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

Scope

Una chiave ha lo scope read, oppure read e write. Dai write solo agli strumenti che modificano i dati.

Scope	Consente
`read`	Ogni `GET`, e `POST /v1/exports` perché un export si limita a leggere.
`write`	Ogni richiesta che modifica i dati, `POST`, `PATCH`, `PUT` e `DELETE`.

Una chiave read che prova a modificare i dati riceve 403 con il codice insufficient_scope.

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

L'oggetto account, con plan impostato su business o enterprise.

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

Tieni al sicuro le chiavi

Chiama l'API solo dal tuo server, mai da un browser, da un'app mobile o dal codice di un repository pubblico.
Conserva le chiavi in un secret manager o in una variabile d'ambiente come GEMLEAD_API_KEY.
Dai a ogni strumento la sua chiave, così puoi revocarne una senza toccare le altre.
Per ruotare una chiave, crea quella nuova, fanne il deploy, poi revoca la vecchia nell'app.

Assistenti IA

Claude e ChatGPT si collegano al server MCP con OAuth. Accedi a Gemlead e scegli l'account X, non c'è nessuna chiave da copiare. Cursor e Claude Code possono usare una chiave, inviata come sopra.