Sensay

https://docs.sensay.io/
Admin
Sensay provides an API for managing conversational AI replicas, including features for analytics,...
Tokens:323,331
Snippets:1,460
Trust Score:8.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install and Build Generated SDK

Source: https://docs.sensay.io/topic/topic-generating-the-sdk

Installs the dependencies for the generated SDK and then builds the SDK project. This is typically done after the SDK has been generated in the specified output directory.

```bash
cd sensay-sdk
npm install
npm run build
```

--------------------------------

### Install HeyAPI CLI

Source: https://docs.sensay.io/topic/topic-generating-the-sdk

Installs the HeyAPI command-line interface tool, which is used for generating SDKs from OpenAPI specifications. This command is executed using npm.

```bash
npm install @heyapi/cli
```

--------------------------------

### User Information Response Example (JSON)

Source: https://docs.sensay.io/source

An example JSON response for the 'Get the current user' endpoint, illustrating the structure of user data including ID, email, name, and linked accounts.

```json
{
  "email": "user@example.com",
  "id": "johndoe",
  "linkedAccounts": [
    {
      "accountID": "12345",
      "accountType": "discord"
    }
  ],
  "name": "John Doe"
}
```

--------------------------------

### Sensay API List Conversations with Pagination (Bash)

Source: https://docs.sensay.io/topic/topic-pagination

Example of fetching a paginated list of conversations from the Sensay API using cURL. It demonstrates the use of 'page' and 'pageSize' query parameters and required headers.

```bash
curl -X GET "https://api.sensay.io/v1/replicas/{replicaUUID}/conversations?page=2&pageSize=20" \
  -H "X-ORGANIZATION-SECRET: $ORGANIZATION_SECRET" \
  -H "X-API-Version: $API_VERSION" \
  -H "Content-Type: application/json"
```

--------------------------------

### Get Knowledge Base Entry by ID (Beta)

Source: https://docs.sensay.io/group/endpoint-conversations

This example demonstrates how to retrieve a specific knowledge base entry using its unique ID via a GET request. It includes the endpoint, required parameters, and optional headers.

```http
GET /v1/training/{trainingID} HTTP/1.1
Host: api.sensay.io
X-API-Version: 2025-03-25
```

--------------------------------

### Sensay.io API Response Examples

Source: https://docs.sensay.io/operation/operation-post-v1-replicas-parameter-integrations-telegram

Provides examples of typical responses from the Sensay.io API, covering successful operations (200, 202) and various error scenarios (400, 401, 404, 415, 500). Each example includes relevant fields like success status, IDs, messages, and error details.

```json
{
  "success": true,
  "id": 42.0
}
```

```json
{
  "success": true,
  "id": 42.0,
  "message": "Telegram integration created successfully, but failed to notify the external integration server. If you are using the default Sensay Telegram Integration, we will retry starting the bot asynchronously."
}
```

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
```

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
```

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
```

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
```

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

--------------------------------

### Example API Response - Chat Completion

Source: https://docs.sensay.io/topic/topic-getting-started

An example JSON response after sending a message to a replica. It contains the replica's response content.

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

--------------------------------

### API Response Example (Success)

Source: https://docs.sensay.io/source

Example of a successful response when updating a knowledge base entry. It confirms the operation was successful.

```json
{
  "success": true
}
```

--------------------------------

### Clone Sensay Chat Client Sample Repository

Source: https://docs.sensay.io/topic/topic-tutorial-next-js

Clones the sample repository for building a chat application with the Sensay API using Git. This is the first step in setting up the project.

```Bash
git clone https://github.com/sensay-io/chat-client-sample.git
cd chat-client-sample
```

--------------------------------

### Sensay.io SDK: Create User, Replica, and Chat

Source: https://docs.sensay.io/topic/topic-generating-the-sdk

This TypeScript code demonstrates how to use the Sensay SDK to create a user, then create a replica for that user, and finally chat with the created replica. It includes configuration, API calls, and error handling.

