API reference

Julien AI

Julien AI is the assistant of the Gemlead app. Through the API it answers questions about Gemlead and about the key's X account, its leads, personas, campaigns and conversations. It only answers, and never creates, changes or sends anything.

Send a message without chat_id to start a chat, then send the next ones with the reply's chat_id to go on in it. You reach the chats made through the API with this X account, never the chats of the app.

A send waits up to 25 seconds for the answer. When Julien AI needs longer, the reply comes back with the status running. Retrieve it every few seconds until it is completed or failed, which takes 150 seconds at most.

Each X account can send 6 messages a minute and 100 a day in UTC, one at a time in a chat and 3 at once, each of 1 to 4 000 characters. Julien AI also takes 150 messages an hour per user, the app's chat and the API together.

Endpoints

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

The assistant reply object

One message to Julien AI and its answer. A send returns it, and it stays readable by its ID.

Attributes

idstring
Unique identifier for the reply, rpl_ and 32 characters.
objectstring
Always assistant_reply.
statusstring
running while Julien AI writes, then completed or failed.
runningcompletedfailed
chat_idstring or null
The chat of the message. Send the next message with it to go on in the same chat. null while the first message of a new chat runs.
messageobject or null
Your message as the chat keeps it, an assistant message object. null until the status is completed.
replyobject or null
Julien AI's answer, an assistant message object. null until the status is completed.
errorobject or null
Why the reply failed, null otherwise.
created_atstring
When the message was sent, ISO 8601.
completed_atstring or null
When the reply ended, completed or failed, ISO 8601. null while it runs.

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

Send a message

POST/v1/assistant/messageswrite scopeMCPask_julien_ai

Sends a message to Julien AI and waits up to 25 seconds for its answer. Past that, the reply comes back running and you retrieve it until it ends. Send it with an Idempotency-Key so a retry never asks twice.

Body parameters

textstringRequired
Your message, 1 to 4 000 characters.
chat_idstring
The chat to go on in, from an earlier reply. Without it, the message starts a new chat.

Returns

An assistant reply object, completed with the answer, or running when Julien AI needs more than 25 seconds.

Errors

400parameter_missing
A required parameter is missing. param names it.
400parameter_invalid
The text is empty or longer than 4 000 characters. param names it.
404resource_missing
No chat with this ID made through the API with this X account. The app's own chats answer the same.
409assistant_busy
Julien AI is still answering a message of this chat, or 3 messages of this X account.
429assistant_rate_limited
More than 6 messages in the minute from this X account, or 150 in the hour for its owner.
429assistant_daily_limit
100 messages today in UTC from this X account.
502upstream_unavailable
Julien AI is not available or could not answer. A message it received stays in the 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?"
  }'

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

Retrieve a reply

GET/v1/assistant/replies/:reply_idread scopeMCPask_julien_ai

Returns a reply. While it is running, retrieve it every few seconds. It ends completed with Julien AI's answer, or failed with its error.

Path parameters

reply_idstringRequired
The reply's ID.

Returns

An assistant reply object.

Errors

404resource_missing
No reply with this ID on the key's X account.

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
}

The assistant message object

A message of a chat with Julien AI, yours or its own.

Attributes

idstring
Unique identifier for the message.
objectstring
Always assistant_message.
chat_idstring
The chat it belongs to.
rolestring
user for your messages, assistant for Julien AI's.
userassistant
textstring
The message. From Julien AI, its answer, then the question it asks you when it asks one.
created_atstring
When the message was sent, ISO 8601.

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

List messages

GET/v1/assistant/messagesread scope

Returns the messages of your chats with Julien AI made through the API, yours and its answers, newest first.

Query parameters

chat_idstring
Only this chat's messages. Default every chat of this X account.
limitinteger
How many objects to return, from 1 to 100. Defaults to 25.
cursorstring
The next_cursor of the previous page, to get the page after it. See Pagination.

Returns

A list of assistant message objects.

Errors

404resource_missing
No chat with this ID made through the API with this X account. The app's own chats answer the same.
400parameter_invalid
A parameter has a value the API does not accept. param names it.

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
}

The assistant chat object

A chat with Julien AI started through the API.

Attributes

idstring
Unique identifier for the chat, the chat_id of its messages.
objectstring
Always assistant_chat.
titlestring
The chat's title, as the app names its chats. New chat until it has one.
created_atstring
When the chat started, ISO 8601.
last_message_atstring
When its last message was sent, ISO 8601.
last_message_previewstring
The start of its last message.

Assistant chat 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."
}

List chats

GET/v1/assistant/chatsread scope

Returns your chats with Julien AI made through the API with this X account, the latest active first.

Query parameters

limitinteger
How many objects to return, from 1 to 100. Defaults to 25.
cursorstring
The next_cursor of the previous page, to get the page after it. See Pagination.

Returns

A list of assistant chat objects.

Errors

400parameter_invalid
A parameter has a value the API does not accept. param names it.

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
}