Getting started
Start a conversation with a Forge agent, read its reply, and keep going, in three requests.
1. Make a key
Sign in, then open Settings > Account > API access and create a key. It starts with fg_ and is shown once. Keep it in an environment variable:
export FORGE_API_KEY=fg_...2. Start a conversation
reply: "required" waits until the agent has answered.
curl -X POST https://api.forge.team/v1/conversations \
-H "Authorization: Bearer $FORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"Write a haiku about a forge","reply":"required"}'const res = await fetch("https://api.forge.team/v1/conversations", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FORGE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"text": "Write a haiku about a forge",
"reply": "required"
}),
});
console.log(await res.json());import os, requests
res = requests.post(
"https://api.forge.team/v1/conversations",
headers={"Authorization": f"Bearer {os.environ['FORGE_API_KEY']}"},
json={
"text": "Write a haiku about a forge",
"reply": "required"
},
)
print(res.json()){
"conversationId": "3f2c9a1e-...",
"messageId": "8d41...",
"replies": [
{
"messageId": "b7e0...",
"text": "Hammer meets the glow...",
"timestamp": "2026-10-16T09:30:12.004Z"
}
]
}3. Keep going
Send the next message to the same conversationId.
curl -X POST https://api.forge.team/v1/messages \
-H "Authorization: Bearer $FORGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"conversationId":"CONVERSATION_ID","text":"Now make it rhyme","reply":"required"}'const res = await fetch("https://api.forge.team/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FORGE_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"conversationId": "CONVERSATION_ID",
"text": "Now make it rhyme",
"reply": "required"
}),
});
console.log(await res.json());import os, requests
res = requests.post(
"https://api.forge.team/v1/messages",
headers={"Authorization": f"Bearer {os.environ['FORGE_API_KEY']}"},
json={
"conversationId": "CONVERSATION_ID",
"text": "Now make it rhyme",
"reply": "required"
},
)
print(res.json())Every conversation you start here is yours in the app too, under your account, and runs on your credits.
Next
- Conversations: reply modes, reading messages, status
- Streaming: replies as they are said, over SSE or a WebSocket
- Examples: small programs to copy
- Reference: every route, and Try it with your key