```TypeScript
import { Configuration, DefaultApi } from './sensay-sdk';

// Configure the SDK with your organization secret and API version
const config = new Configuration({
  basePath: 'https://api.sensay.io',
  headers: {
    'X-ORGANIZATION-SECRET': 'your_secret_token',
    'X-API-Version': '2025-05-01',
    'Content-Type': 'application/json'
  }
});

// Initialize the API client
const api = new DefaultApi(config);

// Create a user
const createUser = async () => {
  try {
    const response = await api.createUser({
      id: 'test_user_id'
    });
    console.log('User created:', response);
    return response;
  } catch (error) {
    console.error('Error creating user:', error);
  }
};

// Create a replica for the user
const createReplica = async (userId: string) => {
  try {
    const response = await api.createReplica({
      name: 'My SDK Replica',
      shortDescription: 'Created with the generated SDK',
      greeting: 'Hello! I was created using a generated SDK.',
      ownerID: userId,
      private: false,
      slug: 'sdk-replica',
      llm: {
        provider: 'openai',
        model: 'gpt-4o'
      }
    });
    console.log('Replica created:', response);
    return response;
  } catch (error) {
    console.error('Error creating replica:', error);
  }
};

// Chat with a replica
const chatWithReplica = async (replicaUuid: string, userId: string) => {
  try {
    // Note: Headers are configured at the client level, but can be overridden per request
    const response = await api.chatCompletions(replicaUuid, {
      content: 'Hello, I'm using the generated SDK!'
    }, {
      headers: {
        'X-USER-ID': userId,
        'X-ORGANIZATION-SECRET': 'your_secret_token', 
        'X-API-Version': '2025-03-25',
        'Content-Type': 'application/json'
      }
    });
    console.log('Chat response:', response);
    return response;
  } catch (error) {
    console.error('Error chatting with replica:', error);
  }
};

// Example usage
const main = async () => {
  const user = await createUser();
  if (user && user.id) {
    const replica = await createReplica(user.id);
    if (replica && replica.uuid) {
      await chatWithReplica(replica.uuid, user.id);
    }
  }
};

main();

```

--------------------------------

### Get Current User API Response

Source: https://docs.sensay.io/group/endpoint-users

Example JSON response for the 'Get Current User' API endpoint, detailing the structure of user information returned, including email, ID, and linked accounts.

```json
{
  "email": "user@example.com",
  "id": "johndoe",
  "linkedAccounts": [
    {
      "accountID": "string",
      "accountType": "discord"
    }
  ],
  "name": "John Doe"
}
```

--------------------------------

### Run Next.js Development Server

Source: https://docs.sensay.io/topic/topic-tutorial-next-js

Starts the Next.js development server, allowing you to view and interact with the chat application locally. The application will be accessible at http://localhost:3000.

```Shell
npm run dev
```

--------------------------------

### Get Mentions - Success Response (200)

Source: https://docs.sensay.io/operation/operation-get-v1-replicas-parameter-conversations-parameter-mentions

Example of a successful response (200 OK) from the Sensay API when retrieving mentions. It includes a list of messages, sender information, and pagination details.

```json
{
  "success": true,
  "items": [
    {
      "type": "mention",
      "messages": [
        {
          "uuid": "03db5651-cb61-4bdf-9ef0-89561f7c9c53",
          "createdAt": "2024-09-24T09:09:55.66709+00:00",
          "content": "Hello world!",
          "role": "user",
          "senderName": "John Doe",
          "senderProfileImageURL": "https://example.com/avatar.png",
          "source": "web",
          "replicaUUID": "03db5651-cb61-4bdf-9ef0-89561f7c9c53"
        }
      ]
    }
  ],
  "hasMore": true
}
```

--------------------------------

### Example API Response - List Replicas

Source: https://docs.sensay.io/topic/topic-getting-started

An example JSON response when listing replicas accessible by a user. It includes details such as replica UUID, name, description, and creation timestamp.

```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
}
```

--------------------------------

### Get Mentions - Unauthorized Response (401)

Source: https://docs.sensay.io/operation/operation-get-v1-replicas-parameter-conversations-parameter-mentions

Example of an unauthorized response (401) from the Sensay API, typically due to invalid or missing authentication credentials. Includes error details and a request ID.

