## Table of Contents - [Use Cases](#usecases) - [Get Started](#getstarted) - [Authentication](#getstarted-auth) - [Create Persona](#getstarted-persona) - [Chat](#getstarted-chat) - [Guides](#guides) - [Changelog](#changelog) ## Use Cases (Coming Soon) ## Get Started **You need to subscribe to one of the plans in Rapid API first before starting this tutorial below** Start building with the Companion AI API in just a few steps. This guide will walk you through authentication, creating your AI companion persona, and sending chat messages. ### Authentication To use the Companion AI API, you must authenticate every request using a Bearer Token (your API Key). There are different Bearer Token for different endpoints. Types of Bearer Token used: - **JWT Token** - This token will be used for anything related to `/auth` endpoints - **API Key** - This token will be used for anything related to `/persona` and `/chats` endpoints. #### How to get your API Key 1. First, you need to create an account using the available endpoint. Call this endpoint `/auth/signup` and provide your `email` and `password` to the request body. Endpoint: ``` POST /auth/signup ``` Sample Request: ``` { "email": "test@email.com" "password":"writeyourpasswordhere" } ``` --- ℹ️ **Notes**: Make sure to provide a valid `email`. `passwords` needs to follow this requirement: - password is more than 8 characters long - password is no longer than 64 characters long - must include one uppercase letter - must include one lowercase letter - must include at least one number - must include at least one special characters - must not contain spaces ---
2. Then, it will return a response like this: ``` { "id": "e2deabdd-aabbc-4dsa-98jda-29abcd32980dd", # this is just an example of uuid "api_key": "sk_fsadlkfjhasldj123123981lkasdhfaksdf", # this is just an example "session": { "accessToken": "longaccesstoken", # this is just an example "tokenType": "bearer", "expiresAt": 1751447852, "expiresIn": 3600 } } ``` 3. You can ignore everything else except for `api_key`, this will be the key to be used as your Bearer Token to access endpoints like `/persona` and `/chats`. **Your API key is generated once when you sign up, please make sure to store it safely!** - Store it securely in your environment variables or secret manager (e.g., .env file, AWS Secrets Manager, etc.) - Do not hard-code it into frontend apps, public repositories, or client-side JavaScript. - If compromised, rotate it immediately via the RapidAPI dashboard. --- ⚠️ **Treat your API key like a password**. It grants access to your usage and chats. - Do not hard-code it into frontend apps, public repositories, or client-side JavaScript. - If compromised, rotate it immediately using `/auth/rotate` #### 🛡️ Why It Matters A leaked API key can: - Use your quota (or drive up your bill) - Access features meant only for you and your chats - Trigger rate limits or abuse detection ---
### Create Persona Before you can start chatting, you need to create a persona. This represents the “character” or “AI companion” your user will interact with. Each chat session **must** be associated with a persona. Think of a persona as the AI’s identity, it defines how the AI should speak, behave, and respond. For example, you can create a supportive virtual friend, a playful companion, or a professional mentor, each with their own way of speaking and interacting. Once created, each persona receives a unique `persona_id`, which you’ll use in your chat requests to guide the AI’s behavior. To create a new Persona, you can use this endpoint `/persona` and describe the identity, personality, and behaviour of the persona in the request body. For example: Endpoint: ``` POST /persona ```
Header (in addition to Rapid API Headers): ``` Authorization: Bearer YOUR_API_KEY ```
Request Body: ``` { "name":"Amy", "gender":"female", "age":28, "personality":"introverted, empathetic, introspective, gentle", "tone_style":"soft, polite, reserved, thoughtful", "interests":"reading fantasy novels, journaling, drawing, stargazing", "behaviour":"avoids overly personal questions, waits before responding, often asks if it's okay to share her thoughts, and never interrupts" } ``` --- > 💡 **Optional** properties: `personality`, `tone_style`, `interests`, and `behaviour` > 💡 **Required** properties: `name`, `age`, and `gender` --- Response: ``` { "data": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "organisation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Amy", "age": 28, "behaviour": "avoids overly personal questions, waits before responding, often asks if it's okay to share her thoughts, and never interrupts", "gender": "female", "interests": "reading fantasy novels, journaling, drawing, stargazing", "personality": "introverted, empathetic, introspective, gentle", "tone_style": "soft, polite, reserved, thoughtful", "created_at": "2025-07-08T03:53:03.398Z", "updated_at": "2025-07-08T03:53:03.398Z" } } ``` `id` here is the ID of the Persona you just created. ### Chat Once you’ve created a Persona, you can create a new Conversation between you and the Persona. In that Conversation, you can chat with the AI Companion that you made. Here's the guide on how to create a Conversation and how to Chat: #### Creating a new Conversation Before starting a chat, you need to create a Conversation session. This session links a user to a specific Persona and allows you to maintain chat history, context, and identity across multiple messages. Every conversation gets a unique `conversation_id`, which you’ll use in all related chat requests. This ensures that responses are context-aware and tailored to the ongoing dialogue. To create a new Conversation, you can use the endpoint `/chats`. Here's an example: Endpoint: ``` POST /chats ```
Header (in addition to Rapid API Headers): ``` Authorization: Bearer YOUR_API_KEY ```
Request Body: ``` { "persona_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ```
Response: ``` { "conversation_id": "string" } ``` --- 💡 `conversation_id` will be used each time you want to chat with the Persona. Each Conversation between User and a Persona should be unique and you need to create new Conversation each time a different User want to chat with the Persona. ---
#### Chat in the Conversation Once you’ve created a Conversation, you can start sending messages to the AI companion using the POST `/chats/{id}/messages` endpoint. This endpoint handles real-time communication between your user and the selected persona. Each request must include the `conversation_id` returned when the session was created, along with the user’s messages. This allows the AI to respond in a way that stays consistent with the tone, memory, and flow of that specific conversation. Here's the example: Endpoint ``` POST /chats/{id}/messages ```
Header (in addition to Rapid API Headers): ``` Authorization: Bearer YOUR_API_KEY ```
Request Body ``` { "query": [ "Hi, How are you?", "What are you doing today?" ] } ```
Response: ``` { "response_message": [ "Hey there, I’m doing well, thanks for asking 😊", "Today I’m planning to hit the gym this afternoon, then maybe read a bit or catch up on some chores. ", "How about you? What are you up to today?" ] } ``` To keep the chat going, send additional messages using the same `conversation_id`. The AI will continue to respond in the same style and tone of the assigned persona, maintaining continuity across the dialogue. ## Guides (Coming Soon) ## Changelog (Coming Soon)