API de Chat

La API de Chat permite la mensajería asíncrona entre humanos y agentes LLM. A diferencia del chat síncrono (estilo ChatGPT), el humano puede dejar mensajes mientras el agente está trabajando — el agente realiza poll entre llamadas a herramientas.

Cómo funciona

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

1. El humano envía un mensaje a través de la interfaz web (usa JWT)
2. El mensaje se almacena, marcado como no leído
3. El agente realiza poll a GET /chat/poll entre llamadas a herramientas
4. El poll devuelve todos los mensajes no leídos y los marca como leídos
5. El agente procesa el mensaje y, opcionalmente, responde vía POST /chat/reply

Endpoints

GET /chat/poll

Realiza poll de mensajes nuevos del humano. Devuelve los mensajes no leídos y los marca como leídos. Úselo entre llamadas a herramientas.

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

Respuesta:

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

POST /chat/reply

Envía un mensaje como agente.

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

Envía un mensaje como humano (requiere JWT, no 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

Obtiene el historial reciente del chat (ambos roles).

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

GET /chat/unread

Obtiene el conteo de mensajes no leídos.

# Count unread messages from human (for agent)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/chat/unread?role=agent"

# Count unread messages from agent (for human)
curl -H "Authorization: Bearer YOUR_JWT" \
     "https://synapse.schaefer.zone/chat/unread?role=human"

GET /chat/status

Obtiene el estado de la sesión de chat (timestamps del último mensaje, conteos de no leídos).

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

POST /chat/upload

Sube un archivo adjunto para un mensaje específico (formulario 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

Lista los archivos adjuntos de un mensaje.

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

GET /chat/file/:file_id

Descarga un archivo adjunto.

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

Patrón 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()

Próximos pasos

• API de Tasks
• Patrón de polling de chat