```json
{
  "success": false,
  "error": "A text representation of the error",
  "fingerprint": "string",
  "request_id": "string"
}
```

--------------------------------

### Install Dependencies with npm

Source: https://docs.sensay.io/topic/topic-tutorial-next-js

Installs the necessary project dependencies using npm after cloning the repository. This command ensures all required packages are available for the Next.js application.

```Shell
npm install
```

--------------------------------

### Create Replicas (POST)

Source: https://docs.sensay.io/changes/270ddd84

Creates a new replica. No specific parameters are detailed in this snippet.

```HTTP
POST /v1/replicas
```

--------------------------------

### Get Mentions - Bad Request Response (400)

Source: https://docs.sensay.io/operation/operation-get-v1-replicas-parameter-conversations-parameter-mentions

Example of a bad request response (400) from the Sensay API, indicating an issue with the request parameters. Includes error details and a request ID.

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
```

--------------------------------

### Get Current User API Response

Source: https://docs.sensay.io/operation/operation-get-v1-users-me

Provides an example of a successful JSON response when fetching current user details from the Sensay API. The response includes user's email, ID, and linked accounts.

```json
{
  "email": "user@example.com",
  "id": "johndoe",
  "linkedAccounts": [
    {
      "accountID": "string",
      "accountType": "discord"
    }
  ],
  "name": "John Doe"
}
```

--------------------------------

### Configure Suggested Questions

Source: https://docs.sensay.io/source

Provides a list of suggested questions to initiate conversations with the replica. Defaults to an empty list.

```YAML
suggestedQuestions:
  type: array
  items:
    type: string
  default: []
  description: Suggested questions when starting a conversation.
  example:
  - What is the meaning of life?
```

--------------------------------

### Manage Replicas: List or Create Replica

Source: https://docs.sensay.io/topic/topic-tutorial-next-js

This function retrieves a list of replicas for a user. If no replicas are found, it creates a new sample replica with specified configurations, including name, description, greeting, and LLM settings. Otherwise, it returns the UUID of the first available replica.

```JavaScript
const replicas = await userClient.replicas.listReplicasGet();

if (replicas.items.length === 0) {
  // Create a new replica if none exists
  const newReplica = await userClient.replicas.createReplicaPost({
    name: `Sample Replica ${Date.now()}`,
    shortDescription: 'A helpful assistant for demonstration purposes',
    greeting: 'Hello! I am a sample replica. How can I help you today?',
    ownerID: userId,
    private: false,
    slug: `sample-replica-${Date.now()}`,
    llm: {
      provider: 'openai',
      model: 'gpt-4o',
    },
  });
  return newReplica.uuid;
}

// Use the first available replica
return replicas.items[0].uuid;
```

--------------------------------

### Get User by ID Response (404) - Sensay API

Source: https://docs.sensay.io/operation/operation-get-v1-users-parameter

Example JSON response when a user is not found (HTTP 404). It indicates the request status, provides an error message, and includes a request ID and fingerprint for tracking.

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
```

--------------------------------

### Example User Creation Response

Source: https://docs.sensay.io/index

An example JSON response after successfully creating a user. It includes the user's ID and an empty array for linked accounts.

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

--------------------------------

### API Request Header Example

Source: https://docs.sensay.io/operation/operation-post-v1-experimental-replicas-parameter-chat-completions

This snippet shows an example of the required X-API-Version header for Sensay.io API requests. This header specifies the version of the API being used for the request.

```http
# Headers
X-API-Version: 2025-03-25
```

--------------------------------

### Get User by ID Response (200) - Sensay API

Source: https://docs.sensay.io/operation/operation-get-v1-users-parameter

Example JSON response for a successful retrieval of user information (HTTP 200). It includes the user's email, ID, and a list of linked accounts with their respective types.

```json
{
  "email": "user@example.com",
  "id": "johndoe",
  "linkedAccounts": [
    {
      "accountID": "string",
      "accountType": "discord"
    }
  ],
  "name": "John Doe"
}
```

--------------------------------

### POST Request to Train Replica

Source: https://docs.sensay.io/operation/operation-post-v1-replicas-parameter-training

