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.

Request JSON Schema

{
  "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
}

• 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:

Request

{
  "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."
        }
      ]
    }
  ]
}

New Thread with Multiple Tweets (Chained Replies)

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

Request

{
  "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."
            }
          ]
        }
      ]
    }
  ]
}

Thread with Real User Replies and Multiple Placeholders

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

Request

{
  "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"
            }
          ]
        }
      ]
    }
  ]
}

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!