Riferimento API

Julien AI

Julien AI è l'assistente dell'app Gemlead. Tramite l'API risponde a domande su Gemlead e sull'account X della chiave, cioè i suoi lead, le sue buyer persona, campagne e conversazioni. Risponde e basta, non crea, non modifica e non invia mai nulla.

Invia un messaggio senza chat_id per iniziare una chat, poi invia i successivi con il chat_id della risposta per continuarla. Accedi alle chat create tramite l'API con questo account X, mai alle chat dell'app.

Un invio attende la risposta fino a 25 secondi. Quando Julien AI ha bisogno di più tempo, la risposta torna con lo stato running. Recuperala ogni qualche secondo finché è completed o failed, cosa che richiede al massimo 150 secondi.

Ogni account X può inviare 6 messaggi al minuto e 100 al giorno in UTC, uno alla volta in una chat e 3 in contemporanea, ognuno da 1 a 4 000 caratteri. Julien AI accetta anche 150 messaggi all'ora per utente, chat dell'app e API insieme.

Endpoint

POST/v1/assistant/messages
GET/v1/assistant/replies/:reply_id
GET/v1/assistant/messages
GET/v1/assistant/chats

L'oggetto risposta dell'assistente

Un messaggio a Julien AI e la sua risposta. Un invio lo restituisce, e resta leggibile tramite il suo ID.

Attributi

idstring
Identificatore univoco della risposta, rpl_ e 32 caratteri.
objectstring
Sempre assistant_reply.
statusstring
running mentre Julien AI scrive, poi completed o failed.
runningcompletedfailed
chat_idstring o null
La chat del messaggio. Invia con questo valore il messaggio successivo per continuare nella stessa chat. null mentre è in corso il primo messaggio di una nuova chat.
messageobject o null
Il tuo messaggio come lo conserva la chat, un oggetto messaggio dell'assistente. null finché lo stato non è completed.
replyobject o null
La risposta di Julien AI, un oggetto messaggio dell'assistente. null finché lo stato non è completed.
errorobject o null
Perché la risposta non è riuscita, altrimenti null.
created_atstring
Quando è stato inviato il messaggio, ISO 8601.
completed_atstring o null
Quando la risposta si è conclusa, completata o fallita, ISO 8601. null mentre è in corso.

L'oggetto risposta dell'assistente

{
  "id": "rpl_7Hq2LmX9vR4tKp8WzN3cYd6FbJ1sGa5E",
  "object": "assistant_reply",
  "status": "completed",
  "chat_id": "Jc7Rk2WqNb",
  "message": {
    "id": "Qm4xT8vLpZ",
    "object": "assistant_message",
    "chat_id": "Jc7Rk2WqNb",
    "role": "user",
    "text": "Which persona brought the most hot leads?",
    "created_at": "2026-11-06T09:14:02.000Z"
  },
  "reply": {
    "id": "Ra9Yh3KsDw",
    "object": "assistant_message",
    "chat_id": "Jc7Rk2WqNb",
    "role": "assistant",
    "text": "Tipsters, with 38 hot leads this week out of 412 scored. Most of them follow @bettingpros.\n\nShould I compare it with last week?",
    "created_at": "2026-11-06T09:14:09.000Z"
  },
  "error": null,
  "created_at": "2026-11-06T09:14:02.000Z",
  "completed_at": "2026-11-06T09:14:09.000Z"
}

Invia un messaggio

POST/v1/assistant/messagesScope writeMCPask_julien_ai

Invia un messaggio a Julien AI e attende la sua risposta fino a 25 secondi. Oltre questo limite, la risposta torna running e la recuperi finché non si conclude. Invialo con una Idempotency-Key, così un nuovo tentativo non fa mai la domanda due volte.

Parametri del body

textstringObbligatorio
Il tuo messaggio, da 1 a 4 000 caratteri.
chat_idstring
La chat in cui continuare, da una risposta precedente. Senza, il messaggio inizia una nuova chat.

Restituisce

Un oggetto risposta dell'assistente, completed con la risposta, oppure running quando Julien AI ha bisogno di più di 25 secondi.

Errori

400parameter_missing
Manca un parametro obbligatorio. param lo indica.
400parameter_invalid
Il testo è vuoto o supera i 4 000 caratteri. param lo indica.
404resource_missing
Nessuna chat con questo ID creata tramite l'API con questo account X. Le chat dell'app ricevono la stessa risposta.
409assistant_busy
Julien AI sta ancora rispondendo a un messaggio di questa chat, o a 3 messaggi di questo account X.
429assistant_rate_limited
Più di 6 messaggi in un minuto da questo account X, o 150 in un'ora per il suo proprietario.
429assistant_daily_limit
100 messaggi oggi, in UTC, da questo account X.
502upstream_unavailable
Julien AI non è disponibile o non è riuscito a rispondere. Un messaggio che ha ricevuto resta nella chat.

POST/v1/assistant/messages

curl -X POST https://gemlead.ai/api/v1/assistant/messages \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Which persona brought the most hot leads?"
  }'

Risposta200

{
  "id": "rpl_7Hq2LmX9vR4tKp8WzN3cYd6FbJ1sGa5E",
  "object": "assistant_reply",
  "status": "completed",
  "chat_id": "Jc7Rk2WqNb",
  "message": {
    "id": "Qm4xT8vLpZ",
    "object": "assistant_message",
    "chat_id": "Jc7Rk2WqNb",
    "role": "user",
    "text": "Which persona brought the most hot leads?",
    "created_at": "2026-11-06T09:14:02.000Z"
  },
  "reply": {
    "id": "Ra9Yh3KsDw",
    "object": "assistant_message",
    "chat_id": "Jc7Rk2WqNb",
    "role": "assistant",
    "text": "Tipsters, with 38 hot leads this week out of 412 scored. Most of them follow @bettingpros.\n\nShould I compare it with last week?",
    "created_at": "2026-11-06T09:14:09.000Z"
  },
  "error": null,
  "created_at": "2026-11-06T09:14:02.000Z",
  "completed_at": "2026-11-06T09:14:09.000Z"
}

