Getting started

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

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://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"

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/training \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json" \
 -d '{}'

Example response:

{
  "success": true,
  "knowledgeBaseID": 12345
}

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

export KNOWLEDGE_BASE_ID=12345

1. Add information to the knowledge base entry

curl -X PUT https://api.sensay.io/v1/replicas/$REPLICA_UUID/training/$KNOWLEDGE_BASE_ID \
 -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
 -H "X-API-Version: $API_VERSION" \
 -H "Content-Type: application/json" \
 -d '{
   "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."
 }'

Example response:

{
  "success": true
}

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."
}