Characters

Characters are the core resource in Mindforge. A character is an AI agent with identity — it has a name, personality, voice, knowledge, and capabilities. Characters can be game NPCs, museum guides, brand mascots, app companions, or anything else that needs to feel like a someone rather than a something.

The Character object

{
  "id": "character_PuTlWmWuynYZu8sP",
  "createdAt": "2026-01-15T12:00:00Z",
  "projectId": "project_abc123",
  "name": "Atlas",
  "description": "A knowledgeable guide who helps players navigate the world.",
  "voiceId": "voice_abc123",
  "voiceDescription": "A warm, calm male voice with a slight British accent.",
  "hasAvatar": true,
  "capabilityGroupIds": ["capability_group_smartmob_v1"]
}

Field	Type	Description
id	string	Unique identifier (character_ prefix)
createdAt	string	ISO 8601 timestamp
projectId	string	Project this character belongs to
name	string	Display name
description	string | null	Personality and behavior description
voiceId	string | null	ID of an assigned voice
voiceDescription	string | null	Free-form TTS voice instruction
hasAvatar	boolean	Whether an avatar has been generated
capabilityGroupIds	string[]	Attached capability group IDs

Create a character

POST /characters

Request body

Field	Type	Required	Description
name	string	Yes	Display name
description	string | null	No	Personality description
voiceId	string	No	Voice ID to assign
voiceDescription	string | null	No	Free-form voice instruction for TTS
capabilityGroupIds	string[]	No	Capability groups to attach

curl

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 players navigate the world.",
    "capabilityGroupIds": ["capability_group_smartmob_v1"]
  }'

Returns a Character object.

List all characters

GET /characters

curl

curl https://api.mindforge.ai/characters \
  -H "Authorization: Bearer $MINDFORGE_API_KEY"

Returns an array of Character objects.

Retrieve a character

GET /characters/{characterId}

curl

curl https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP \
  -H "Authorization: Bearer $MINDFORGE_API_KEY"

Update a character

PATCH /characters/{characterId}

All fields are optional. Only provided fields are updated.

Request body

Field	Type	Description
name	string	New display name
description	string | null	New description
voiceId	string	New voice ID
voiceDescription	string | null	New voice instruction
capabilityGroupIds	string[]	Replaces all attached capability groups

curl

curl -X PATCH https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "A mysterious guide with ancient knowledge." }'

Delete a character

DELETE /characters/{characterId}

curl

curl -X DELETE https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP \
  -H "Authorization: Bearer $MINDFORGE_API_KEY"

{ "id": "character_PuTlWmWuynYZu8sP", "deleted": true }

Add a capability

POST /characters/{characterId}/capabilities

curl -X POST https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP/capabilities \
  -H "Authorization: Bearer $MINDFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "capabilityId": "capability_5X51Einm2JqPi53D" }'

Remove a capability

DELETE /characters/{characterId}/capabilities/{capabilityId}

curl -X DELETE https://api.mindforge.ai/characters/character_PuTlWmWuynYZu8sP/capabilities/capability_5X51Einm2JqPi53D \
  -H "Authorization: Bearer $MINDFORGE_API_KEY"