Characters API

Characters are AI personalities and chatbots that users create on the platform. Each character has its own name, system prompt, backing model, and optional voice. Use these endpoints to create, update, list, and delete your characters, or browse the public explore feed.

Base URL

https://api.replr.ai/v1

POST/v1/replrsAuth Required

Create a new character with a name, system prompt, and optional configuration like model, avatar, category, greeting message, and voice.

Request Body

Name	Type	Required	Description
`name`	string	Required	Display name of the character (1-80 characters).
`description`	string	Optional	Short public description shown in explore and embeds (max 300 characters).
`instructions`	string	Required	System prompt that defines the character's personality, tone, and behavior. Supports Markdown.
`model`	string	Optional	Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.
`avatar_url`	string	Optional	URL to a square image used as the character's avatar (recommended 256x256+).
`is_public`	boolean	Optional	Whether the character appears in the public explore feed. Defaults to false.
`category`	string	Optional	Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.
`greeting_message`	string	Optional	First message the character sends when a new conversation starts. Omit to let the character generate one.
`voice_id`	string	Optional	Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.replr.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

curl -X POST https://api.replr.ai/v1/replrs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Atlas",
    "description": "A curious research assistant.",
    "instructions": "You are Atlas, a knowledgeable research assistant who explains complex topics clearly.",
    "model": "default",
    "is_public": true,
    "category": "assistant",
    "greeting_message": "Hey! I\u0027m Atlas. What are we researching today?"
  }'

GET/v1/replrsAuth Required

List all characters owned by the authenticated user. Supports pagination and sorting.

Path Parameters

Name	Type	Required	Description
`limit`	integer	Optional	Max items to return (1-100). Defaults to 20.
`offset`	integer	Optional	Number of items to skip for pagination. Defaults to 0.
`sort`	string	Optional	Sort order. One of "created_at", "updated_at", or "name". Defaults to "created_at".

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Atlas",
      "description": "A curious research assistant that loves diving deep into topics.",
      "model": "default",
      "avatar_url": "https://cdn.replr.ai/avatars/atlas.png",
      "is_public": true,
      "category": "assistant",
      "message_count": 4832,
      "created_at": "2026-01-15T08:30:00Z",
      "updated_at": "2026-03-08T14:22:10Z"
    },
    {
      "id": "f0e1d2c3-b4a5-6789-0fed-cba987654321",
      "name": "Luna",
      "description": "Creative writing partner with a flair for storytelling.",
      "model": "creative",
      "avatar_url": "https://cdn.replr.ai/avatars/luna.png",
      "is_public": false,
      "category": "creative",
      "message_count": 1290,
      "created_at": "2026-02-03T19:10:00Z",
      "updated_at": "2026-03-07T11:45:30Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}

Examples

curl https://api.replr.ai/v1/replrs?limit=10&sort=updated_at \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/replrs/:idAuth Required

Retrieve the full details of a single character by its unique ID.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.replr.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

curl https://api.replr.ai/v1/replrs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

PUT/v1/replrs/:idAuth Required

Update one or more fields on an existing character. Only the fields you include in the request body will be changed.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Request Body

Name	Type	Required	Description
`name`	string	Optional	Display name of the character (1-80 characters).
`description`	string	Optional	Short public description shown in explore and embeds (max 300 characters).
`instructions`	string	Optional	System prompt that defines the character's personality, tone, and behavior. Supports Markdown.
`model`	string	Optional	Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.
`avatar_url`	string	Optional	URL to a square image used as the character's avatar (recommended 256x256+).
`is_public`	boolean	Optional	Whether the character appears in the public explore feed. Defaults to false.
`category`	string	Optional	Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.
`greeting_message`	string	Optional	First message the character sends when a new conversation starts. Omit to let the character generate one.
`voice_id`	string	Optional	Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Atlas",
  "description": "A curious research assistant that loves diving deep into topics.",
  "instructions": "You are Atlas, a knowledgeable and curious research assistant...",
  "model": "default",
  "avatar_url": "https://cdn.replr.ai/avatars/atlas.png",
  "is_public": true,
  "category": "assistant",
  "greeting_message": "Hey! I'm Atlas. What are we researching today?",
  "voice_id": "alloy",
  "message_count": 4832,
  "creator_id": "usr_9f8e7d6c5b4a3210",
  "created_at": "2026-01-15T08:30:00Z",
  "updated_at": "2026-03-08T14:22:10Z"
}

Examples

curl -X PUT https://api.replr.ai/v1/replrs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for Atlas.",
    "model": "creative"
  }'

DELETE/v1/replrs/:idAuth Required

Permanently delete a character and all its associated conversations. This action cannot be undone.

Path Parameters

Name	Type	Required	Description
`id`	string (UUID)	Required	Unique identifier of the character.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deleted": true
}

Examples

curl -X DELETE https://api.replr.ai/v1/replrs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

GET/v1/replrs/exploreAuth Required

Browse public characters created by the community. Filter by category, search by name, and sort by popularity, recency, or trending.

Path Parameters

Name	Type	Required	Description
`category`	string	Optional	Filter by category (assistant, tutor, character, coach, companion, creative, developer, other).
`sort`	string	Optional	Sort order. One of "popular", "recent", or "trending". Defaults to "popular".
`limit`	integer	Optional	Max items to return (1-100). Defaults to 20.
`offset`	integer	Optional	Number of items to skip for pagination. Defaults to 0.
`q`	string	Optional	Free-text search across name and description.

Response

