BetterSpace Developer API

Integrate mental health and wellness services into your platform with a simple REST API. Per-user pricing, no base fees.

API Modules

40+

Endpoints

₹10-60

Per User/Month

# Quick test with your API key
curl -H "Authorization: Bearer <anon_key>" \
     -H "X-API-Key: bs_test_your_key" \
     https://database.betterspace.care/functions/v1/api-gateway/v1/assessments/types

Prerequisites

Before making API calls, complete these steps in order:

Create a Developer Account

Subscribe to Modules

Go to Dashboard → Modules and subscribe to the features you need. Each module unlocks specific API endpoints. You can only call endpoints for modules you're subscribed to.

Generate an API Key

Go to Dashboard → API Keys and create a key. Start with a sandbox key for testing (free, unlimited). Create a live key when ready for production.

Copy the key immediately — it's only shown once.

Call POST /v1/users/register with the user's email and your external ID. The API automatically:

Finds an existing BetterSpace profile by email and links it
Or creates a new BetterSpace account and links it

No manual linking needed. One API call does everything.

POST /v1/users/register
{
  "external_id": "emp-001",
  "email": "priya@company.com",
  "name": "Priya Sharma"
}

Use Your External IDs in API Calls

Once registered, use the external_id in all subsequent API calls. The gateway resolves it automatically.

POST /v1/mood/log
{
  "user_id": "emp-001",
  "mood_value": 4
}

Test in the Playground

Go to Dashboard → API Playground, paste your API key, and test endpoints live. The playground shows real responses from the API.

Authentication

All API requests go through the Supabase Edge Function gateway. You need two headers:

# Required headers for every request
Authorization: Bearer <supabase_anon_key>
X-API-Key: bs_live_your_api_key

# The anon key authenticates with Supabase
# The X-API-Key identifies your tenant account

Key Prefixes: bs_live_ for production (billed), bs_test_ for sandbox (free, unlimited).

Base URL

https://database.betterspace.care/functions/v1/api-gateway

All endpoint paths are appended to this base. E.g., /v1/assessments/types

Users & Linking

Before using most endpoints, register your users with their external IDs from your system. Then link them to BetterSpace profiles.

1. Register a user (in the portal UI)

Go to Dashboard → Users → Add User. Enter their external ID (e.g., emp-001).

2. Link to BetterSpace profile

Click "Link" on the user row and search for their BetterSpace profile by name or email. This maps your external ID to their internal UUID.

3. Use in API calls

{
  "user_id": "emp-001",  // Your external ID
  "mood_value": 4,
  "activities": ["work", "exercise"]
}

The gateway automatically resolves emp-001 to the linked BetterSpace UUID.

Rate Limits

Window	Default Limit
Per minute	60 requests
Per hour	1,000 requests
Per day	10,000 requests

Check X-RateLimit-Remaining header. Enterprise plans get higher limits.

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "code": "module_not_subscribed",
    "message": "Your account does not have access to this module.",
    "status": 403
  }
}

Code	Status	Meaning
missing_api_key	401	No X-API-Key header
invalid_api_key	401	Key invalid, expired, or account suspended
module_not_subscribed	403	Module not in your subscription
rate_limit_exceeded	429	Too many requests
user_not_found	404	External user ID not registered
invalid_request	400	Missing or invalid parameters

Pricing

Simple per-active-user/month pricing. No base fees. Only charged for users who make API calls.

Example: Subscribe to Assessments (₹30) + AI Chat (₹45) + Mood (₹15). With 200 active users → 200 × ₹90 = ₹18,000/month.

View full pricing →

Mental Health Assessments

₹30/user/month — Administer standardized screenings with AI insights.

GET /v1/assessments/types

List all available assessment types.

// Response
{
  "types": [
    { "id": "phq9", "name": "PHQ-9", "description": "Depression", "questions": 9 },
    { "id": "gad7", "name": "GAD-7", "description": "Anxiety", "questions": 7 },
    { "id": "pss10", "name": "PSS-10", "description": "Stress", "questions": 10 },
    { "id": "who5", "name": "WHO-5", "description": "Well-Being", "questions": 5 },
    { "id": "dass21", "name": "DASS-21", "description": "Depression/Anxiety/Stress", "questions": 21 }
  ]
}