Initiates the training process for a replica by creating a knowledge base entry. Requires an API key and version header. The response indicates success or provides error details.

```curl
curl \
 --request POST 'https://api.sensay.io/v1/replicas/03db5651-cb61-4bdf-9ef0-89561f7c9c53/training' \
 --header "X-ORGANIZATION-SECRET: $API_KEY" \
 --header "X-API-Version: 2025-03-25"
```

--------------------------------

### Get Current User API Request

Source: https://docs.sensay.io/operation/operation-get-v1-users-me

Demonstrates how to retrieve information about the currently authenticated user using the Sensay API. It includes the necessary cURL command with headers for authentication and API versioning, along with an example JSON response.

```bash
curl \
 --request GET 'https://api.sensay.io/v1/users/me' \
 --header "X-ORGANIZATION-SECRET: $API_KEY" \
 --header "X-USER-ID: $API_KEY" \
 --header "X-API-Version: 2025-03-25"
```

--------------------------------

### Configure Sensay API Key using .env.local

Source: https://docs.sensay.io/topic/topic-tutorial-next-js

Sets up the Sensay API key for the Next.js application by creating a .env.local file in the project root. This is the recommended method for development environments.

```Shell
NEXT_PUBLIC_SENSAY_API_KEY=your_api_key_here
```

--------------------------------

### Generate Signed URL for File Upload (curl)

Source: https://docs.sensay.io/topic/topic-pagination

This snippet demonstrates how to request a signed URL from the Sensay API for uploading files. It includes the necessary GET request, endpoint, query parameters for the filename, and the required authentication header.

```curl
curl \
 --request GET 'https://api.sensay.io/v1/replicas/03db5651-cb61-4bdf-9ef0-89561f7c9c53/training/files/upload?filename=company_handbook.pdf' \
 --header "X-ORGANIZATION-SECRET: $API_KEY"
```

--------------------------------

### Generate Signed URL for File Upload (cURL)

Source: https://docs.sensay.io/topic/topic-generating-the-sdk

This snippet demonstrates how to request a signed URL from the Sensay API to upload a file. It includes the necessary GET request, endpoint, query parameters for the filename, and the required authentication header.

```bash
curl \
 --request GET 'https://api.sensay.io/v1/replicas/03db5651-cb61-4bdf-9ef0-89561f7c9c53/training/files/upload?filename=company_handbook.pdf' \
 --header "X-ORGANIZATION-SECRET: $API_KEY"
```

--------------------------------

### Create Replica Training (POST /v1/replicas/{replicaUUID}/training)

Source: https://docs.sensay.io/changes/83b2fd5c

This entry represents the POST /v1/replicas/{replicaUUID}/training endpoint. No specific changes are detailed, but its presence indicates an available operation.

```HTTP
POST /v1/replicas/{replicaUUID}/training
```

--------------------------------

### Create a User in Sensay API

Source: https://docs.sensay.io/topic/topic-getting-started

Demonstrates how to create a new user within an organization using the Sensay API. It shows a cURL request with necessary headers including organization secret and API version, and an example JSON payload for the user ID. It also includes an example of the API's response.

```curl
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'"}'
```

--------------------------------

### Fetch Source Analytics

Source: https://docs.sensay.io/topic/topic-in-depth-conversations

Retrieves conversation source analytics for a given replica. It makes a GET request to the /v1/replicas/{replicaUUID}/analytics/conversations/sources endpoint. The function handles response checking and returns the parsed JSON data. It also includes example usage for calculating source percentages.

```JavaScript
async function getSourceAnalytics(replicaUUID) {
  const response = await fetch(
    `/v1/replicas/${replicaUUID}/analytics/conversations/sources`,
    {
      headers: {
        'X-ORGANIZATION-SECRET': process.env.ORGANIZATION_SECRET,
        'X-API-Version': '2025-03-25',
        'Content-Type': 'application/json'
      }
    }
  );

  if (!response.ok) {
    throw new Error(`Analytics request failed: ${response.status}`);
  }

  return response.json();
}

// Usage
const { items: sources } = await getSourceAnalytics('f0e4c2f7-ae27-4b35-89bf-7cf729a73687');

// Calculate percentages
const totalConversations = sources.reduce((sum, source) => sum + source.conversations, 0);
const sourcePercentages = sources.map(source => ({
  ...source,
  percentage: ((source.conversations / totalConversations) * 100).toFixed(1)
}));
```

