Complete reference for integrating with the AFFECTIVELY REST API
All API requests should be made to:
https://affectively.com/apiThe AFFECTIVELY API uses Firebase Authentication. Include your Firebase Auth token in the Authorization header:
Authorization: Bearer YOUR_FIREBASE_AUTH_TOKENTo obtain a Firebase Auth token, authenticate through the AFFECTIVELY web application or use the Firebase SDK.
Rate limits are enforced per subscription tier to ensure fair usage and system stability. All rate limits are applied per user (identified by Firebase Auth token). Limits are calculated to maintain sustainable service costs while providing reasonable usage allowances.
Rate limits are enforced at three levels: per minute, per hour, and per day. The most restrictive limit applies. Daily limits are the primary control for monthly usage.
Premium subscription: $9.99/month
Ultra-Premium subscription: $29.99/month
For enterprise API access, contact us for pricing
Rate limits are enforced at three time windows simultaneously. All three limits must be satisfied:
If you exceed any limit, you'll receive a 429 error. The daily limit is typically the most restrictive for normal usage patterns.
Every API response includes rate limit information in the response headers:
X-RateLimit-Limit: Your tier's limitX-RateLimit-Remaining: Remaining requests in the current windowX-RateLimit-Reset: Unix timestamp when the limit resetsRetry-After: Seconds to wait before retrying (when rate limited)When you exceed your rate limit, you'll receive a 429 Too Many Requests response:
{
"error": "Rate limit exceeded",
"message": "You have exceeded the rate limit for your subscription tier...",
"rateLimit": {
"limit": 5,
"remaining": 0,
"resetAt": "2024-01-15T10:31:00.000Z"
}
}Wait until the reset time before making additional requests. Consider upgrading your subscription tier for higher limits.
All requests should:
Content-Type: application/json header for POST requestsAll responses:
/api/emotionsList all emotions with optional filtering. No authentication required.
Query Parameters:
level: 'primary' | 'secondary' | 'tertiary' | 'all' (default: 'all')valence: 'positive' | 'negative' | 'neutral'arousal: 'low' | 'moderate' | 'high'ekmanCategory: Filter by Ekman categorysearch: Text search in name/descriptionGET https://affectively.com/api/emotions?level=primary&valence=positive/api/emotions/hierarchyGet the complete emotion hierarchy (primary → secondary → tertiary). No authentication required.
/api/emotions/[id]Get details for a specific emotion by ID. No authentication required.
/api/text/analyzeRequires AuthAnalyzes text for emotions and infers psychological profiles. Requires API subscription tier.
Request Body:
{
"text": "string",
"options": {
"includeFullAIC": boolean
}
}Response:
TextAnalysisResponse with emotions, CVM facts, psychological profile/api/aic/analyzeRequires AuthClient-agnostic API for Affective Intelligence System. Accepts AffectInput and returns AffectOutput. Requires API subscription tier.
Request Body:
AffectInput schema (validated via Zod)Response:
AffectOutput with Low-Entropy Label and Adaptive Lever/api/agent/chatRequires AuthUltra-PremiumStreaming chat endpoint for interacting with an AI agent that has access to MCP tools. The agent can analyze emotions, text, and provide psychological insights using the Affective Intelligence Companion system. Requires Ultra-Premium subscription or admin access.
Request Body:
{
"messages": [
{
"role": "user" | "assistant" | "system",
"content": "string"
}
],
"conversationId": "string" // Optional: for resuming conversations
}Response:
Streaming response using AI SDK data stream format. The agent can autonomously call MCP tools during the conversation:
analyze_affect - Analyze affective statesanalyze_text - Analyze text for emotions and psychological insightsget_emotions - Query emotion taxonomygenerate_repartee - Generate strategic repartee (Ultra-Premium)generate_visual_repartee - Analyze images and generate responses (Ultra-Premium)Note:
This endpoint uses Server-Sent Events (SSE) for streaming. Use the AI SDK's useChat hook or handle the stream manually. Tool invocations are included in the stream.
All errors follow a consistent format:
{
"error": "Error type",
"message": "Human-readable error message",
"details": {} // Optional additional error details
}Invalid request format or validation failed
Missing or invalid authentication token
Valid token but insufficient subscription tier
Rate limit exceeded (see Rate Limiting section)
Server-side error occurred
const response = await fetch('https://affectively.com/api/text/analyze', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${firebaseAuthToken}`
},
body: JSON.stringify({
text: 'I feel anxious about the upcoming presentation.'
})
});
const data = await response.json();
console.log('Remaining requests:', response.headers.get('X-RateLimit-Remaining'));import requests
response = requests.post(
'https://affectively.com/api/text/analyze',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {firebase_auth_token}'
},
json={
'text': 'I feel anxious about the upcoming presentation.'
}
)
data = response.json()
print(f"Remaining requests: {response.headers.get('X-RateLimit-Remaining')}")curl -X POST 'https://affectively.com/api/text/analyze' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_FIREBASE_AUTH_TOKEN' \
-d '{
"text": "I feel anxious about the upcoming presentation."
}'For AI agent integration, see our MCP Server Technical Documentation.
Need help? Visit our Contact page for support.
To access authenticated endpoints, you'll need an API subscription. See Pricing for details.