List replicas

GET /v1/replicas

Organization service token & User Organization service token

List replicas with pagination with optional filtering. Only Replicas that are public or belong to the authenticated user are returned.

Headers

X-API-Version string

Default value is 2025-03-25.

Query parameters

owner_uuid string

Filters by the owner UUID of the Replicas
ownerID string

The replica owner ID.
page integer

Pagination: The page number to return
page_index integer Deprecated

Pagination: The page index to return

Default value is 1.
page_size integer

Pagination: The number of items per page

Default value is 24.
slug string

Filters by the replica's slug
search string

Search: by name of Replica, sorted in ascending order
tags array[string]

Filters by tags associated to Replicas

Values are AI, Academic, Arts, Blockchain, Business, Celebrity, Charity, Developer, Educator, Europe, Fashion, Finance, Food, Health & Fitness, History, Italian, Kids, Language, Law, Leadership, Lifestyle, Literature, Love, Military, Modelling, Motivation, Movies, Music, North America, Philosophy, Politics, Religion, Science, Self-Help, Sensay, Sports, Technology, Web, Wisdom, blockchain, engage2earn, female, investment, male, meme, miniapp, telegram, or web3.
sort string

Sorts by name or popularity of Replicas in ascending order

Values are name or popularity. Default value is name.
integration string

Filters by integration

Values are telegram or discord.

Responses

200 application/json

List of Replicas
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- type string Required
- items array[object] Required
  
  Array of replica items for the current page. Will be an empty array if no items exist.
  
  Hide items attributes Show items attributes object
  
  name string Required
  
  The name of the replica.
  
  Maximum length is 50.
  
  purpose string
  
  The purpose of the replica. This field is not used for training the replica.
  
  Maximum length is 200.
  
  shortDescription string Required
  
  A short description of your replica. This field is not used for training the replica.
  
  Maximum length is 50.
  
  greeting string Required
  
  The first thing your replica will say when you start a conversation with them.
  
  Maximum length is 600.
  
  type string
  
  The replica type. individual: A replica of yourself. character: A replica of a character: can be anything you want. brand: A replica of a business persona or organization.
  
  Values are individual, character, or brand. Default value is character.
  
  ownerID string Required
  
  The replica owner ID.
  
  private boolean
  
  Visibility of the replica. When set to true, only the owner will be able to find the replica and chat with it.
  
  Default value is false.
  
  whitelistEmails array[string(email)]
  
  Emails of users who can use the replica.
  
  Default value is [] (empty).
  
  slug string Required
  
  The slug of the replica. Slugs can be used by API consumers to determine the URLs where replicas can be found.
  
  Maximum length is 50.
  
  tags array[string]
  
  The tags associated with the replica. Tags help categorize replicas and make them easier to find.
  
  Default value is [] (empty).
  
  profileImage string(uri)
  
  The URL of the profile image of the replica. The image will be downloaded, optimized and stored on our servers, so the URL in the response will be different. Supported formats: .jpg, .jpeg, .png, .bmp, .webp, .avif
  
  Format should match the following pattern: https?:\/\/[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z0-9()]+\b([-a-zA-Z0-9()@:%_+.~#?&\/=]*). Default value is https://sensay.io/assets/default-replica-profile.webp.
  
  suggestedQuestions array[string]
  
  Suggested questions when starting a conversation.
  
  Default value is [] (empty).
  
  llm object Required
  
  Hide llm attributes Show llm attributes object
  
  model string
  
  The LLM model of the replica.
  
  Values are gpt-4o, claude-3-5-haiku-latest, claude-3-7-sonnet-latest, claude-4-sonnet-20250514, grok-2-latest, grok-3-beta, deepseek-chat, o3-mini, gpt-4o-mini, huggingface-eva, or huggingface-dolphin-llama. Default value is claude-3-5-haiku-latest.
  
  memoryMode string
  
  The memory mode of the replica.
  
  Values are prompt-caching or rag-search. Default value is rag-search.
  
  systemMessage string
  
  Who is your replica? How do you want it to talk, respond and act.
  
  Maximum length is 30000.
  
  tools array[string]
  
  The replica's tools. Tools enable agents to interact with the world. getTokenInfo: Allows replica to get token information
  
  Values are getTokenInfo, getUdaoTokenInfo, getSensayTokenInfo, getTokenInfoMEAI, answerToLife, or toolhouse. Default value is [] (empty).
  
  voicePreviewText string
  
  Text that can be used to generate a voice preview.
  
  Maximum length is 400.
  
  uuid string(uuid) Required
  
  The replica UUID
  
  profile_image string | null Required Deprecated
  
  The URL of the profile image of the replica. Please use profileImage instead.
  
  short_description string | null Required Deprecated
  
  The description of the replica. Please use shortDescription instead.
  
  introduction string | null Required Deprecated
  
  The introduction of the replica. Please use greeting instead.
  
  created_at string | null Required
  
  The date and time the replica was created.
  
  owner_uuid string | null Required Deprecated
  
  The UUID of the owner of the replica. Please migrate to the new User ID system and use ownerID instead.
  
  voice_enabled boolean Required Beta
  
  Whether the replica has voice support.
  
  video_enabled boolean Required Beta
  
  Whether the replica has video support.
  
  chat_history_count integer | null Required
  
  The total number of chat history items related to this replica, for all users of the organization.
  
  system_message string Required Deprecated
  
  The replica's tone, personality and behaviour, Please use llm.systemMessage instead.
  
  discord_integration object | null Required Beta
  
  The Discord integration of the replica.
  
  Hide discord_integration attributes Show discord_integration attributes object | null Beta
  
  token string | null Required
  
  service_name string | null Required
  
  is_active boolean | null Required
  
  telegram_integration object | null Required Beta
  
  The Telegram integration of the replica.
  
  Hide telegram_integration attributes Show telegram_integration attributes object | null Beta
  
  token string | null Required
  
  service_name string | null Required
  
  elevenLabsID string | null Beta
  
  The ElevenLabs voice ID associated with this replica.
- total integer Required
  
  The total number of replica items available across all pages
400 application/json

Bad Request
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
401 application/json

Unauthorized
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
404 application/json

Not Found
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- request_id string Required
  
  A unique identifier of the request, useful for reporting
415 application/json

Unsupported Media Type
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
500 application/json

Internal Server Error
Hide response attributes Show response attributes object
- success boolean Required
  
  Indicates the status of the request
- error string Required
  
  A text representation of the error
- fingerprint string
  
  A unique identifier of the event, useful for reporting
- request_id string Required
  
  A unique identifier of the request, useful for reporting
- inner_exception object
  
  The inner exception
  
  Hide inner_exception attributes Show inner_exception attributes object
  
  name string Required
  
  message string Required
  
  cause string
  
  stack string

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"
        ],
        "memoryMode": "rag-search",
        "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",
      "elevenLabsID": "ABC123XYZ456",
      "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)

{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}

Response examples (401)

{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}

Response examples (404)

{
  "success": true,
  "error": "string",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}

Response examples (415)

{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}

Response examples (500)

{
  "success": true,
  "error": "string",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b",
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "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"
  }
}