--------------------------------

### Add GET /v1/training and GET /v1/training/{trainingID}

Source: https://docs.sensay.io/changes_page=3

Two new endpoints, GET /v1/training and GET /v1/training/{trainingID}, have been added.

```HTTP
GET /v1/training
GET /v1/training/{trainingID}
```

--------------------------------

### Create Knowledge Base Entry - POST Request

Source: https://docs.sensay.io/operation/operation-post-v1-replicas-parameter-training

Creates a new knowledge base entry for a replica, initiating the text-based training process. This endpoint requires the replica's UUID and returns a knowledgeBaseID for subsequent content updates. The entry status begins as BLANK and is processed upon content addition.

```OpenAPI
{
  "openapi": "3.0.0",
  "info": {
    "title": "Sensay API",
    "version": "1.0.0"
  },
  "paths": {
    "/v1/replicas/{replicaUUID}/training": {
      "post": {
        "summary": "Create a knowledge base entry",
        "description": "Creates a new empty knowledge base entry for a replica. This is the first step in the text-based training process. After creating the entry, you'll receive a knowledgeBaseID that you'll need to use in the next step to add your training content using the Update endpoint. The entry starts with a BLANK status and will be processed automatically once you add content.",
        "parameters": [
          {
            "name": "replicaUUID",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "X-API-Version",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "default": "2025-03-25"
          }
        ],
        "responses": {
          "200": {
            "description": "Knowledge base entry created successfully"
          }
        }
      }
    }
  }
}
```

--------------------------------

### Add GET /v1/validation/param/{uuid}, GET /v1/validation/query, POST /v1/validation/json

Source: https://docs.sensay.io/changes_page=5

This snippet documents the addition of three new endpoints: GET /v1/validation/param/{uuid}, GET /v1/validation/query, and POST /v1/validation/json. These are noted as additions to the API.

```text
GET /v1/validation/param/{uuid}
GET /v1/validation/query
POST /v1/validation/json
```

--------------------------------

### Train Replicas (POST)

Source: https://docs.sensay.io/changes/270ddd84

Initiates training for a replica. Requires the replicaUUID in the path.

```HTTP
POST /v1/replicas/{replicaUUID}/training
```

--------------------------------

### Create Knowledge Base Entry (POST)

Source: https://docs.sensay.io/group/endpoint-training

This snippet demonstrates how to create a new knowledge base entry using the Sensay API. It includes the necessary cURL command with headers for authentication and API versioning, along with example JSON responses for success (200) and various error conditions (400, 401, 404, 415, 500).

```bash
curl \
 --request POST 'https://api.sensay.io/v1/replicas/03db5651-cb61-4bdf-9ef0-89561f7c9c53/training' \
 --header "X-ORGANIZATION-SECRET: $API_KEY" \
 --header "X-API-Version: 2025-03-25"
```

--------------------------------

### Remove GET /v1, /v1/replica, and /v1/replica/{replicaUUID}/chat endpoints

Source: https://docs.sensay.io/changes_page=6

This snippet details breaking changes involving the removal of three API endpoints: GET /v1, GET /v1/replica, and GET /v1/replica/{replicaUUID}/chat.

```HTTP
GET /v1
```

```HTTP
GET /v1/replica
```

```HTTP
GET /v1/replica/{replicaUUID}/chat
```

--------------------------------

### Breaking Changes: GET /v1/validation/param/{uuid}, GET /v1/validation/query, POST /v1/validation/json

Source: https://docs.sensay.io/changes_page=5

This snippet highlights breaking changes due to the removal of resources. It specifically lists GET /v1/validation/param/{uuid}, GET /v1/validation/query, and POST /v1/validation/json as removed and breaking.

```text
GET /v1/validation/param/{uuid}
GET /v1/validation/query
POST /v1/validation/json
```

--------------------------------

### Knowledge Base Entry Creation Responses

