Mindforge Docs

Appearance

Quickstart ​

Get up and running with the Mindforge API in under 5 minutes.

1. Get an API key ​

Sign up at mindforge.ai and create an API key in your project settings. Keys start with sk-mf-.

2. Create a character ​

sh
curl -X POST https://api.mindforge.ai/characters \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atlas",
    "description": "A knowledgeable guide who helps visitors explore and learn."
  }'

Save the id from the response — you'll need it next.

3. Chat with your character ​

The simplest way to interact is through the conversations API:

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

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

4. Or use any OpenAI SDK ​

Mindforge is OpenAI-compatible. Pass the character ID as the model and point any OpenAI SDK at Mindforge:

python
from openai import OpenAI

client = OpenAI(
    base_url="https://api.mindforge.ai/v1",
    api_key="sk-mf-YOUR_KEY",
)

response = client.chat.completions.create(
    model="CHARACTER_ID",  # your character ID
    messages=[
        {"role": "user", "content": "Hello! Where should I go first?"}
    ],
)

print(response.choices[0].message.content)
typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.mindforge.ai/v1",
  apiKey: "sk-mf-YOUR_KEY",
});

const response = await client.chat.completions.create({
  model: "CHARACTER_ID", // your character ID
  messages: [
    { role: "user", content: "Hello! Where should I go first?" },
  ],
});

console.log(response.choices[0].message.content);
sh
curl https://api.mindforge.ai/v1/chat/completions \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "CHARACTER_ID",
    "messages": [
      { "role": "user", "content": "Hello! What should I see first?" }
    ]
  }'

Next steps ​