API-Referenz

Julien AI

Julien AI ist der Assistent der Gemlead-App. Über die API beantwortet er Fragen zu Gemlead und zum X-Konto des Schlüssels, seinen Leads, Personas, Kampagnen und Unterhaltungen. Er antwortet nur und erstellt, ändert oder sendet nie etwas.

Sende eine Nachricht ohne chat_id, um einen Chat zu starten, und die nächsten dann mit der chat_id der Antwort, um darin weiterzumachen. Du hast Zugriff auf die Chats, die über die API mit diesem X-Konto entstanden sind, nie auf die Chats der App.

Beim Senden wartet die Anfrage bis zu 25 Sekunden auf die Antwort. Braucht Julien AI länger, kommt die Antwort mit dem Status running zurück. Rufe sie alle paar Sekunden ab, bis sie completed oder failed ist, was höchstens 150 Sekunden dauert.

Jedes X-Konto kann 6 Nachrichten pro Minute und 100 pro UTC-Tag senden, in einem Chat eine nach der anderen und insgesamt 3 gleichzeitig, jede mit 1 bis 4 000 Zeichen. Julien AI nimmt außerdem höchstens 150 Nachrichten pro Stunde und Nutzer an, Chat in der App und API zusammen.

Endpoints

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

Das Antwortobjekt

Eine Nachricht an Julien AI und seine Antwort. Der Sendeaufruf gibt sie zurück, und sie bleibt über ihre ID lesbar.

Attribute

idstring
Eindeutige Kennung der Antwort, rpl_ und 32 Zeichen.
objectstring
Immer assistant_reply.
statusstring
running, solange Julien AI schreibt, dann completed oder failed.
runningcompletedfailed
chat_idstring oder null
Der Chat der Nachricht. Sende die nächste Nachricht damit, um im selben Chat weiterzumachen. null, solange die erste Nachricht eines neuen Chats läuft.
messageobject oder null
Deine Nachricht, so wie der Chat sie speichert, ein Nachrichtenobjekt. null, bis der Status completed ist.
replyobject oder null
Die Antwort von Julien AI, ein Nachrichtenobjekt. null, bis der Status completed ist.
errorobject oder null
Warum die Antwort fehlgeschlagen ist, sonst null.
created_atstring
Wann die Nachricht gesendet wurde, ISO 8601.
completed_atstring oder null
Wann die Antwort endete, abgeschlossen oder fehlgeschlagen, ISO 8601. null, solange sie läuft.

Das Antwortobjekt

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

Nachricht senden

POST/v1/assistant/messagesScope writeMCPask_julien_ai

Sendet eine Nachricht an Julien AI und wartet bis zu 25 Sekunden auf die Antwort. Danach kommt die Antwort als running zurück, und du rufst sie ab, bis sie fertig ist. Sende sie mit einem Idempotency-Key, damit ein erneuter Versuch nie doppelt fragt.

Body-Parameter

textstringErforderlich
Deine Nachricht, 1 bis 4 000 Zeichen.
chat_idstring
Der Chat, in dem es weitergeht, aus einer früheren Antwort. Ohne ihn startet die Nachricht einen neuen Chat.

Rückgabe

Ein Antwortobjekt, completed mit der Antwort oder running, wenn Julien AI mehr als 25 Sekunden braucht.

Fehler

400parameter_missing
Ein Pflichtparameter fehlt. param nennt ihn.
400parameter_invalid
Der Text ist leer oder länger als 4 000 Zeichen. param nennt ihn.
404resource_missing
Kein Chat mit dieser ID, der über die API mit diesem X-Konto entstanden ist. Die Chats der App selbst ergeben dieselbe Antwort.
409assistant_busy
Julien AI beantwortet noch eine Nachricht dieses Chats oder 3 Nachrichten dieses X-Kontos.
429assistant_rate_limited
Mehr als 6 Nachrichten pro Minute von diesem X-Konto, oder 150 pro Stunde für seinen Inhaber.
429assistant_daily_limit
Dieses X-Konto hat an diesem UTC-Tag schon 100 Nachrichten gesendet.
502upstream_unavailable
Julien AI ist nicht verfügbar oder konnte nicht antworten. Eine Nachricht, die er erhalten hat, bleibt im 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?"
  }'

Antwort200

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

Antwort abrufen

GET/v1/assistant/replies/:reply_idScope readMCPask_julien_ai

Gibt eine Antwort zurück. Solange sie running ist, rufe sie alle paar Sekunden ab. Sie endet als completed mit der Antwort von Julien AI oder als failed mit ihrem error.

Pfadparameter

reply_idstringErforderlich
Die ID der Antwort.

Rückgabe

Ein Antwortobjekt.

Fehler

404resource_missing
Keine Antwort mit dieser ID im X-Konto des Schlüssels.

GET/v1/assistant/replies/:reply_id

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

Antwort200

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

Das Nachrichtenobjekt

Eine Nachricht aus einem Chat mit Julien AI, von dir oder von ihm.

Attribute

idstring
Eindeutige Kennung der Nachricht.
objectstring
Immer assistant_message.
chat_idstring
Der Chat, zu dem sie gehört.
rolestring
user für deine Nachrichten, assistant für die von Julien AI.
userassistant
textstring
Die Nachricht. Bei Julien AI seine Antwort, danach die Frage an dich, wenn er eine stellt.
created_atstring
Wann die Nachricht gesendet wurde, ISO 8601.

Das Nachrichtenobjekt

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

Nachrichten auflisten

GET/v1/assistant/messagesScope read

Gibt die Nachrichten deiner Chats mit Julien AI zurück, die über die API entstanden sind, deine und seine Antworten, die neuesten zuerst.

Query-Parameter

chat_idstring
Nur die Nachrichten dieses Chats. Standardmäßig alle Chats dieses X-Kontos.
limitinteger
Wie viele Objekte zurückgegeben werden, von 1 bis 100. Standardmäßig 25.
cursorstring
Der next_cursor der vorherigen Seite, um die nächste Seite abzurufen. Siehe Paginierung.

Rückgabe

Eine Liste von Nachrichtenobjekten.

Fehler

404resource_missing
Kein Chat mit dieser ID, der über die API mit diesem X-Konto entstanden ist. Die Chats der App selbst ergeben dieselbe Antwort.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

GET/v1/assistant/messages

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

Antwort200

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

Das Chatobjekt

Ein Chat mit Julien AI, der über die API gestartet wurde.

Attribute

idstring
Eindeutige Kennung des Chats, die chat_id seiner Nachrichten.
objectstring
Immer assistant_chat.
titlestring
Der Titel des Chats, so wie die App ihre Chats benennt. New chat, bis er einen hat.
created_atstring
Wann der Chat begann, ISO 8601.
last_message_atstring
Wann seine letzte Nachricht gesendet wurde, ISO 8601.
last_message_previewstring
Der Anfang seiner letzten Nachricht.

Das Chatobjekt

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

GET/v1/assistant/chatsScope read

Gibt deine Chats mit Julien AI zurück, die über die API mit diesem X-Konto entstanden sind, die zuletzt aktiven zuerst.

Query-Parameter

limitinteger
Wie viele Objekte zurückgegeben werden, von 1 bis 100. Standardmäßig 25.
cursorstring
Der next_cursor der vorherigen Seite, um die nächste Seite abzurufen. Siehe Paginierung.

Rückgabe

Eine Liste von Chatobjekten.

Fehler

400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

GET/v1/assistant/chats

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

Antwort200

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