Conversations

Conversations provide a stateful way to interact with characters. Messages are persisted in the database, so you can retrieve the full history at any time. Conversations also support real-time streaming via WebSocket.

For a stateless, OpenAI-compatible approach, see Chat completions instead.

The Conversation object

{
  "id": "conv_AbCdEfGh12345678",
  "createdAt": "2026-01-15T12:00:00Z",
  "characterId": "character_PuTlWmWuynYZu8sP"
}

The Message object

{
  "id": "msg_AbCdEfGh12345678",
  "conversationId": "conv_AbCdEfGh12345678",
  "role": "player",
  "content": "Hello! Where should I go first?",
  "createdAt": "2026-01-15T12:00:01Z"
}

Field	Type	Description
role	string	"player" or "character"
content	string	Message text

Create a conversation

POST /conversations

Request body

Field	Type	Required	Description
characterId	string	Yes	Character to converse with

curl

curl -X POST https://api.mindforge.ai/conversations \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "characterId": "character_PuTlWmWuynYZu8sP" }'

Get a conversation

GET /conversations/{conversationId}

Returns the conversation with its full message history.

{
  "id": "conv_AbCdEfGh12345678",
  "createdAt": "2026-01-15T12:00:00Z",
  "characterId": "character_PuTlWmWuynYZu8sP",
  "messages": [
    { "id": "msg_1", "role": "player", "content": "Hello!", "createdAt": "..." },
    { "id": "msg_2", "role": "character", "content": "Welcome, traveler!", "createdAt": "..." }
  ]
}

Send a message

POST /conversations/{conversationId}/messages

Sends a message and returns the character's response. Messages are persisted automatically.

Request body

Field	Type	Required	Description
content	string	Yes	The player's message

curl

curl -X POST https://api.mindforge.ai/conversations/conv_AbCdEfGh12345678/messages \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Where should I go first?" }'

Response

{
  "playerMessage": {
    "id": "msg_abc123",
    "conversationId": "conv_AbCdEfGh12345678",
    "role": "player",
    "content": "Where should I go first?",
    "createdAt": "2026-01-15T12:00:01Z"
  },
  "characterMessage": {
    "id": "msg_def456",
    "conversationId": "conv_AbCdEfGh12345678",
    "role": "character",
    "content": "I'd recommend starting at the market square. There's a merchant there who might have something useful for your journey.",
    "createdAt": "2026-01-15T12:00:02Z"
  }
}

WebSocket streaming

GET /conversations/{conversationId}/ws?token=YOUR_API_KEY

Connect via WebSocket for real-time streaming responses.

Client messages

{ "content": "Hello!", "mode": "conversation" }

Field	Type	Description
content	string	The player's message
mode	string	"conversation" (default) or "analysis"

Server messages

Ready — sent when the connection is established:

{ "type": "ready" }

Chunk — streamed text fragments:

{ "type": "chunk", "characterId": "character_abc", "content": "Hello", "done": false }

Capability — tool call from the character:

{ "type": "capability", "characterId": "character_abc", "name": "goToLocation", "params": { "x": 100, "z": 200 } }

Error:

{ "type": "error", "message": "Something went wrong" }