{
  "data": [
    {
      "id": "c3d4e5f6-a1b2-7890-fedc-ba0987654321",
      "name": "CodePilot",
      "description": "Senior engineer that reviews your code and suggests improvements.",
      "model": "default",
      "avatar_url": "https://cdn.replr.ai/avatars/codepilot.png",
      "is_public": true,
      "category": "developer",
      "message_count": 28401,
      "creator_id": "usr_1a2b3c4d5e6f7890",
      "created_at": "2025-12-01T10:00:00Z",
      "updated_at": "2026-03-09T02:15:00Z"
    }
  ],
  "total": 148,
  "limit": 20,
  "offset": 0
}

Examples

curl "https://api.replr.ai/v1/replrs/explore?category=developer&sort=trending&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Name

Type

Required

Description

name

string

Required

Display name of the character (1-80 characters).

description

string

Optional

Short public description shown in explore and embeds (max 300 characters).

instructions

string

Required

System prompt that defines the character's personality, tone, and behavior. Supports Markdown.

model

string

Optional

Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.

avatar_url

string

Optional

URL to a square image used as the character's avatar (recommended 256x256+).

is_public

boolean

Optional

Whether the character appears in the public explore feed. Defaults to false.

category

string

Optional

Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.

greeting_message

string

Optional

First message the character sends when a new conversation starts. Omit to let the character generate one.

voice_id

string

Optional

Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Atlas", "description": "A curious research assistant that loves diving deep into topics.", "instructions": "You are Atlas, a knowledgeable and curious research assistant...", "model": "default", "avatar_url": "https://cdn.replr.ai/avatars/atlas.png", "is_public": true, "category": "assistant", "greeting_message": "Hey! I'm Atlas. What are we researching today?", "voice_id": "alloy", "message_count": 4832, "creator_id": "usr_9f8e7d6c5b4a3210", "created_at": "2026-01-15T08:30:00Z", "updated_at": "2026-03-08T14:22:10Z" }

curl -X POST https://api.replr.ai/v1/replrs \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Atlas", "description": "A curious research assistant.", "instructions": "You are Atlas, a knowledgeable research assistant who explains complex topics clearly.", "model": "default", "is_public": true, "category": "assistant", "greeting_message": "Hey! I\u0027m Atlas. What are we researching today?" }'

Name

Type

Required

Description

limit

integer

Optional

Max items to return (1-100). Defaults to 20.

offset

integer

Optional

Number of items to skip for pagination. Defaults to 0.

sort

string

Optional

Sort order. One of "created_at", "updated_at", or "name". Defaults to "created_at".

{ "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Atlas", "description": "A curious research assistant that loves diving deep into topics.", "model": "default", "avatar_url": "https://cdn.replr.ai/avatars/atlas.png", "is_public": true, "category": "assistant", "message_count": 4832, "created_at": "2026-01-15T08:30:00Z", "updated_at": "2026-03-08T14:22:10Z" }, { "id": "f0e1d2c3-b4a5-6789-0fed-cba987654321", "name": "Luna", "description": "Creative writing partner with a flair for storytelling.", "model": "creative", "avatar_url": "https://cdn.replr.ai/avatars/luna.png", "is_public": false, "category": "creative", "message_count": 1290, "created_at": "2026-02-03T19:10:00Z", "updated_at": "2026-03-07T11:45:30Z" } ], "total": 2, "limit": 20, "offset": 0 }

Name

Type

Required

Description

id

string (UUID)

Required

Unique identifier of the character.

Name

Type

Required

Description

id

string (UUID)

Required

Unique identifier of the character.

Name

Type

Required

Description

name

string

Optional

Display name of the character (1-80 characters).

description

string

Optional

Short public description shown in explore and embeds (max 300 characters).

instructions

string

Optional

System prompt that defines the character's personality, tone, and behavior. Supports Markdown.

model

string

Optional

Backing LLM. Choose from our available models. See the models documentation for the full list of supported identifiers.

avatar_url

string

Optional

URL to a square image used as the character's avatar (recommended 256x256+).

is_public

boolean

Optional

Whether the character appears in the public explore feed. Defaults to false.

category

string

Optional

Explore category. One of assistant, tutor, character, coach, companion, creative, developer, or other.

greeting_message

string

Optional

First message the character sends when a new conversation starts. Omit to let the character generate one.

voice_id

string

Optional

Identifier for the TTS voice used in voice sessions (e.g. alloy, echo, fable).

curl -X PUT https://api.replr.ai/v1/replrs/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "description": "Updated description for Atlas.", "model": "creative" }'

Name

Type

Required

Description

id

string (UUID)

Required

Unique identifier of the character.

Name

Type

Required

Description

category

string

Optional

Filter by category (assistant, tutor, character, coach, companion, creative, developer, other).

sort

string

Optional

Sort order. One of "popular", "recent", or "trending". Defaults to "popular".

limit

integer

Optional

Max items to return (1-100). Defaults to 20.

offset

integer

Optional

Number of items to skip for pagination. Defaults to 0.

q

string

Optional

Free-text search across name and description.

{ "data": [ { "id": "c3d4e5f6-a1b2-7890-fedc-ba0987654321", "name": "CodePilot", "description": "Senior engineer that reviews your code and suggests improvements.", "model": "default", "avatar_url": "https://cdn.replr.ai/avatars/codepilot.png", "is_public": true, "category": "developer", "message_count": 28401, "creator_id": "usr_1a2b3c4d5e6f7890", "created_at": "2025-12-01T10:00:00Z", "updated_at": "2026-03-09T02:15:00Z" } ], "total": 148, "limit": 20, "offset": 0 }