Source: https://docs.sensay.io/group/endpoint-training

Provides example JSON responses for the POST /v1/replicas/{replicaUUID}/training endpoint. It covers the structure of a successful creation (200) and various error responses (400, 401, 404, 415, 500), including details about error messages, request IDs, and inner exceptions for server errors.

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

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
```

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
```

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

--------------------------------

### Sensay API File Upload Responses (JSON)

Source: https://docs.sensay.io/topic/topic-generating-the-sdk

Provides examples of JSON responses from the Sensay API for file upload operations. It covers successful uploads (200) with signed URLs and knowledge base IDs, as well as error responses (400, 401, 404, 415, 500) with detailed error messages and request identifiers.

```json
{
  "success": true,
  "signedURL": "https://storage.googleapis.com/replica_files/",
  "knowledgeBaseID": 12345
}
```

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab",
  "fingerprint": "14fceadd84e74ec499afe9b0f7952d6b"
}
```

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
```

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

--------------------------------

### Create Replica using Sensay API

Source: https://docs.sensay.io/operation/operation-post-v1-replicas

This snippet demonstrates how to create a replica using the Sensay API via a `curl` command. It includes the necessary headers and a JSON payload with replica configuration details. The response section details the expected output for successful creation (201) and various error scenarios (400, 401, 404, 409, 415, 500).

```bash
curl \
 --request POST 'https://api.sensay.io/v1/replicas' \
 --header "X-ORGANIZATION-SECRET: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "X-API-Version: 2025-03-25" \
 --data '{"name":"John Smith","purpose":"Acts as my AI twin for answering questions about my creative work.","shortDescription":"Accountant from Brooklyn who loves sports.","greeting":"What would you like to know?","type":"character","ownerID":"a-user-id","private":false,"whitelistEmails":["user@domain.example"],"slug":"example-replica","tags":["male","italian"],"profileImage":"https://images.invalid/photo.jpeg","suggestedQuestions":["What is the meaning of life?"],"llm":{"model":"gpt-4o","memoryMode":"rag-search","systemMessage":"Concise, knowledgeable, empathetic and cheerful.","tools":["getTokenInfo"]},"voicePreviewText":"Hi, I\'m your Sensay replica! How can I assist you today?","isAccessibleByCustomerSupport":true,"isEveryConversationAccessibleBySupport":true,"isPrivateConversationsEnabled":false,"introductionAudioID":"intro_audio_123"}'
```

--------------------------------

### Get Replica (GET /v1/replicas/{replicaUUID})

Source: https://docs.sensay.io/changes/83b2fd5c

The GET /v1/replicas/{replicaUUID} endpoint is marked as a breaking change. Removing a resource is generally considered breaking unless it was previously deprecated.

```HTTP
GET /v1/replicas/{replicaUUID}
```

--------------------------------

### Not Found Response (404)

Source: https://docs.sensay.io/operation/operation-post-v1-replicas-parameter-training

Example of a not found response. Indicates that the requested resource could not be found. Includes a success status, error message, and request ID.

```json
{
  "error": "A text representation of the error",
  "success": false,
  "request_id": "xyz1::reg1:reg1::ab3c4-1234567890123-0123456789ab"
}
```

--------------------------------

### API Request Header Example

Source: https://docs.sensay.io/group/endpoint-experimental

This snippet shows an example of the required X-API-Version header for Sensay.io API requests. This header specifies the version of the API being used for the request.

```http
# Headers
X-API-Version: 2025-03-25
```

--------------------------------

### Add Error Responses to User Endpoints

Source: https://docs.sensay.io/changes_page=4

This change adds several error responses (400, 401, 404, 415, 500) to multiple GET and POST endpoints related to users and replicas. This includes modifications to DELETE /v1/users/me, GET /v1/replicas, GET /v1/replicas/{replicaUUID}/chat/history, GET /v1/replicas/{replicaUUID}/chat/history/{source}, GET /v1/users/me, POST /v1/replicas/{replicaUUID}/chat/completions, and POST /v1/users.

```HTTP
DELETE /v1/users/me
```

```HTTP
GET /v1/replicas
```

