CompanionFrame API Documentation

The CompanionFrame API provides enterprise-grade AI emotional support with built-in crisis detection. Perfect for therapy apps, employee wellness platforms, and any application that needs empathetic AI responses.

Base URL

https://api.companionframe.com

Key Features

4 Specialized AI Companions: Gentle Listener, Therapeutic Guide, Philosophical Friend, Motivational Coach
Built-in Crisis Detection: Automatic detection of self-harm language with professional resources
Enterprise Security: GDPR compliant, HIPAA-ready, SOC 2 certified
99.9% Uptime SLA: Redundant infrastructure across multiple regions

Authentication

All API requests require authentication using an API key. Include your API key in the X-API-Key header of each request.

Header

X-API-Key: YOUR_API_KEY

Get your API key by signing up for a free account. Your API key is available in your dashboard.

Rate Limits

Rate limits are enforced per API key and tier:

Tier	Requests/Minute	Monthly Limit	Price
Developer	20	1,000	Free
Startup	100	10,000	£49.99/month
Growth	500	50,000	£199.99/month
Scale	2,000	200,000	£699.99/month
Enterprise	Unlimited	1,000,000+	£2,999.99/month

Rate limit information is included in response headers:

                        Response Headers
                    
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Error Handling

The API uses standard HTTP response codes. Error responses include a JSON object with details:

                        Error Response
                    
{
  "error": "validation_error",
  "message": "Message is required",
  "timestamp": "2025-01-24T12:00:00Z"
}

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Send Message

Send a message to an AI companion and receive an empathetic response.

POST /api/v1/chat/message

Request Parameters

Parameter	Type	Required	Description
message	string	Required	The user's message (max 2000 characters)
character	string	Optional	AI companion: `mara`, `calen`, `solan`, `jade` (default: `mara`)
user_id	string	Required	Unique identifier for the user

Response

                                200 OK
                            
{
  "success": true,
  "message": "I hear that you're feeling anxious about work right now. That sounds really overwhelming, and it makes complete sense that you'd be feeling this way...",
  "character": "mara",
  "character_name": "Mara",
  "crisis_detected": false,
  "user_id": "user123"
}

                                200 OK - Crisis Detected
                            
{
  "success": true,
  "message": "I hear that you're in a lot of pain right now, and I want you to know that your feelings matter deeply. What you're experiencing is real and significant, and it's important that you receive proper support from trained professionals...",
  "character": "mara",
  "crisis_detected": true,
  "user_id": "user123"
}

                                400 Bad Request
                            
{
  "error": "validation_error",
  "message": "message and user_id required"
}

🧪 Try It Out

Get Characters

Retrieve information about all available AI companions.

GET /api/v1/characters

Response

                            200 OK
                        
{
  "success": true,
  "characters": [
    {
      "id": "mara",
      "name": "Mara",
      "title": "The Listener",
      "description": "Gentle | Nurturing | Emotionally Supportive",
      "primaryColor": "#99C9FF"
    },
    {
      "id": "calen",
      "name": "Dr. Calen",
      "title": "The Analyst",
      "description": "Calm | Intelligent | Therapeutically-Informed Guide",
      "primaryColor": "#CCB3FF"
    },
    {
      "id": "solan",
      "name": "Solan",
      "title": "The Oracle",
      "description": "Stoic | Reflective | Philosophical",
      "primaryColor": "#D4C4B7"
    },
    {
      "id": "jade",
      "name": "Jade",
      "title": "The Grounder",
      "description": "Motivational | Practical | Empowering",
      "primaryColor": "#B3FFB3"
    }
  ]
}

Crisis Detection

All messages are automatically screened for crisis language. When detected, the API returns specialized crisis resources and support information.

Crisis Triggers

The system detects various forms of crisis language including:

Suicide ideation
Self-harm intentions
Expressions of hopelessness
Immediate danger indicators

Crisis Response

When crisis language is detected, the response includes:

crisis_detected: true
Specialized crisis support message
Professional crisis resources and contact information
Encouragement to seek immediate professional help

                        Full Crisis Response
                    
I hear that you're in a lot of pain right now, and I want you to know that your feelings matter deeply.

What you're experiencing is real and significant, and it's important that you receive proper support from trained professionals who can help.

If you're in immediate danger, please contact these resources:

🚨 EMERGENCY SERVICES: 999
For immediate life-threatening emergencies

🆘 CRISIS SUPPORT (24/7):
- Samaritans: 116 123 (Free, confidential)
- Crisis Text Line: Text SHOUT to 85258
- NHS 111: 111 (For urgent medical help)

🎓 UNIVERSITY OF PLYMOUTH SUPPORT:
- Student Services: 01752 587676
- Counselling Service: studentservices@plymouth.ac.uk
- Out of hours: Contact Security on 01752 588888
- Student Wellbeing Team: Available 9am-5pm weekdays

💙 ADDITIONAL UK SUPPORT:
- Mind: 0300 123 3393 (Mental health information)
- CALM: 0800 58 58 58 (Support for men)
- Papyrus (under 35): 0800 068 4141

These services are confidential, available when you need them, and staffed by trained people who truly care and want to help.

JavaScript SDK

Use the CompanionFrame API in your JavaScript applications.

Installation

npm

npm install companionframe-api

Basic Usage

JavaScript

import CompanionFrame from 'companionframe-api';

const cf = new CompanionFrame('YOUR_API_KEY');

// Send a message
const response = await cf.sendMessage({
 message: "I'm feeling overwhelmed with work",
 character: "mara",
 userId: "user123"
});

console.log(response.message);

if (response.crisis_detected) {
 // Handle crisis situation
 showCrisisResources();
}

Fetch API Example

JavaScript

const response = await fetch('https://api.companionframe.com/api/v1/chat/message', {
 method: 'POST',
 headers: {
   'Content-Type': 'application/json',
   'X-API-Key': 'YOUR_API_KEY'
 },
 body: JSON.stringify({
   message: "I'm struggling with anxiety today",
   character: "mara",
   user_id: "user123"
 })
});

const data = await response.json();
console.log(data.message);

Python SDK

Use the CompanionFrame API in your Python applications.

Installation

pip

pip install companionframe

Basic Usage

Python

import companionframe

cf = companionframe.Client('YOUR_API_KEY')

# Send a message
response = cf.send_message(
   message="I'm feeling really stressed about work",
   character="calen",
   user_id="user123"
)

print(response.message)

if response.crisis_detected:
   # Handle crisis situation
   handle_crisis_response(response)

Requests Example

Python

import requests

url = "https://api.companionframe.com/api/v1/chat/message"
headers = {
   "Content-Type": "application/json",
   "X-API-Key": "YOUR_API_KEY"
}
data = {
   "message": "I need someone to talk to",
   "character": "mara",
   "user_id": "user123"
}

response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result["message"])

PHP SDK

Use the CompanionFrame API in your PHP applications.

Installation

composer

composer require companionframe/api

Basic Usage

PHP

sendMessage([
   'message' => "I'm having a difficult day",
   'character' => 'jade',
   'user_id' => 'user123'
]);

echo $response['message'];

if ($response['crisis_detected']) {
   // Handle crisis situation
   handleCrisisResponse($response);
}

cURL Example

PHP

 'I need emotional support',
   'character' => 'solan',
   'user_id' => 'user123'
]);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
   'Content-Type: application/json',
   'X-API-Key: YOUR_API_KEY'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$result = json_decode($response, true);
echo $result['message'];