Characters

List, create, update, and delete AI characters. Characters define the personality, speaking style, and behavior of your AI assistant.

GET

/api/v1/characters

List available characters

POST

/api/v1/characters

Create a new character

GET

/api/v1/characters/:id

Get character details

PATCH

/api/v1/characters/:id

Update character

DELETE

/api/v1/characters/:id

Delete character

List Characters

Supports optional pagination, search, and filtering via query parameters. When no query parameters are provided, all accessible characters are returned.

Query Parameters

Param	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page, 1-100 (default: 20)
search	string	Text search on name and description
gender	string	Filter by gender: male, female, non-binary, other
ageMin	number	Minimum age filter (min: 18)
ageMax	number	Maximum age filter
occupation	string	Text search on occupation
ownership	string	Filter: all (default), mine, public, presets

Request

curl "https://www.turingmate.com/api/v1/characters?page=1&limit=10&search=mia&gender=female" \
  -H "x-api-key: your_api_key"

Response (paginated)

{
  "characters": [
    {
      "id": "abc123",
      "name": "Mia",
      "description": "A friendly AI companion",
      "gender": "female",
      "avatar": null,
      "profilePhotoUrl": "https://...",
      "canInitiateConversation": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  }
}

Create Character

Request

curl -X POST https://www.turingmate.com/api/v1/characters \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex",
    "gender": "male",
    "personality": "Curious, witty, and always up for a deep conversation about science and philosophy",
    "speakingStyle": "Casual and playful, uses metaphors, asks lots of questions"
  }'

Required Fields

Field	Type	Description
name	string	Character name (1-100 chars)
personality	string	Core personality traits (10-2000 chars)
speakingStyle	string	How they communicate (10-1000 chars)

Optional Fields

Field	Type	Description
description	string	Short description (max 500)
gender	string	Gender: male, female, non-binary, or other
appearanceDescription	string	Physical appearance for image gen
canInitiateConversation	boolean	Can proactively message users