```HTTP
GET /v1/replicas/{replicaUUID}/chat/history
```

```HTTP
GET /v1/replicas/{replicaUUID}/chat/history/{source}
```

```HTTP
GET /v1/users/me
```

```HTTP
POST /v1/replicas/{replicaUUID}/chat/completions
```

```HTTP
POST /v1/users
```

--------------------------------

### GET /v1/replicas/{replicaUUID} - Get Replica Endpoint

Source: https://docs.sensay.io/changes_page=1

The GET /v1/replicas/{replicaUUID} endpoint has been modified. The removal of a resource is considered a breaking change unless it was previously deprecated.

```HTTP
GET /v1/replicas/{replicaUUID}
```

--------------------------------

### Successful Training Response (200)

Source: https://docs.sensay.io/operation/operation-post-v1-replicas-parameter-training

Example of a successful response when a knowledge base entry is created. Includes a success status and the unique identifier for the new entry.

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

--------------------------------

### Sensay API: Add introductionAudioID to GET /v1/replicas

Source: https://docs.sensay.io/changes

This snippet details the addition of the 'introductionAudioID' property to the response of the GET /v1/replicas endpoint. It also notes modifications to the GET /v1/replicas/{replicaUUID} response.

```json
GET /v1/replicas
  Response modified: 200
    Content type modified: application/json
      Property modified: items
        Property added: introductionAudioID
Modified: GET /v1/replicas/{replicaUUID}
  Response modified: 200
    Content type modified: application/json
      Property added: introductionAudioID
```

--------------------------------

### Create Knowledge Base Entry (Sensay API)

Source: https://docs.sensay.io/group/endpoint-training

Creates a new knowledge base entry for a replica, initiating the text-based training process. This endpoint requires the replica's UUID and returns a knowledgeBaseID for subsequent content updates. The entry status starts as BLANK and is processed upon content addition.

```OpenAPI
{
  "summary": "Creates a new empty knowledge base entry for a replica. This is the first step in the text-based training process. After creating the entry, you'll receive a knowledgeBaseID that you'll need to use in the next step to add your training content using the Update endpoint. The entry starts with a BLANK status and will be processed automatically once you add content.",
  "operationId": "createKnowledgeBaseEntry",
  "parameters": [
    {
      "name": "X-API-Version",
      "in": "header",
      "schema": {
        "type": "string",
        "default": "2025-03-25"
      }
    },
    {
      "name": "replicaUUID",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "responses": {},
  "tags": [
    "Training"
  ],
  "description": "Creates a new knowledge base entry for a replica.",
  "method": "POST",
  "path": "/v1/replicas/{replicaUUID}/training",
  "security": [
    {
      "organizationServiceToken": []
    }
  ]
}
```

--------------------------------

### Get Replica Details (GET)

Source: https://docs.sensay.io/changes/270ddd84

Retrieves details for a specific replica. Requires the replicaUUID in the path.

```HTTP
GET /v1/replicas/{replicaUUID}
```

--------------------------------

### Get Replica Messages (GET /v1/replicas/{replicaUUID}/conversations/{conversationUUID}/messages)

Source: https://docs.sensay.io/changes/83b2fd5c

The GET /v1/replicas/{replicaUUID}/conversations/{conversationUUID}/messages endpoint is marked as a breaking change. Removing a resource is generally considered breaking unless it was previously deprecated.

```HTTP
GET /v1/replicas/{replicaUUID}/conversations/{conversationUUID}/messages
```

--------------------------------

### Successful Response Example (200 OK)

Source: https://docs.sensay.io/operation/operation-get-v1-training

Example of a successful response (HTTP 200) when listing knowledge base entries. It confirms the operation's success and provides an array of training data items, detailing their properties.

```json
{
  "success": true,
  "items": [
    {
      "id": 12345,
      "type": "text",
      "title": "Company Information",
      "status": "READY",
      "filename": null,
      "raw_text": "Our company was founded in 2020...",
      "created_at": "2025-04-15T08:11:00.093761+00:00",
      "updated_at": "2025-04-15T08:11:05.299349+00:00"
    }
  ]
}
```
Tokens:
Raw