POST /v1/assessments/administer

Get questions for a specific assessment.

{
  "user_id": "emp-001",
  "assessment_type": "phq9"
}

POST /v1/assessments/submit

Submit answers and get scored results.

// Request
{
  "user_id": "emp-001",
  "assessment_type": "phq9",
  "answers": [1, 2, 1, 3, 0, 1, 2, 1, 0]
}

// Response
{
  "score": 11,
  "severity": "moderate",
  "max_score": 27
}

POST /v1/assessments/insights

Get AI-generated personalized insights for a score.

{
  "assessment_type": "phq9",
  "score": 11,
  "severity": "moderate"
}

AI Wellness Chat (Rooh)

₹45/user/month — White-label AI companion powered by Gemini 2.5 Flash.

POST /v1/chat/message

Send a message and get an AI wellness response.

// Request
{
  "user_id": "emp-001",
  "message": "I have been feeling stressed about work deadlines",
  "session_id": "optional-uuid-for-context"
}

// Response
{
  "response": "I hear you. Work deadlines can feel overwhelming...",
  "session_id": "uuid"
}

POST /v1/chat/session

Create a new chat session.

// Response
{ "session_id": "uuid", "created_at": "2026-05-28T10:00:00Z" }

Crisis Detection

₹20/user/month — Real-time text analysis for crisis indicators.

POST /v1/crisis/analyze

Analyze text for suicide ideation, self-harm, harm to others, or severe distress.

// Request
{
  "text": "I feel like there is no way out of this situation",
  "user_id": "emp-001"
}

// Response
{
  "is_crisis": true,
  "category": "crisis_distress",
  "severity": "high",
  "recommendation": "Immediate intervention recommended."
}

Categories: suicide_ideation, self_harm, harm_to_others, crisis_distress

GET /v1/crisis/alerts

List recent crisis alerts for your organization.

Therapy Marketplace

₹60/user/month — Therapist directory, booking, and video sessions.

GET /v1/therapists

Search therapists. Optional filters: specialization, language, max_price, min_rating

Case-sensitive filters: specialization and language are matched exactly against the therapist's tags. A lowercase value like specialization=anxiety returns an empty list — stored values are capitalized (Anxiety, CBT, Stress Management). Send the value exactly as stored, or omit the filter to list all and read each result's specializations array to discover valid values.

// GET /v1/therapists?specialization=Anxiety&max_price=2000

{
  "therapists": [
    {
      "id": "uuid",
      "bio": "Counselling Psychologist...",
      "specializations": ["Anxiety", "Stress", "CBT"],
      "languages": ["English", "Hindi"],
      "experience_years": 6,
      "session_price": 1500,
      "rating": 4.67
    }
  ],
  "page": 1,
  "limit": 20
}

GET /v1/therapists/:id/availability?date=2026-06-15

Get available and booked slots for a specific date.

POST /v1/bookings

Create a therapy session booking.

{
  "user_id": "emp-001",
  "therapist_id": "therapist-uuid",
  "date": "2026-06-15",
  "start_time": "10:00",
  "notes": "First session - anxiety management"
}

GET /v1/bookings/:id

Get booking status, video link, and details.

Corporate Wellness

₹40/user/month — Team analytics, burnout scoring, and wellness plans.

GET /v1/teams/:id/analytics

Get team wellness metrics for the last 30 days.

// Response
{
  "team_id": "uuid",
  "member_count": 45,
  "period": "last_30_days",
  "metrics": {
    "average_mood": 3.8,
    "mood_logs_count": 312,
    "assessments_completed": 28,
    "engagement_rate": 69
  }
}

GET /v1/teams/:id/burnout-score

Calculate team burnout risk score (0-100).

{
  "burnout_risk_score": 45,
  "risk_level": "moderate",
  "recommendation": "Monitor closely and consider wellness activities"
}

POST /v1/teams/:id/members

Bulk add team members.

