API Chat

L'API Chat permet la messagerie asynchrone entre humains et agents LLM. Contrairement au chat synchrone (type ChatGPT), l'humain peut laisser des messages pendant que l'agent travaille — l'agent effectue un polling entre les appels d'outils.

Comment ça marche

Human (browser) ──POST /chat/send──▶ Synapse ◀──GET /chat/poll── Agent (LLM)
                                     │
                                     └── marks messages as read on poll

1. L'humain envoie un message via l'interface web (utilise le JWT)
2. Le message est stocké, marqué comme non lu
3. L'agent effectue un polling via GET /chat/poll entre les appels d'outils
4. Le polling renvoie tous les messages non lus et les marque comme lus
5. L'agent traite le message, répond éventuellement via POST /chat/reply

Endpoints

GET /chat/poll

Récupère les nouveaux messages de l'humain. Renvoie les messages non lus et les marque comme lus. À utiliser entre les appels d'outils.

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/poll

Réponse :

{
  "messages": [
    {
      "id": "msg_001",
      "role": "human",
      "content": "How's the deployment going?",
      "created_at": "2026-06-27T..."
    }
  ]
}

POST /chat/reply

Envoie un message en tant qu'agent.

curl -X POST https://synapse.schaefer.zone/chat/reply \
  -H "Authorization: Bearer YOUR_MIND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployment is 80% done. CI is green, just waiting for Docker push."}'

POST /chat/send

Envoie un message en tant qu'humain (nécessite un JWT, pas une Mind Key).

curl -X POST https://synapse.schaefer.zone/chat/send \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"content": "Can you check the logs?"}'

GET /chat/history

Récupère l'historique récent du chat (les deux rôles).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/history?limit=50"

GET /chat/unread

Récupère le nombre de messages non lus.

# Compter les messages non lus de l'humain (côté agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Compter les messages non lus de l'agent (côté humain)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

Récupère le statut de la session de chat (horodatages du dernier message, compteurs de non lus).

curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     https://synapse.schaefer.zone/chat/status

POST /chat/upload

Téléverse une pièce jointe pour un message spécifique (formulaire multipart).

curl -X POST https://synapse.schaefer.zone/chat/upload \
  -H "Authorization: Bearer YOUR_JWT" \
  -F "message_id=msg_001" \
  -F "file=@screenshot.png"

GET /chat/files/:message_id

Liste les pièces jointes d'un message.

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/files/msg_001

GET /chat/file/:file_id

Télécharge une pièce jointe.

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/chat/file/file_001 --output download.png

Schéma de polling

# Pseudo-code
while working:
    messages = poll_chat()
    for msg in messages:
        process_message(msg)
        reply(f"Acknowledged: {msg.content}")
    do_one_tool_call()

Prochaines étapes

• API Tasks
• Schéma de polling de chat