Recupera una risposta

GET/v1/assistant/replies/:reply_idScope readMCPask_julien_ai

Restituisce una risposta. Finché è running, recuperala ogni qualche secondo. Si conclude completed con la risposta di Julien AI, oppure failed con il suo error.

Parametri di percorso

reply_idstringObbligatorio
L'ID della risposta.

Restituisce

Un oggetto risposta dell'assistente.

Errori

404resource_missing
Nessuna risposta con questo ID sull'account X della chiave.

GET/v1/assistant/replies/:reply_id

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

Risposta200

{
  "id": "rpl_7Hq2LmX9vR4tKp8WzN3cYd6FbJ1sGa5E",
  "object": "assistant_reply",
  "status": "running",
  "chat_id": "Jc7Rk2WqNb",
  "message": null,
  "reply": null,
  "error": null,
  "created_at": "2026-11-06T09:14:02.000Z",
  "completed_at": null
}

L'oggetto messaggio dell'assistente

Un messaggio di una chat con Julien AI, tuo o suo.

Attributi

idstring
Identificatore univoco del messaggio.
objectstring
Sempre assistant_message.
chat_idstring
La chat a cui appartiene.
rolestring
user per i tuoi messaggi, assistant per quelli di Julien AI.
userassistant
textstring
Il messaggio. Per Julien AI, la sua risposta seguita dalla domanda che ti fa, se ne fa una.
created_atstring
Quando è stato inviato il messaggio, ISO 8601.

L'oggetto messaggio dell'assistente

{
  "id": "Ra9Yh3KsDw",
  "object": "assistant_message",
  "chat_id": "Jc7Rk2WqNb",
  "role": "assistant",
  "text": "Tipsters, with 38 hot leads this week out of 412 scored. Most of them follow @bettingpros.\n\nShould I compare it with last week?",
  "created_at": "2026-11-06T09:14:09.000Z"
}

Elenca i messaggi

GET/v1/assistant/messagesScope read

Restituisce i messaggi delle tue chat con Julien AI create tramite l'API, i tuoi e le sue risposte, dal più recente.

Parametri di query

chat_idstring
Solo i messaggi di questa chat. Di default tutte le chat di questo account X.
limitinteger
Quanti oggetti restituire, da 1 a 100. Di default 25.
cursorstring
Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti messaggio dell'assistente.

Errori

404resource_missing
Nessuna chat con questo ID creata tramite l'API con questo account X. Le chat dell'app ricevono la stessa risposta.
400parameter_invalid
Un parametro ha un valore che l'API non accetta. param lo indica.

GET/v1/assistant/messages

curl -G https://gemlead.ai/api/v1/assistant/messages \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d chat_id=Jc7Rk2WqNb

Risposta200

{
  "object": "list",
  "data": [
    {
      "id": "Ra9Yh3KsDw",
      "object": "assistant_message",
      "chat_id": "Jc7Rk2WqNb",
      "role": "assistant",
      "text": "Tipsters, with 38 hot leads this week out of 412 scored. Most of them follow @bettingpros.\n\nShould I compare it with last week?",
      "created_at": "2026-11-06T09:14:09.000Z"
    },
    {
      "id": "Qm4xT8vLpZ",
      "object": "assistant_message",
      "chat_id": "Jc7Rk2WqNb",
      "role": "user",
      "text": "Which persona brought the most hot leads?",
      "created_at": "2026-11-06T09:14:02.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

L'oggetto chat dell'assistente

Una chat con Julien AI iniziata tramite l'API.

Attributi

idstring
Identificatore univoco della chat, il chat_id dei suoi messaggi.
objectstring
Sempre assistant_chat.
titlestring
Il titolo della chat, come lo assegna l'app. New chat finché non ne ha uno.
created_atstring
Quando è iniziata la chat, ISO 8601.
last_message_atstring
Quando è stato inviato il suo ultimo messaggio, ISO 8601.
last_message_previewstring
L'inizio del suo ultimo messaggio.

L'oggetto chat dell'assistente

{
  "id": "Jc7Rk2WqNb",
  "object": "assistant_chat",
  "title": "Hot leads this week",
  "created_at": "2026-11-06T09:14:02.000Z",
  "last_message_at": "2026-11-06T09:14:09.000Z",
  "last_message_preview": "Tipsters, with 38 hot leads this week out of 412 scored."
}

Elenca le chat

GET/v1/assistant/chatsScope read

Restituisce le tue chat con Julien AI create tramite l'API con questo account X, a partire da quella attiva più di recente.

Parametri di query

limitinteger
Quanti oggetti restituire, da 1 a 100. Di default 25.
cursorstring
Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti chat dell'assistente.

Errori

400parameter_invalid
Un parametro ha un valore che l'API non accetta. param lo indica.

GET/v1/assistant/chats

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

Risposta200

{
  "object": "list",
  "data": [
    {
      "id": "Jc7Rk2WqNb",
      "object": "assistant_chat",
      "title": "Hot leads this week",
      "created_at": "2026-11-06T09:14:02.000Z",
      "last_message_at": "2026-11-06T09:14:09.000Z",
      "last_message_preview": "Tipsters, with 38 hot leads this week out of 412 scored."
    }
  ],
  "has_more": false,
  "next_cursor": null
}