> ## Documentation Index
> Fetch the complete documentation index at: https://craftengine.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# character engine

> This document describes the single, tree‑based endpoint for integrating our character engine with your apps.

It is designed for simplicity, flexibility, and extensibility. Wherever you place a placeholder (a message with your character ID and no text), the API will generate content.

In future versions, we plan to introduce multimodality capabilities, allowing for the handling and response to various forms of media, including images, video, and audio.

## Endpoint

```
POST /api/v1/character/response
Content-Type: application/json
```

This is the only endpoint you need. It accepts a full conversation tree (`messages`) with placeholders for generated replies.

```json Request JSON Schema theme={null}
{
  "global_context"?: "string",    // Optional: a global brief that applies to all generated messages
  "accounts"?: [                  // Optional: metadata or extra facts about real handles
    {
      "handle": "@al1ce",
      "context": "Alice is a robotics engineer and the character’s best friend."
    }
  ],
  "messages": [ Message ]         // The full conversation tree; placeholders generate replies
}
```

```typescript Message Object theme={null}
type Message = {
  id: string,             // Developer‑chosen identifier (e.g. "p1", "start", "t2")
  author: string,         // Either a account handle ("@al1ce") or your character ID ("loafie")
  text?: string,          // Omit this field to mark a placeholder for generated content
  context?: string,       // Optional: mini-brief for the generation of this specific message
  replies?: Message[]     // Nested replies, allowing arbitrary depth
}
```

```json Response JSON Schema theme={null}
// The response array contains one object for each placeholder, matching by id.
{
  "responses": [
    {
      "id": "string",   // Echoes the placeholder Message.id
      "text": "string"  // Generated content for that placeholder
    }
    // ...one entry per placeholder
  ]
}
```

* A **placeholder** is any Message where text is omitted and author is your character ID. The API will generate content at that node.
* You can place **multiple placeholders** anywhere in the tree to generate multiple replies in one request.
* **Real user messages** (e.g. from @bob) must include text; the API does not generate user replies.

## Usage Examples

### Single Reply in a Thread

A single placeholder where `loafie` replies to `@alice`:

```json Request theme={null}
{
  "messages": [
    {
      "id": "root1",
      "author": "@al1ce",
      "text": "Who’s up for a road trip this weekend?",
      "replies": [
        {
          "id": "p1",
          "author": "loafie",
          "context": "Encourage them but complain about traffic."
        }
      ]
    }
  ]
}
```

```json Response theme={null}
{
  "responses": [
    {
      "id": "p1",
      "text": "A road trip sounds epic—until you’re stuck behind a caravan of RVs for hours. Count me in, Alice... but only if someone else drives!"
    }
  ]
}
```

### **New Thread with Multiple Tweets (Chained Replies)**

Start a new thread of three tweets, guide the thread's flow with context for each message:

```json Request theme={null}
{
  "global_context": "You’re an inspirational coach.",
  "messages": [
    {
      "id": "t1",
      "author": "loafie",
      "context": "Kick off with a strong rallying cry.",
      "replies": [
        {
          "id": "t2",
          "author": "loafie",
          "context": "Build on that momentum with a practical tip.",
          "replies": [
            {
              "id": "t3",
              "author": "loafie",
              "context": "Close with a call-to-action and reference the thread."
            }
          ]
        }
      ]
    }
  ]
}
```

```json Response theme={null}
{
  "responses": [
    {
      "id": "t1",
      "text": "Rise and shine, champions! Today’s the day you own your greatness!"
    },
    {
      "id": "t2",
      "text": "Start small—set one clear intention and watch momentum build."
    },
    {
      "id": "t3",
      "text": "Now go tag a friend who needs this boost and let’s conquer together."
    }
  ]
}
```

### **Thread with Real User Replies and Multiple Placeholders**

A thread where two different users reply, and your character responds to each:

```json Request theme={null}
{
  "accounts": [
    {
      "handle": "@bob",
      "context": "Bob loves spicy humor."
    },
    {
      "handle": "@carol",
      "context": "Carol is a deep thinker who shares quotes."
    }
  ],
  "global_context": "Keep responses witty but respectful.",
  "messages": [
    {
      "id": "root",
      "author": "loafie",
      "text": "What’s the wildest thing you’ve done this year?",
      "replies": [
        {
          "id": "r1",
          "author": "@bob",
          "text": "I once tried to teach my cat to skateboard… and she nailed it!",
          "replies": [
            {
              "id": "p1",
              "author": "loafie"
            }
          ]
        },
        {
          "id": "r2",
          "author": "@carol",
          "text": "I spent a week meditating in silence atop a mountain.",
          "replies": [
            {
              "id": "p2",
              "author": "loafie"
            }
          ]
        }
      ]
    }
  ]
}
```

```json Response theme={null}
{
  "responses": [
    {
      "id": "p1",
      "text": "That cat is a natural—I bow to its skateboard mastery!"
    },
    {
      "id": "p2",
      "text": "A week in silence must have been profound. How has it changed your daily life?"
    }
  ]
}
```

This single, tree‑based API lets you define where your character should speak and provide any guiding context. Add, remove, or nest placeholders as needed—our engine fills in the blanks. Happy integrating!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.