API-referentie

Julien AI

Julien AI is de assistent van de Gemlead-app. Via de API beantwoordt hij vragen over Gemlead en over het X-account van de sleutel, met de leads, persona's, campagnes en gesprekken ervan. Hij antwoordt alleen en maakt, wijzigt of verstuurt nooit iets.

Stuur een bericht zonder chat_id om een chat te beginnen, en stuur de volgende met de chat_id uit het antwoord om erin verder te gaan. Je bereikt de chats die via de API met dit X-account zijn gemaakt, nooit de chats van de app.

Na het versturen wacht de API maximaal 25 seconden op het antwoord. Heeft Julien AI meer tijd nodig, dan komt het antwoord terug met de status running. Haal het om de paar seconden op tot het completed of failed is, wat hooguit 150 seconden duurt.

Elk X-account kan 6 berichten per minuut en 100 per UTC-dag sturen, één tegelijk per chat en 3 tegelijk in totaal, elk van 1 tot 4 000 tekens. Julien AI accepteert daarnaast maximaal 150 berichten per uur per gebruiker, de chat in de app en de API samen.

Endpoints

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

Het assistentantwoord-object

Eén bericht aan Julien AI en het antwoord erop. Je krijgt dit object terug als je een bericht verstuurt, en het blijft via de ID op te vragen.

Attributen

idstring
Unieke ID van het antwoord, rpl_ gevolgd door 32 tekens.
objectstring
Altijd assistant_reply.
statusstring
running terwijl Julien AI schrijft, daarna completed of failed.
runningcompletedfailed
chat_idstring of null
De chat van het bericht. Stuur het volgende bericht hiermee om in dezelfde chat verder te gaan. null zolang het eerste bericht van een nieuwe chat nog wordt verwerkt.
messageobject of null
Je bericht zoals de chat het bewaart, een assistentbericht-object. null tot de status completed is.
replyobject of null
Het antwoord van Julien AI, een assistentbericht-object. null tot de status completed is.
errorobject of null
Waarom het antwoord mislukte, anders null.
created_atstring
Wanneer het bericht is verstuurd, in ISO 8601.
completed_atstring of null
Wanneer het antwoord eindigde, voltooid of mislukt, in ISO 8601. null zolang het loopt.

Het assistentantwoord-object

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

Een bericht sturen

POST/v1/assistant/messagesScope writeMCPask_julien_ai

Stuurt een bericht naar Julien AI en wacht maximaal 25 seconden op het antwoord. Duurt het langer, dan komt het antwoord terug als running en haal je het op tot het klaar is. Stuur het met een Idempotency-Key, zodat een nieuwe poging de vraag nooit twee keer stelt.

Bodyparameters

textstringVerplicht
Je bericht, 1 tot 4 000 tekens.
chat_idstring
De chat om in verder te gaan, uit een eerder antwoord. Zonder deze waarde begint het bericht een nieuwe chat.

Resultaat

Een assistentantwoord-object, completed met het antwoord, of running als Julien AI meer dan 25 seconden nodig heeft.

Fouten

400parameter_missing
Er ontbreekt een verplichte parameter. param geeft aan welke.
400parameter_invalid
De tekst is leeg of langer dan 4 000 tekens. param noemt het veld.
404resource_missing
Geen chat met deze ID die via de API met dit X-account is gemaakt. Voor de eigen chats van de app krijg je hetzelfde antwoord.
409assistant_busy
Julien AI is nog bezig met een bericht in deze chat, of met 3 berichten van dit X-account.
429assistant_rate_limited
Meer dan 6 berichten in een minuut vanaf dit X-account, of 150 in een uur voor de eigenaar.
429assistant_daily_limit
Vandaag, in UTC, al 100 berichten vanaf dit X-account.
502upstream_unavailable
Julien AI is niet beschikbaar of kon niet antwoorden. Een bericht dat hij ontving, blijft in de chat staan.

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

Response200

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

Een antwoord ophalen

GET/v1/assistant/replies/:reply_idScope readMCPask_julien_ai

Geeft een antwoord terug. Zolang het running is, haal je het om de paar seconden op. Het eindigt als completed met het antwoord van Julien AI, of als failed met de error.

Padparameters

reply_idstringVerplicht
De ID van het antwoord.

Resultaat

Een assistentantwoord-object.

Fouten

404resource_missing
Geen antwoord met deze ID op het X-account van de sleutel.

GET/v1/assistant/replies/:reply_id

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

Response200

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

Het assistentbericht-object

Een bericht uit een chat met Julien AI, van jou of van Julien AI zelf.

Attributen

idstring
Unieke ID van het bericht.
objectstring
Altijd assistant_message.
chat_idstring
De chat waar het bij hoort.
rolestring
user voor jouw berichten, assistant voor die van Julien AI.
userassistant
textstring
Het bericht. Bij Julien AI het antwoord, gevolgd door de vraag die hij je stelt, als hij er een stelt.
created_atstring
Wanneer het bericht is verstuurd, in ISO 8601.

Het assistentbericht-object

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

Berichten opvragen

GET/v1/assistant/messagesScope read

Geeft de berichten terug van je chats met Julien AI die via de API zijn gemaakt, je eigen berichten en zijn antwoorden, nieuwste eerst.

Queryparameters

chat_idstring
Alleen de berichten van deze chat. Standaard alle chats van dit X-account.
limitinteger
Hoeveel objecten je terugkrijgt, van 1 tot 100. Standaard 25.
cursorstring
De next_cursor van de vorige pagina, om de pagina daarna op te halen. Zie Paginering.

Resultaat

Een lijst van assistentbericht-objecten.

Fouten

404resource_missing
Geen chat met deze ID die via de API met dit X-account is gemaakt. Voor de eigen chats van de app krijg je hetzelfde antwoord.
400parameter_invalid
Een parameter heeft een waarde die de API niet accepteert. param geeft aan welke.

GET/v1/assistant/messages

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

Response200

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

Het assistentchat-object

Een chat met Julien AI die via de API is gestart.

Attributen

idstring
Unieke ID van de chat, de chat_id van de berichten erin.
objectstring
Altijd assistant_chat.
titlestring
De titel van de chat, zoals de app chats een titel geeft. New chat zolang er nog geen titel is.
created_atstring
Wanneer de chat begon, in ISO 8601.
last_message_atstring
Wanneer het laatste bericht is verstuurd, in ISO 8601.
last_message_previewstring
Het begin van het laatste bericht.

Het assistentchat-object

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

Chats opvragen

GET/v1/assistant/chatsScope read

Geeft je chats met Julien AI terug die via de API met dit X-account zijn gemaakt, de laatst actieve eerst.

Queryparameters

limitinteger
Hoeveel objecten je terugkrijgt, van 1 tot 100. Standaard 25.
cursorstring
De next_cursor van de vorige pagina, om de pagina daarna op te halen. Zie Paginering.

Resultaat

Een lijst van assistentchat-objecten.

Fouten

400parameter_invalid
Een parameter heeft een waarde die de API niet accepteert. param geeft aan welke.

GET/v1/assistant/chats

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

Response200

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