Getting started

View as Markdown

In this Getting started guide, we will assume you have already obtained your organization's Secret Service Token, which you will need to use in your server-to-server requests against https://api.sensay.io.

Walkthrough


All API requests must include a Content-Type header.


Specifying the API version as a X-API-Version header is highly recommended, as it will allow you to handle breaking changes without errors. All breaking changes are announced on our Sensay API Telegram Channel.

Set your variables 

export USER_ID=test_user_id
export ORGANIZATION_SECRET=your_secret_token
export API_VERSION=2025-03-25

1. Create a user in your organization

Each organization can have many users. We will first create a new user for your organization:

curl -X POST https://api.sensay.io/v1/users \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json" \
 -d '{"id": "'"$USER_ID"'"}'

Example response:

{ "id": "test_user_id", "linkedAccounts": [] }

The id field is optional and allows you to provide a unique identifier for the user in your organization. It is used to identify the user in further requests. If you do not provide a user id, the API will generate a unique one for you:

curl -X POST https://api.sensay.io/v1/users \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json" \
 -d '{}'

Example response:

{ "id": "12345678-1234-1234-1234-123456789abc", "linkedAccounts": [] }

2. Create a user replica in your organization

Replicas belong to users, so we can create a new replica belonging to the user we created:

curl -X POST https://api.sensay.io/v1/replicas \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "My Replica",
   "shortDescription": "A helpful assistant",
   "greeting": "Hi there! How can I help you today?",
   "ownerID": "'"$USER_ID"'",
   "private": false,
   "slug": "my-replica",
   "llm": {
     "provider": "openai",
     "model": "gpt-4o"
   }
 }'

You will get a response similar to this one with the replica UUID returned.

{"success": true, "uuid": "12345678-1234-1234-1234-123456789abc"}

Export the replica UUID to use it in the next steps.

export REPLICA_UUID=copy_and_paste_the_uuid_returned_above

3. List replicas accessible by the user of your organization 

curl -X GET https://api.sensay.io/v1/replicas \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json" \
 -H "X-USER-ID: $USER_ID"

The response will include all replicas that the user has access to, including private ones:

{
  "success": true,
  "type": "array",
  "items": [
    {
      "uuid": "12345678-1234-1234-1234-123456789abc",
      "name": "My Replica",
      "slug": "my-replica",
      "profile_image": "https://studio.sensay.io/assets/default-replica-profile.webp",
      "short_description": "A helpful assistant",
      "introduction": "Hi there! How can I help you today?",
      "tags": [],
      "created_at": "2025-04-15T08:05:03.167222+00:00",
      "owner_uuid": "12345678-1234-1234-1234-123456789abc",
      "voice_enabled": false,
      "video_enabled": false,
      "chat_history_count": 0,
      "system_message": "",
      "telegram_service_name": null,
      "discord_service_name": null,
      "discord_is_active": null,
      "telegram_integration": null,
      "discord_integration": null
    }
  ],
  "total": 1
}

Alternatively, list all replicas within your Organization, including private ones:

curl -X GET https://api.sensay.io/v1/replicas \
 -H "Content-Type: application/json" \
 -H "X-API-Version: $API_VERSION" \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET"


By not specifying X-USER-ID you are performing the request as an admin, hence listing all replicas within your Organization, including non-listed and private ones.

4. Get all chat history between a user and a replica 

curl -X GET https://api.sensay.io/v1/replicas/$REPLICA_UUID/chat/history \
 -H "Content-Type: application/json" \
 -H "X-API-Version: $API_VERSION" \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-USER-ID: $USER_ID"

Initially, after creation, the chat history will be empty:

{
  "success": true,
  "type": "array",
  "items": []
}

5. Chat with a replica 

curl -X POST https://api.sensay.io/v1/replicas/$REPLICA_UUID/chat/completions \
 -H "Content-Type: application/json" \
 -H "X-API-Version: $API_VERSION" \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-USER-ID: $USER_ID" \
 -d '{"content":"How did you handle the immense pressure during the Civil War?"}'

The response of the request include the chat response:

{
  "success": true,
  "content": "I don't have enough information to answer that question."
}

6. Retrieve the chat history again 

