Chat completions

The chat completions endpoint is OpenAI-compatible. Use it directly or through any OpenAI SDK. See the OpenAI compatibility guide for setup instructions.

Create a chat completion

POST /v1/chat/completions

Request body

Field	Type	Required	Default	Description
model	string	Yes*	—	Character ID (e.g. character_PuTlWmWuynYZu8sP)
messages	array	Yes	—	Conversation messages
stream	boolean	No	true	Whether to stream the response
temperature	number	No	—	Sampling temperature (0–2)
max_tokens	number	No	—	Maximum tokens to generate
top_p	number	No	—	Nucleus sampling threshold
stop	string | string[]	No	—	Stop sequences

* The model field is a character ID. You can also pass character_id in the body for backwards compatibility.

Message format

{
  "messages": [
    { "role": "user", "content": "Hello!" },
    { "role": "assistant", "content": "Hi there! How can I help?" },
    { "role": "user", "content": "Tell me about the castle." }
  ]
}

Supported roles: user, assistant, tool. System messages are accepted but ignored — Mindforge builds its own system prompt from the character's configuration.

Non-streaming response

Set stream: false to get a single JSON response.

curl

curl https://api.mindforge.ai/v1/chat/completions \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "character_PuTlWmWuynYZu8sP",
    "messages": [{ "role": "user", "content": "Hello!" }],
    "stream": false
  }'

Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1714000000,
  "model": "character_PuTlWmWuynYZu8sP",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! Welcome to the kingdom. How can I help you today?",
        "refusal": null
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 14,
    "total_tokens": 39
  },
  "system_fingerprint": null
}

Streaming response

Streaming is the default. The response is a stream of server-sent events (SSE).

curl

curl https://api.mindforge.ai/v1/chat/completions \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "character_PuTlWmWuynYZu8sP",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

Stream format

Each event is a line starting with data: followed by a JSON chunk:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1714000000,"model":"my-assistant","choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1714000000,"model":"my-assistant","choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1714000000,"model":"my-assistant","choices":[{"index":0,"delta":{"content":"!"},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1714000000,"model":"my-assistant","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

data: [DONE]

• The first chunk includes delta.role: "assistant"
• Content chunks include delta.content with the text fragment
• The final chunk has an empty delta and finish_reason: "stop"
• The stream ends with data: [DONE]

Tool calls

If the character has capabilities attached, it may respond with tool calls instead of (or in addition to) text.

Non-streaming tool call

When tools are called, finish_reason is "tool_calls":

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Streaming tool call

Tool calls appear as delta.tool_calls in the stream:

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1714000000,"model":"my-assistant","choices":[{"index":0,"delta":{"tool_calls":[{"index":0,"id":"call_abc123","type":"function","function":{"name":"goToLocation","arguments":"{\"x\":100,\"z\":200}"}}]},"logprobs":null,"finish_reason":null}]}