Referência da API

Julien AI

O Julien AI é o assistente do app Gemlead. Pela API, ele responde perguntas sobre o Gemlead e sobre a conta do X da chave, com os leads, as personas, as campanhas e as conversas dela. Ele só responde e nunca cria, altera ou envia nada.

Envie uma mensagem sem chat_id para começar um chat e depois envie as próximas com o chat_id da resposta para continuar nele. Você acessa os chats criados pela API com esta conta do X, nunca os chats do app.

Um envio espera até 25 segundos pela resposta. Quando o Julien AI precisa de mais tempo, a resposta volta com o status running. Consulte de novo a cada poucos segundos até ela ficar completed ou failed, o que leva no máximo 150 segundos.

Cada conta do X pode enviar 6 mensagens por minuto e 100 por dia em UTC, uma por vez num chat e 3 ao mesmo tempo, cada uma com 1 a 4 000 caracteres. O Julien AI também aceita 150 mensagens por hora por usuário, somando o chat do app e a API.

Endpoints

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

O objeto assistant reply

Uma mensagem ao Julien AI e a resposta dele. Um envio retorna esse objeto, e ele continua disponível para leitura pelo ID.

Atributos

idstring
Identificador único da resposta, rpl_ seguido de 32 caracteres.
objectstring
Sempre assistant_reply.
statusstring
running enquanto o Julien AI escreve, depois completed ou failed.
runningcompletedfailed
chat_idstring ou null
O chat da mensagem. Envie a próxima mensagem com ele para continuar no mesmo chat. null enquanto a primeira mensagem de um novo chat está em processamento.
messageobject ou null
A sua mensagem como o chat a guarda, um objeto assistant message. null até o status ser completed.
replyobject ou null
A resposta do Julien AI, um objeto assistant message. null até o status ser completed.
errorobject ou null
O motivo da falha da resposta, senão null.
created_atstring
Quando a mensagem foi enviada, em ISO 8601.
completed_atstring ou null
Quando a resposta terminou, concluída ou com falha, em ISO 8601. null enquanto ela está em andamento.

O objeto assistant reply

{
  "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 uma mensagem

POST/v1/assistant/messagesScope writeMCPask_julien_ai

Envia uma mensagem ao Julien AI e espera até 25 segundos pela resposta. Depois disso, a resposta volta como running e você a consulta de novo até ela terminar. Envie com uma Idempotency-Key para que uma nova tentativa nunca envie a pergunta duas vezes.

Parâmetros do corpo

textstringObrigatório
A sua mensagem, de 1 a 4 000 caracteres.
chat_idstring
O chat em que continuar, vindo de uma resposta anterior. Sem ele, a mensagem começa um novo chat.

Retorno

Um objeto assistant reply, completed com a resposta, ou running quando o Julien AI precisa de mais de 25 segundos.

Erros

400parameter_missing
Falta um parâmetro obrigatório. param diz qual.
400parameter_invalid
O texto está vazio ou tem mais de 4 000 caracteres. param diz qual.
404resource_missing
Nenhum chat com este ID criado pela API com esta conta do X. Os chats do próprio app recebem a mesma resposta.
409assistant_busy
O Julien AI ainda está respondendo a uma mensagem deste chat, ou a 3 mensagens desta conta do X.
429assistant_rate_limited
Mais de 6 mensagens no minuto a partir desta conta do X, ou 150 na hora para o dono dela.
429assistant_daily_limit
100 mensagens hoje em UTC a partir desta conta do X.
502upstream_unavailable
O Julien AI está indisponível ou não conseguiu responder. Uma mensagem que ele recebeu continua no 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?"
  }'

Resposta200

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

Obter uma resposta

GET/v1/assistant/replies/:reply_idScope readMCPask_julien_ai

Retorna uma resposta. Enquanto ela estiver running, consulte de novo a cada poucos segundos. Ela termina completed com a resposta do Julien AI, ou failed com o error.

Parâmetros de caminho

reply_idstringObrigatório
O ID da resposta.

Retorno

Um objeto assistant reply.

Erros

404resource_missing
Nenhuma resposta com este ID na conta do X da chave.

GET/v1/assistant/replies/:reply_id

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

Resposta200

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

O objeto assistant message

Uma mensagem de um chat com o Julien AI, sua ou dele.

Atributos

idstring
Identificador único da mensagem.
objectstring
Sempre assistant_message.
chat_idstring
O chat a que ela pertence.
rolestring
user para as suas mensagens, assistant para as do Julien AI.
userassistant
textstring
A mensagem. Vinda do Julien AI, a resposta dele e depois a pergunta que ele faz a você, quando faz uma.
created_atstring
Quando a mensagem foi enviada, em ISO 8601.

O objeto assistant message

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

GET/v1/assistant/messagesScope read

Retorna as mensagens dos seus chats com o Julien AI criados pela API, as suas e as respostas dele, das mais novas para as mais antigas.

Parâmetros de consulta

chat_idstring
Só as mensagens deste chat. O padrão são todos os chats desta conta do X.
limitinteger
Quantos objetos retornar, de 1 a 100. O padrão é 25.
cursorstring
O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos assistant message.

Erros

404resource_missing
Nenhum chat com este ID criado pela API com esta conta do X. Os chats do próprio app recebem a mesma resposta.
400parameter_invalid
Um parâmetro tem um valor que a API não aceita. param diz qual.

GET/v1/assistant/messages

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

Resposta200

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

O objeto assistant chat

Um chat com o Julien AI iniciado pela API.

Atributos

idstring
Identificador único do chat, o chat_id das mensagens dele.
objectstring
Sempre assistant_chat.
titlestring
O título do chat, no mesmo formato que o app usa. New chat até ele ganhar um.
created_atstring
Quando o chat começou, em ISO 8601.
last_message_atstring
Quando a última mensagem dele foi enviada, em ISO 8601.
last_message_previewstring
O começo da última mensagem dele.

O objeto assistant chat

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

GET/v1/assistant/chatsScope read

Retorna seus chats com o Julien AI criados pela API com esta conta do X, começando pelo que teve atividade mais recente.

Parâmetros de consulta

limitinteger
Quantos objetos retornar, de 1 a 100. O padrão é 25.
cursorstring
O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos assistant chat.

Erros

400parameter_invalid
Um parâmetro tem um valor que a API não aceita. param diz qual.

GET/v1/assistant/chats

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

Resposta200

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