List replicas
List replicas with pagination with optional filtering. Only Replicas that are public or belong to the authenticated user are returned.
Query parameters
-
Filters by the owner UUID of the Replicas
-
The replica owner ID.
-
Pagination: The page number to return
Minimum value is
0. -
Pagination: The page index to return
Minimum value is
0. Default value is1. -
Pagination: The number of items per page
Minimum value is
0. Default value is24. -
Filters by the replica's slug
-
Search: by name of Replica, sorted in ascending order
-
Sorts by name or popularity of Replicas in ascending order
Values are
nameorpopularity. Default value isname. -
Filters by integration
Values are
telegramordiscord.
GET
/v1/replicas
curl \
--request GET 'https://api.sensay.io/v1/replicas' \
--header "X-ORGANIZATION-SECRET: $API_KEY" \
--header "X-USER-ID: $API_KEY" \
--header "X-API-Version: 2025-03-25"
Response examples (200)
{
"success": true,
"type": "string",
"items": [
{
"llm": {
"model": "gpt-4o",
"tools": [
"answerToLife"
],
"systemMessage": "Concise, knowledgeable, empathetic and cheerful."
},
"name": "Example Replica",
"slug": "copy",
"tags": [
"male",
"italian"
],
"type": "character",
"uuid": "123e4567-e89b-12d3-a456-426614174000",
"ownerID": "a-user-id",
"private": false,
"purpose": "Replica purpose",
"greeting": "What would you like to know?",
"created_at": "2023-10-01T12:00:00Z",
"owner_uuid": "123e4567-e89b-12d3-a456-426614174001",
"introduction": "deprecated",
"profileImage": "https://domain.example/image.webp",
"profile_image": "https://deprecated.invalid/image.png",
"video_enabled": true,
"voice_enabled": true,
"system_message": "Descriptive, energetic, friendly",
"whitelistEmails": [
"example@domain.example"
],
"shortDescription": "An example replica",
"short_description": "An example replica",
"chat_history_count": 5,
"suggestedQuestions": [
"What is the meaning of life?"
],
"discord_integration": {
"token": "MTk4NjIyNDgzNDcxOTI1MjQ4.Cl2FMQ.ZnCjm1XVW7vRze4b7Cq4se7kKWs",
"is_active": true,
"service_name": "test_discord_bot"
},
"telegram_integration": {
"token": "7701101112:DASeKD32EQLL32113-ngfVUMkyzg",
"service_name": "test_telegram_bot"
}
}
],
"total": 100
}
Response examples (400)
{
"error": "Replica owner knowledge base entry custom quota exceeded. Current usage: 10/10. To fix this, either increase the totalUserQuota value in your request's usageLimits parameter or remove some existing Knowledge Base entries.",
"success": false,
"error_code": "KNOWLEDGE_BASE_CUSTOM_QUOTA_EXCEEDED",
"request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
"fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
Response examples (401)
{
"error": "Replica owner knowledge base entry custom quota exceeded. Current usage: 10/10. To fix this, either increase the totalUserQuota value in your request's usageLimits parameter or remove some existing Knowledge Base entries.",
"success": false,
"error_code": "KNOWLEDGE_BASE_CUSTOM_QUOTA_EXCEEDED",
"request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
"fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
Response examples (404)
{
"error": "A text representation of the error",
"success": false,
"request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
Response examples (415)
{
"error": "Replica owner knowledge base entry custom quota exceeded. Current usage: 10/10. To fix this, either increase the totalUserQuota value in your request's usageLimits parameter or remove some existing Knowledge Base entries.",
"success": false,
"error_code": "KNOWLEDGE_BASE_CUSTOM_QUOTA_EXCEEDED",
"request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
"fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
Response examples (500)
{
"error": "A text representation of the error",
"success": false,
"request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
"fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
"inner_exception": {
"name": "Server overheated",
"cause": "Request too complicated",
"stack": "Error: Server overheated due to an unexpected situation\n at Object.eval (eval at <anonymous>...",
"message": "The server overheated due to an unexpected situation"
}
}