Referencia de la API
Julien AI
Julien AI es el asistente de la app Gemlead. A través de la API responde preguntas sobre Gemlead y sobre la cuenta de X de la clave, sus leads, buyer personas, campañas y conversaciones. Solo responde, nunca crea, cambia ni envía nada.
Envía un mensaje sin chat_id para empezar un chat y luego envía los siguientes con el chat_id de la respuesta para continuarlo. Solo ves los chats creados por la API con esta cuenta de X, nunca los de la app.
Un envío espera la respuesta hasta 25 segundos. Si Julien AI necesita más tiempo, la respuesta vuelve con el estado running. Consúltala cada pocos segundos hasta que esté en completed o failed, lo que tarda 150 segundos como máximo.
Cada cuenta de X puede enviar 6 mensajes por minuto y 100 al día en UTC, uno a la vez por chat y 3 en paralelo, de 1 a 4 000 caracteres cada uno. Julien AI también acepta 150 mensajes por hora por usuario, sumando el chat de la app y la API.
El objeto assistant reply
Un mensaje a Julien AI y su respuesta. Un envío lo devuelve, y puedes volver a leerlo por su ID.
Atributos
- idstringIdentificador único de la respuesta,
rpl_seguido de 32 caracteres. - objectstringSiempre
assistant_reply. - statusstring
runningmientras Julien AI escribe, luegocompletedofailed.runningcompletedfailed - chat_idstring o nullEl chat del mensaje. Envía el siguiente mensaje con él para seguir en el mismo chat.
nullmientras se procesa el primer mensaje de un chat nuevo. - messageobject o nullTu mensaje tal como lo guarda el chat, un objeto assistant message.
nullhasta que el estado seacompleted. - replyobject o null
- errorobject o nullPor qué falló la respuesta, o
nullsi no falló. - created_atstringCuándo se envió el mensaje, en ISO 8601.
- completed_atstring o nullCuándo terminó la respuesta, completada o fallida, en ISO 8601.
nullmientras está en curso.
{
"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"
}Enviar un mensaje
Envía un mensaje a Julien AI y espera su respuesta hasta 25 segundos. Pasado ese tiempo, la respuesta vuelve en running y la consultas hasta que termine. Envíalo con una Idempotency-Key para que un reintento nunca pregunte dos veces.
Parámetros del cuerpo
- textstringObligatorioTu mensaje, de 1 a 4 000 caracteres.
- chat_idstringEl chat en el que continuar, tomado de una respuesta anterior. Sin él, el mensaje empieza un chat nuevo.
Devuelve
Un objeto assistant reply, en completed con la respuesta, o en running si Julien AI necesita más de 25 segundos.
Errores
- Falta un parámetro obligatorio.
paramlo indica. - El texto está vacío o tiene más de 4 000 caracteres.
paramlo indica. - No hay ningún chat con este ID creado por la API con esta cuenta de X. Los chats propios de la app dan la misma respuesta.
- Julien AI sigue respondiendo a un mensaje de este chat, o a 3 mensajes de esta cuenta de X.
- Más de 6 mensajes en un minuto desde esta cuenta de X, o 150 en una hora para su propietario.
- 100 mensajes hoy, en UTC, desde esta cuenta de X.
- Julien AI no está disponible o no pudo responder. Si recibió el mensaje, este se queda en el chat.
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?"
}'{
"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"
}Obtener una respuesta
Devuelve una respuesta. Mientras esté en running, consúltala cada pocos segundos. Termina en completed con la respuesta de Julien AI, o en failed con su error.
Parámetros de ruta
- reply_idstringObligatorioEl ID de la respuesta.
Devuelve
Errores
- No hay ninguna respuesta con este ID en la cuenta de X de la clave.
curl \
https://gemlead.ai/api/v1/assistant/replies/rpl_7Hq2LmX9vR4tKp8WzN3cYd6FbJ1sGa5E \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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
}El objeto assistant message
Un mensaje de un chat con Julien AI, tuyo o suyo.
Atributos
- idstringIdentificador único del mensaje.
- objectstringSiempre
assistant_message. - chat_idstringEl chat al que pertenece.
- rolestring
userpara tus mensajes,assistantpara los de Julien AI.userassistant - textstringEl mensaje. Si es de Julien AI, su respuesta y luego la pregunta que te hace, si te hace una.
- created_atstringCuándo se envió el mensaje, en ISO 8601.
{
"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"
}Listar mensajes
readDevuelve los mensajes de tus chats con Julien AI creados por la API, los tuyos y sus respuestas, primero los más recientes.
Parámetros de consulta
- chat_idstringSolo los mensajes de este chat. Por defecto, todos los chats de esta cuenta de X.
- limitintegerCuántos objetos devolver, de 1 a 100. 25 por defecto.
- cursorstringEl
next_cursorde la página anterior, para obtener la siguiente. Consulta Paginación.
Devuelve
Una lista de objetos assistant message.
Errores
- No hay ningún chat con este ID creado por la API con esta cuenta de X. Los chats propios de la app dan la misma respuesta.
- Un parámetro tiene un valor que la API no acepta.
paramlo indica.
curl -G https://gemlead.ai/api/v1/assistant/messages \
-H "Authorization: Bearer $GEMLEAD_API_KEY" \
-d chat_id=Jc7Rk2WqNb{
"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
}El objeto assistant chat
Un chat con Julien AI iniciado por la API.
Atributos
- idstringIdentificador único del chat, el
chat_idde sus mensajes. - objectstringSiempre
assistant_chat. - titlestringEl título del chat, como la app nombra sus chats.
New chathasta que tenga uno. - created_atstringCuándo empezó el chat, en ISO 8601.
- last_message_atstringCuándo se envió su último mensaje, en ISO 8601.
- last_message_previewstringEl principio de su último mensaje.
{
"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."
}Listar chats
readDevuelve tus chats con Julien AI creados por la API con esta cuenta de X, primero los de actividad más reciente.
Parámetros de consulta
- limitintegerCuántos objetos devolver, de 1 a 100. 25 por defecto.
- cursorstringEl
next_cursorde la página anterior, para obtener la siguiente. Consulta Paginación.
Devuelve
Una lista de objetos assistant chat.
Errores
- Un parámetro tiene un valor que la API no acepta.
paramlo indica.
curl https://gemlead.ai/api/v1/assistant/chats \
-H "Authorization: Bearer $GEMLEAD_API_KEY"{
"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
}