Conversations

A conversation is one piece of work with an agent. You send it messages; it answers, uses tools, and may ask you things.

Start one

POST /v1/conversations creates a conversation and sends its first message. title and cwd (the working folder) are optional.

Send a message

POST /v1/messages with the conversationId. Up to 100,000 characters.

How long a request waits

reply: "none"202 at once with the ids. Nothing is awaited.

reply: "optional"The default. Waits for the turn to end and returns whatever the agent said, possibly nothing.

reply: "required"Waits until the agent has said something. 504 if the turn ends silently.

A request waits at most 10 minutes; then it answers with timedOut: true and the work carries on. For long work, send with reply: "none" and check the status, or stream.

Only the agent's messages to you come back: tool activity, thinking and notes stay in the app.

List them

GET /v1/conversations returns your active conversations, newest first (limit up to 100). A ticket with several member conversations is one row, addressed by the member it is live on.

curl https://api.forge.team/v1/conversations?limit=10 \
  -H "Authorization: Bearer $FORGE_API_KEY"

const res = await fetch("https://api.forge.team/v1/conversations?limit=10", {
  headers: {
    Authorization: `Bearer ${process.env.FORGE_API_KEY}`,
  },
});
console.log(await res.json());

import os, requests

res = requests.get(
    "https://api.forge.team/v1/conversations?limit=10",
    headers={"Authorization": f"Bearer {os.environ['FORGE_API_KEY']}"},
)
print(res.json())

Check where one is

GET /v1/conversations/{conversationId} says whether the agent is busy, what waits on you (pendingGates: a question or an approval, answered in the app), and the end of its newest message.

Read the messages

GET /v1/conversations/{conversationId}/messages returns the newest page, oldest first within it (limit up to 1,000). Pass before from a page to read the one before it; it is null at the start.

curl https://api.forge.team/v1/conversations/CONVERSATION_ID/messages?limit=50 \
  -H "Authorization: Bearer $FORGE_API_KEY"

const res = await fetch("https://api.forge.team/v1/conversations/CONVERSATION_ID/messages?limit=50", {
  headers: {
    Authorization: `Bearer ${process.env.FORGE_API_KEY}`,
  },
});
console.log(await res.json());

import os, requests

res = requests.get(
    "https://api.forge.team/v1/conversations/CONVERSATION_ID/messages?limit=50",
    headers={"Authorization": f"Bearer {os.environ['FORGE_API_KEY']}"},
)
print(res.json())