Référence API

Julien AI

Julien AI est l'assistant de l'app Gemlead. Via l'API, il répond aux questions sur Gemlead et sur le compte X de la clé, ses leads, personas, campagnes et conversations. Il ne fait que répondre, et ne crée, ne modifie ni n'envoie jamais rien.

Envoie un message sans chat_id pour démarrer un chat, puis envoie les suivants avec le chat_id de la réponse pour le continuer. Tu as accès aux chats créés via l'API avec ce compte X, jamais aux chats de l'app.

Un envoi attend la réponse jusqu'à 25 secondes. Quand Julien AI a besoin de plus de temps, la réponse revient avec le statut running. Récupère-la à intervalles de quelques secondes jusqu'à ce qu'elle soit completed ou failed, ce qui prend 150 secondes au plus.

Chaque compte X peut envoyer 6 messages par minute et 100 par jour UTC, un seul à la fois par chat et 3 en parallèle, chacun de 1 à 4 000 caractères. Julien AI accepte aussi 150 messages par heure et par utilisateur, chat de l'app et API compris.

Endpoints

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

L'objet réponse de l'assistant

Un message à Julien AI et sa réponse. L'envoi la renvoie, et tu peux ensuite la relire avec son ID.

Attributs

idstring
Identifiant unique de la réponse, rpl_ suivi de 32 caractères.
objectstring
Toujours assistant_reply.
statusstring
running pendant que Julien AI écrit, puis completed ou failed.
runningcompletedfailed
chat_idstring ou null
Le chat du message. Passe-le avec le message suivant pour continuer dans le même chat. null tant que le premier message d'un nouveau chat est en cours.
messageobject ou null
Ton message tel que le chat le garde, un objet message de l'assistant. null tant que le statut n'est pas completed.
replyobject ou null
La réponse de Julien AI, un objet message de l'assistant. null tant que le statut n'est pas completed.
errorobject ou null
Pourquoi la réponse a échoué, null sinon.
created_atstring
Date d'envoi du message, en ISO 8601.
completed_atstring ou null
Date de fin de la réponse, terminée ou en échec, en ISO 8601. null tant qu'elle est en cours.

L'objet réponse de l'assistant

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

Envoyer un message

POST/v1/assistant/messagesScope writeMCPask_julien_ai

Envoie un message à Julien AI et attend sa réponse jusqu'à 25 secondes. Au-delà, la réponse revient en running et tu la récupères jusqu'à ce qu'elle se termine. Envoie-le avec une Idempotency-Key pour qu'une nouvelle tentative ne pose jamais la question deux fois.

Paramètres du corps

textstringObligatoire
Ton message, de 1 à 4 000 caractères.
chat_idstring
Le chat à continuer, issu d'une réponse précédente. Sans lui, le message démarre un nouveau chat.

Renvoie

Un objet réponse de l'assistant, completed avec la réponse, ou running quand Julien AI a besoin de plus de 25 secondes.

Erreurs

400parameter_missing
Il manque un paramètre obligatoire. param indique lequel.
400parameter_invalid
Le texte est vide ou dépasse 4 000 caractères. param indique le paramètre.
404resource_missing
Aucun chat avec cet ID créé via l'API avec ce compte X. Pour les chats de l'app, la réponse est la même.
409assistant_busy
Julien AI répond encore à un message de ce chat, ou à 3 messages de ce compte X.
429assistant_rate_limited
Plus de 6 messages dans la minute depuis ce compte X, ou 150 dans l'heure pour son propriétaire.
429assistant_daily_limit
Déjà 100 messages depuis ce compte X sur la journée UTC en cours.
502upstream_unavailable
Julien AI n'est pas disponible ou n'a pas pu répondre. Un message qu'il a reçu reste dans le 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?"
  }'

Réponse200

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

Récupérer une réponse

GET/v1/assistant/replies/:reply_idScope readMCPask_julien_ai

Renvoie une réponse. Tant qu'elle est running, récupère-la à intervalles de quelques secondes. Elle finit en completed avec la réponse de Julien AI, ou en failed avec son error.

Paramètres de chemin

reply_idstringObligatoire
L'ID de la réponse.

Renvoie

Un objet réponse de l'assistant.

Erreurs

404resource_missing
Aucune réponse avec cet ID sur le compte X de la clé.

GET/v1/assistant/replies/:reply_id

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

Réponse200

{
  "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'objet message de l'assistant

Un message d'un chat avec Julien AI, de toi ou de lui.

Attributs

idstring
Identifiant unique du message.
objectstring
Toujours assistant_message.
chat_idstring
Le chat auquel il appartient.
rolestring
user pour tes messages, assistant pour ceux de Julien AI.
userassistant
textstring
Le message. Pour Julien AI, sa réponse, puis la question qu'il te pose s'il en pose une.
created_atstring
Date d'envoi du message, en ISO 8601.

L'objet message de l'assistant

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

Lister les messages

GET/v1/assistant/messagesScope read

Renvoie les messages de tes chats avec Julien AI créés via l'API, les tiens et ses réponses, du plus récent au plus ancien.

Paramètres de requête

chat_idstring
Seulement les messages de ce chat. Par défaut tous les chats de ce compte X.
limitinteger
Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
cursorstring
Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets message de l'assistant.

Erreurs

404resource_missing
Aucun chat avec cet ID créé via l'API avec ce compte X. Pour les chats de l'app, la réponse est la même.
400parameter_invalid
Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.

GET/v1/assistant/messages

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

Réponse200

{
  "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'objet chat de l'assistant

Un chat avec Julien AI démarré via l'API.

Attributs

idstring
Identifiant unique du chat, le chat_id de ses messages.
objectstring
Toujours assistant_chat.
titlestring
Le titre du chat, donné comme dans l'app. New chat tant qu'il n'en a pas.
created_atstring
Date de début du chat, en ISO 8601.
last_message_atstring
Date de son dernier message, en ISO 8601.
last_message_previewstring
Le début de son dernier message.

L'objet chat de l'assistant

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

Lister les chats

GET/v1/assistant/chatsScope read

Renvoie tes chats avec Julien AI créés via l'API avec ce compte X, le plus récemment actif en premier.

Paramètres de requête

limitinteger
Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
cursorstring
Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets chat de l'assistant.

Erreurs

400parameter_invalid
Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.

GET/v1/assistant/chats

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

Réponse200

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