curl -X GET https://api.sensay.io/v1/replicas/$REPLICA_UUID/chat/history \
 -H "Content-Type: application/json" \
 -H "X-API-Version: $API_VERSION" \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-USER-ID: $USER_ID"

Response now includes the chat message and its response:

{
  "success": true,
  "type": "array",
  "items": [
    {
      "id": 668,
      "created_at": "2025-04-15T08:11:00.093761+00:00",
      "content": "How did you handle the immense pressure during the Civil War?",
      "role": "user",
      "is_private": false,
      "source": "web",
      "replica_uuid": "4da68021-78a7-4fa2-91c1-ea2e5986e06f",
      "is_archived": false,
      "replica_slug": "my-replica",
      "user_uuid": "210bb355-193d-4ed0-8223-5802710438c9",
      "sources": []
    },
    {
      "id": 669,
      "created_at": "2025-04-15T08:11:00.299349+00:00",
      "content": "Response content",
      "role": "assistant",
      "is_private": false,
      "source": "web",
      "replica_uuid": "4da68021-78a7-4fa2-91c1-ea2e5986e06f",
      "is_archived": false,
      "replica_slug": "my-replica",
      "user_uuid": "210bb355-193d-4ed0-8223-5802710438c9",
      "sources": []
    }
  ]
}

7. Train your replica with custom knowledge

To make your replica more useful, you can train it with custom knowledge. Let's add some information about your company:

  1. Create a knowledge base entry
curl -X POST https://api.sensay.io/v1/replicas/$REPLICA_UUID/knowledge-base \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json" \
 -d '{ "text": "Our company was founded in 2020. We specialize in AI-powered customer service solutions. Our business hours are Monday to Friday, 9 AM to 5 PM Eastern Time. We offer a 30-day money-back guarantee on all our products." }'

Example response:

{
  "success": true,
  "results":[
    {
      "enqueued": true,
      "type":"text",
      "knowledgeBaseID":193377
    }
  ]
}

Export the knowledge base ID to use it in the next step:

export KNOWLEDGE_BASE_ID=12345
  1. Wait for your replica to be trained
curl -X GET https://api.sensay.io/v1/replicas/$REPLICA_UUID/knowledge-base/$KNOWLEDGE_BASE_ID \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json"

Example response:

{
  "success": true,
  "id": 193377,
  "replicaUUID": "4876c98d-559d-4497-b8d3-38819e00010a",
  "type": "text",
  "status": "VECTOR_CREATED",
  "rawText": "Our company was founded in 2020. We specialize in AI-powered customer service solutions. Our business hours are Monday to Friday, 9 AM to 5 PM Eastern Time. We offer a 30-day money-back guarantee on all our products.",
  "generatedFacts":[
    "... omitted for brevity ..."
  ],
  "rawTextChunks":[
    {
        "content":"Our company was founded in 2020. We specialize in AI-powered customer service solutions. Our business hours are Monday to Friday, 9 AM to 5 PM Eastern Time. We offer a 30-day money-back guarantee on all our products.",
        "chunkChars":216,
        "chunkIndex":0,
        "chunkTokens":51
    }
  ],
  "generatedTitle":"Company Overview: AI-Powered Customer Service Solutions",
  "summary":"This company, established in 2020, specializes in providing advanced AI-powered customer service solutions. They operate from Monday to Friday, between 9 AM and 5 PM Eastern Time. A key aspect of their customer-centric approach is a generous 30-day money-back guarantee that applies to all their products. This policy underscores their commitment to customer satisfaction and product quality.",
  "createdAt":"2025-11-06T09:36:48.213015+00:00",
  "updatedAt":"2025-11-06T09:37:36.143021+00:00"
}

Wait for your replica to be trained: the value of status should be VECTOR_CREATED or, eventually, READY.

  1. Test your trained replica

Now you can ask your replica about the information you just added:

curl -X POST https://api.sensay.io/v1/replicas/$REPLICA_UUID/chat/completions \
 -H "Content-Type: application/json" \
 -H "X-API-Version: $API_VERSION" \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-USER-ID: $USER_ID" \
 -d '{"content":"What are your business hours?"}'

Example response:

{
  "success": true,
  "content": "Our business hours are Monday to Friday, 9 AM to 5 PM Eastern Time."
}


The replica will now be able to answer questions based on the information you provided. For more advanced training options, see the Training documentation.