Chat
6 Chat routes on the FLAM API: One turn of the loop; Undo, redo, and any direct edit; Prepare private chat context.
Base URL https://api-staging.flam.fashion. Send Authorization: Bearer flam_sk_… on every call; a handful of routes are session-only and say so. How keys and roles work.
POST /api/chat
One turn of the loop
The house reads the message against the current draft and answers with what it said plus the mutations it applied. Every applied mutation is ALSO pushed over the job socket the moment it lands (turnId is echoed so the tab that asked does not render it twice, and sessionId keeps another open topic from receiving it). Free — a turn never spends tokens.
Request body — application/json (required)
| Field | Type | Required | Notes |
|---|---|---|---|
message | string | yes | — |
draft | object | no | — |
history | object[] | no | — |
screen | string | no | — |
turnId | string | no | — |
sessionId | string | no | Existing conversation. Omit to create one atomically with the turn. |
{
"message": "string",
"draft": {},
"history": [
{
"role": "director",
"text": "string"
}
],
"screen": "string",
"turnId": "string",
"sessionId": "string"
}Responses
| Status | Meaning |
|---|---|
200 | The turn |
400 | BAD_BODY / BAD_MESSAGE / BAD_DRAFT |
401 | No valid session |
502 | AI_UNAVAILABLE |
503 | AI_NOT_CONFIGURED / AI_GATEWAY_NEEDS_BILLING |
200 returns:
{
"text": "string",
"applied": [
{}
],
"mirror": {},
"turnId": "string",
"sessionId": "string",
"persisted": true
}Call it
curl -X POST "https://api-staging.flam.fashion/api/chat" \
-H "Authorization: Bearer $FLAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"message":"string","draft":{},"history":[{"role":"director","text":"string"}],"screen":"string","turnId":"string","sessionId":"string"}'POST /api/chat/apply
Undo, redo, and any direct edit
ONE door for both directions of the walk — undo posts the inverse, redo posts the mutation. Free by definition: a mutation never spends. A selection can only ever name pieces this house holds.
Request body — application/json (required)
| Field | Type | Required | Notes |
|---|---|---|---|
draft | object | no | — |
mutation | object | yes | — |
{
"draft": {},
"mutation": {}
}Responses
| Status | Meaning |
|---|---|
200 | The new draft |
400 | BAD_BODY / BAD_DRAFT / BAD_MUTATION |
401 | No valid session |
404 | ASSET_NOT_FOUND |
422 | CANNOT_APPLY { reason } |
200 returns:
{
"draft": {},
"applied": {}
}Call it
curl -X POST "https://api-staging.flam.fashion/api/chat/apply" \
-H "Authorization: Bearer $FLAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"draft":{},"mutation":{}}'POST /api/chat/context/warm
Prepare private chat context
Starts a background refresh of the signed-in person's house and personal memory. It returns immediately and never exposes the cached memory to the browser.
Responses
| Status | Meaning |
|---|---|
202 | The background refresh started. |
401 | No signed-in person. |
202 returns:
{
"warming": true
}Call it
curl -X POST "https://api-staging.flam.fashion/api/chat/context/warm" \
-H "Authorization: Bearer $FLAM_API_KEY"GET /api/chat/sessions
List this director's recent conversations
Newest first, scoped to both the active house and actor.
Responses
| Status | Meaning |
|---|---|
200 | Recent open conversations |
401 | No valid session |
200 returns:
{
"sessions": [
{
"id": "string",
"title": "string",
"createdAt": "2026-07-27T09:00:00.000Z",
"lastTurnAt": "2026-07-27T09:00:00.000Z"
}
]
}Call it
curl -X GET "https://api-staging.flam.fashion/api/chat/sessions" \
-H "Authorization: Bearer $FLAM_API_KEY"POST /api/chat/sessions
Start a new conversation
Creates an empty actor-visible working context in the active house.
Request body — application/json
| Field | Type | Required | Notes |
|---|---|---|---|
title | string | no | — |
{
"title": "string"
}Responses
| Status | Meaning |
|---|---|
201 | The new conversation |
401 | No valid session |
201 returns:
{
"session": {
"id": "string",
"title": "string",
"createdAt": "2026-07-27T09:00:00.000Z",
"lastTurnAt": "2026-07-27T09:00:00.000Z"
}
}Call it
curl -X POST "https://api-staging.flam.fashion/api/chat/sessions" \
-H "Authorization: Bearer $FLAM_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"string"}'GET /api/chat/sessions/{id}/turns
Restore one conversation
Returns at most 200 exact UI turns, oldest first.
Parameters
| In | Name | Type | Required | Notes |
|---|---|---|---|---|
| path | id | string | yes | — |
Responses
| Status | Meaning |
|---|---|
200 | The persisted transcript |
401 | No valid session |
404 | CHAT_SESSION_NOT_FOUND |
200 returns:
{
"turns": [
{}
]
}Call it
curl -X GET "https://api-staging.flam.fashion/api/chat/sessions/{id}/turns" \
-H "Authorization: Bearer $FLAM_API_KEY"