# 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

> warn
> All API requests must include a `Content-Type` header.

> warn
> 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](https://t.me/sensay_api).

### Set your variables

```bash
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:

```bash
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:
```json
{ "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:

```bash
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:
```json
{ "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:

```bash
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.
```json
{"success": true, "uuid": "12345678-1234-1234-1234-123456789abc"}
```

Export the replica UUID to use it in the next steps.
```bash
export REPLICA_UUID=copy_and_paste_the_uuid_returned_above
```

### 3. List replicas accessible by the user of your organization

```bash
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:
```json
{
  "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:
```bash
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"
```

> warn
> 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

```bash
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:
```json
{
  "success": true,
  "type": "array",
  "items": []
}
```


### 5. Chat with a replica

```bash
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:
```json
{
  "success": true,
  "content": "I don't have enough information to answer that question."
}
```

### 6. Retrieve the chat history again

```bash
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:
```json
{
  "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**

```bash
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:
```json
{
  "success": true,
  "results":[
    {
      "enqueued": true,
      "type":"text",
      "knowledgeBaseID":193377
    }
  ]
}
```

Export the knowledge base ID to use it in the next step:
```bash
export KNOWLEDGE_BASE_ID=12345
```
2. **Wait for your replica to be trained**

```bash
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:
```json
{
  "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`.

3. **Test your trained replica**

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

```bash
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:
```json
{
  "success": true,
  "content": "Our business hours are Monday to Friday, 9 AM to 5 PM Eastern Time."
}
```

> info
> The replica will now be able to answer questions based on the information you provided. For more advanced training options, see the [Training documentation](/topic/topic-in-depth-training).