{
  "members": [
    { "external_id": "emp-001", "email": "priya@company.com", "name": "Priya Sharma" },
    { "external_id": "emp-002", "email": "rahul@company.com", "name": "Rahul Verma" }
  ]
}

Wellness Analytics

₹15/user/month — Mood trends, engagement metrics, PDF reports.

GET /v1/analytics/mood-trends?period=monthly&team_id=uuid

Get aggregated mood data. Periods: weekly, monthly, yearly

POST /v1/reports/generate

Generate a PDF wellness report.

{
  "report_type": "monthly_wellness",
  "team_id": "uuid",
  "period": "2026-05"
}

Mood & Journal

₹15/user/month — Mood logging, trends, AI journal prompts.

POST /v1/mood/log

Log a mood entry (1-5 scale).

// Request
{
  "user_id": "emp-001",
  "mood_value": 4,
  "activities": ["work", "exercise"],
  "note": "Good productive day"
}

// Response
{
  "logged": true,
  "mood_id": "uuid",
  "mood_value": 4,
  "created_at": "2026-05-28T08:30:00Z"
}

GET /v1/mood/trends?user_id=emp-001&period=monthly

Get mood history and average for a user.

GET /v1/journal/prompts

Get 3 randomized AI-powered journal prompts.

Sleep & Health

₹25/user/month — Sleep tracking, scoring, and health dashboard.

POST /v1/sleep/log

Log a sleep entry with bedtime, wake time, and quality.

// Request
{
  "user_id": "emp-001",
  "bedtime": "2026-05-27T23:30:00Z",
  "wake_time": "2026-05-28T07:00:00Z",
  "quality": 4
}

// Response
{
  "logged": true,
  "duration_hours": 7.5,
  "sleep_score": 88
}

GET /v1/sleep/trends

Get historical sleep data and trends.

Psychometric Testing

₹35/user/month — Custom test creation, scoring engine, PDF reports.

GET /v1/tests

List all published psychometric tests.

POST /v1/tests/:id/score

Score a completed test response using the formula engine.

{
  "response_id": "uuid-of-completed-response"
}

Notifications

₹10/user/month — Push, email, WhatsApp multi-channel delivery.

POST /v1/notifications/send

Send a notification to a user via multiple channels.

{
  "user_id": "emp-001",
  "channels": ["push", "email"],
  "title": "Time for your wellness check-in",
  "body": "Take 2 minutes to log your mood."
}

Event Webhooks

Free — Included with any module subscription.

POST /v1/webhooks/endpoints

{
  "url": "https://your-app.com/webhooks/betterspace",
  "events": ["booking.completed", "assessment.completed", "crisis.detected", "mood.logged"],
  "description": "Production webhook"
}

// Response includes signing secret (store securely)
{
  "id": "uuid",
  "secret": "whsec_abc123...",
  "message": "Store the secret securely"
}

GET /v1/webhooks/events

List all available webhook events.

{
  "events": {
    "bookings": ["booking.created", "booking.confirmed", "booking.completed", "booking.cancelled"],
    "assessments": ["assessment.completed"],
    "mood": ["mood.logged"],
    "crisis": ["crisis.detected"],
    "users": ["user.created", "user.updated"],
    "sleep": ["sleep.logged"]
  }
}

Verifying Webhook Signatures

All payloads are signed with HMAC-SHA256. Verify using the X-Webhook-Signature header:

// Node.js example
const crypto = require("crypto");

function verifyWebhook(payload, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
  return signature === expected;
}

SDKs

Official client libraries for quick integration. No need to manage headers manually.

JavaScript / TypeScript

Node.js, React, Next.js

npm install @betterspace/sdk

Python

Django, Flask, FastAPI

pip install betterspace

// JavaScript — 3 lines to get started
import { BetterSpace } from '@betterspace/sdk';

const bs = new BetterSpace('bs_live_your_key');
const result = await bs.assessments.submit('emp-001', 'phq9', [1,2,1,3,0,1,2,1,0]);
// → { score: 11, severity: "moderate" }

Full SDK docs: Dashboard → SDKs

Need help? Contact us at api-support@betterspace.care