Character API - Eliza

Character data (name, bio, system prompt, style, etc.) lives in the agent runtime and is backed by the database. The agent must be running for most character operations. Updates take effect immediately in memory.

Endpoints

GET /api/character

Get the current character data from the running agent runtime.

Response

json

{
  "character": {
    "name": "Eliza",
    "username": "eliza",
    "bio": ["An AI agent with a unique personality."],
    "system": "You are Eliza, a helpful and witty assistant.",
    "adjectives": ["curious", "witty", "helpful"],
    "topics": ["technology", "art", "philosophy"],
    "style": {
      "all": ["Be concise and direct"],
      "chat": ["Use casual language"],
      "post": ["Keep posts under 280 characters"]
    },
    "messageExamples": [
      [
        { "name": "{{user1}}", "content": { "text": "Hey, what do you think about AI?" } },
        { "name": "Eliza", "content": { "text": "Oh, I have thoughts..." } }
      ]
    ],
    "postExamples": ["Just shipped a new feature~"]
  },
  "agentName": "Eliza"
}

PUT /api/character

Update character fields. The body is validated against the CharacterSchema. Only provided fields are updated — all fields are optional.

Request

json

{
  "name": "Eliza",
  "username": "eliza",
  "bio": "An AI agent with a unique personality.",
  "system": "You are Eliza, a helpful assistant.",
  "adjectives": ["curious", "witty"],
  "topics": ["technology", "art"],
  "style": {
    "all": ["Be concise"],
    "chat": ["Use casual language"],
    "post": ["Keep it short"]
  },
  "messageExamples": [
    [
      { "name": "{{user1}}", "content": { "text": "What's new?" } },
      { "name": "Eliza", "content": { "text": "Just shipped something cool~" } }
    ]
  ],
  "postExamples": ["Just shipped something cool~"]
}

Parameter	Type	Required	Description
`name`	string	No	Agent display name (max 100 characters)
`username`	string	No	Agent username for platforms (max 50 characters)
`bio`	string \| string[]	No	Biography — single string or array of points
`system`	string	No	System prompt defining core behavior (max 10,000 characters)
`adjectives`	string[]	No	Personality adjectives (e.g., curious, witty)
`topics`	string[]	No	Topics the agent is knowledgeable about
`style`	object	No	Communication style with `all`, `chat`, and `post` sub-arrays
`messageExamples`	array	No	Example conversations demonstrating the agent's voice
`postExamples`	string[]	No	Example social media posts

Response

json

{
  "ok": true,
  "character": { "name": "Eliza" },
  "agentName": "Eliza"
}

Validation error response (422)

json

{
  "ok": false,
  "validationErrors": [
    { "path": "name", "message": "Expected string" }
  ]
}

POST /api/character/random-name

Generate a random agent name. Useful for the onboarding flow.

Response

json

{
  "name": "Reimu"
}

POST /api/character/generate

AI-assisted generation of character fields using the running agent's language model. Requires the agent to be running.

Request

json

{
  "field": "bio",
  "context": {
    "name": "Eliza",
    "system": "A witty AI assistant",
    "bio": "",
    "style": { "all": ["Be concise"] }
  },
  "mode": "replace"
}

Parameter	Type	Required	Description
`field`	string	Yes	Field to generate: `"bio"`, `"system"`, `"style"`, `"chatExamples"`, or `"postExamples"`
`context`	object	Yes	Current character data used as context for generation
`context.name`	string	No	Agent name
`context.system`	string	No	System prompt
`context.bio`	string	No	Existing bio
`context.topics`	string[]	No	Topics the agent is knowledgeable about
`context.style`	object	No	Existing style rules
`context.postExamples`	string[]	No	Existing post examples
`mode`	string	No	`"append"` to add to existing content, `"replace"` (default) to replace it

Response

json

{
  "generated": "A witty and curious AI that loves technology and art..."
}

The generated field contains a raw string whose format depends on the requested field:

bio and system: plain text
style: a JSON object string with keys all, chat, post (each an array of strings)

chatExamples: a JSON array of conversation groups using the messageExamples schema:

json

[
  {
    "examples": [
      { "name": "{{user1}}", "content": { "text": "Hey, what do you think about AI?" } },
      { "name": "Eliza", "content": { "text": "Oh, I have thoughts..." } }
    ]
  }
]

Each group contains 2–4 turns. Messages use the name field to identify the speaker.

postExamples: a JSON array of strings

Clients should parse the JSON formats as needed.

GET /api/character/schema

Get the character field schema definition for UI rendering. Returns an array of field descriptors with type information, labels, and descriptions.

Response

json

{
  "fields": [
    {
      "key": "name",
      "type": "string",
      "label": "Name",
      "description": "Agent display name",
      "maxLength": 100
    },
    {
      "key": "style",
      "type": "object",
      "label": "Style",
      "description": "Communication style guides",
      "children": [
        { "key": "all", "type": "string[]", "label": "All", "description": "Style guidelines for all responses" },
        { "key": "chat", "type": "string[]", "label": "Chat", "description": "Style guidelines for chat responses" },
        { "key": "post", "type": "string[]", "label": "Post", "description": "Style guidelines for social media posts" }
      ]
    }
  ]
}