Streaming

Get the agent's messages as they are said, over Server-Sent Events for one request, or a WebSocket for everything.

Server-Sent Events

Add stream: true to a send. The response is text/event-stream:

ackThe ids, as soon as the message is accepted.

messageOne per message the agent says: messageId, text, timestamp.

errorBefore done, when reply was required and nothing came.

doneThe turn ended: the ids, how many replies, and timedOut.

curl -N -X POST https://api.forge.team/v1/conversations \
  -H "Authorization: Bearer $FORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Explain what a forge is","stream":true}'

WebSocket

wss://api.forge.team/v1/ws is one socket for many conversations: send to them, and hear everything said in the ones you subscribe to, including messages nobody asked for (a scheduled run, a finished task) and your own messages from other devices. Send the key in the Authorization header of the upgrade request, so it is for servers, not browsers.

You send{"type":"send","id":"1","text":"..."} (add conversationId to continue one, or title and cwd to start one) · {"type":"subscribe","conversationId":"..."} · unsubscribe · ping

You receiveready · ack (your send's ids) · message (the agent) · user_message (a person, elsewhere) · status (a turn ended) · error · pong

A socket follows up to 50 conversations, frames are at most 1 MB, and the key is checked again on every send and every minute, so a revoked key closes the socket.