AI Agent Documentation

BuildStability Agent Integration Guide

Complete technical guide for AI agents (Claude, ChatGPT, Gemini) and developers integrating with BuildStability via MCP, OpenAPI, and PostgREST API

View Raw Markdown

Built for the AI Agent Era — Unlike competitors who lock data in proprietary black boxes, BuildStability provides structured data access via MCP, OpenAPI, and standard PostgreSQL.

Quick Start

For AI Agents (Claude, ChatGPT, Gemini, etc.)

Enable API access in Business Settings → API & Integrations
Authenticate with Supabase JWT token
Use MCP endpoint: POST https://api.buildstability.com/api/mcp
See MCP Server section below

For Developers

Architecture Overview

BuildStability is built on modern, agent-friendly infrastructure:

Component	Technology	Agent Access
Database	PostgreSQL 15+ (Supabase)	✅ Direct SQL queries
Authentication	Supabase Auth (JWT)	✅ Standard Bearer tokens
API Layer	MCP Server + PostgREST API (JWT auth, RLS enforced)	✅ JSON-RPC 2.0 + REST
Frontend	React/Vite SPA	ℹ️ Human interface only
Edge Functions	Supabase Edge Functions	✅ HTTP endpoints

Key Advantage: All data is stored in standard PostgreSQL. No proprietary formats, no black boxes.

MCP Server (Model Context Protocol)

Overview

BuildStability exposes a native MCP endpoint for AI assistants to interact directly with business data using JSON-RPC 2.0.

Endpoint

POST https://api.buildstability.com/api/mcp

Authentication

Authorization: Bearer <supabase_jwt_token>

Content-Type: application/json

X-Business-ID: <business_uuid> (optional - for multi-business users)

Security Requirements

IMPORTANT: API/MCP access must be explicitly enabled for each business.

API Access Must Be Enabled: Businesses must enable API access in their settings before MCP endpoints will work.
Business Isolation: All data is scoped to the authenticated user's business.
Multi-Business Users: Use the X-Business-ID header to specify which business to access.

Enabling API Access

Business administrators can enable API access:

Go to Business Settings
Navigate to API & Integrations
Toggle Enable API Access
Save changes

Protocol

JSON-RPC 2.0 over HTTP

Available Tools

Tool Name	Description	Parameters
`tools/list`	List all available tools	None
`buildstability/get_client_summary`	Get client details with engagement score	`client_id` (required)
`buildstability/list_active_programs`	List active workout programs	`limit` (optional, default: 10)
`buildstability/check_churn_risk`	Get clients at risk of churning	`threshold` (optional, default: 40)
`buildstability/get_business_stats`	Get high-level business metrics	None
Schedule & Clients
`buildstability/get_schedule`	Get appointments and classes	`date`, `trainer_id`, `include_classes`
`buildstability/list_clients`	List all clients with engagement data	`status`, `search`, `limit`
`buildstability/get_available_slots`	Get available booking slots	`date`, `trainer_id`, `duration_minutes`
Revenue & Analytics
`buildstability/get_revenue_summary`	Get revenue for a period	`period`, `start_date`, `end_date`
`buildstability/get_attendance_stats`	Get attendance and no-show rates	`period`, `client_id`
`buildstability/get_popular_times`	Get booking time analytics	`period`
Client Details
`buildstability/get_client_workout_history`	Get workout sessions and exercises	`client_id` (required), `limit`
`buildstability/get_client_notes`	Get notes and documents	`client_id` (required), `document_type`
Actions
`buildstability/send_client_message`	Send email to client	`client_id`, `message` (required)
`buildstability/create_client_note`	Add note to client profile	`client_id`, `content` (required)

15 tools available. Use tools/list to get full details.

Example Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "buildstability/check_churn_risk",
  "params": {
    "threshold": 40
  }
}

Example Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "threshold": 40,
    "at_risk_count": 3,
    "clients": [
      {
        "client_id": "uuid-here",
        "name": "John Smith",
        "email": "john@example.com",
        "engagement_score": 28,
        "last_workout": "2025-01-10",
        "recommendation": "Immediate outreach required - high churn risk"
      }
    ]
  }
}

OpenAPI Specification

A full OpenAPI 3.1 specification is available for GPT Actions and API clients:

https://buildstability.com/buildstability-openapi.json

Use Cases:

Import into OpenAI GPT Actions
Generate client SDKs (TypeScript, Python, etc.)
API documentation tools (Swagger UI, Postman)
API testing and validation

View Interactive Spec View Raw JSON

Authentication

Agents acting on behalf of a user must obtain a valid JWT from Supabase Auth.

Method

Bearer Token in Authorization header

Getting Your Token

Method 1: Browser Console (Quick Test)

Log in to BuildStability
Open DevTools (F12) → Application → Local Storage
Find sb-<project-id>-auth-token
Copy the access_token value

Method 2: Supabase Client (Recommended)

import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_ANON_KEY!
);

const { data: { session } } = await supabase.auth.getSession();
const accessToken = session?.access_token;

Token Expiration

Access tokens: 1 hour
Refresh tokens: 30 days
Supabase client automatically refreshes tokens

Security Best Practices

✅ Never commit tokens to version control
✅ Use environment variables
✅ Store tokens securely (Keychain/Keystore on mobile)
✅ Always use HTTPS
✅ Rotate tokens if compromised

Data Schema (Core Entities)

Client

Represents a fitness client managed by a trainer.

interface Client {
  id: string;              // UUID
  first_name: string;
  last_name: string;
  email: string;
  status: 'active' | 'archived' | 'lead';
  join_date: string;       // ISO 8601
  managing_trainer_id: string; // UUID of the trainer
  business_id: string;     // UUID of the business
}

Program Template

A reusable workout structure.

interface ProgramTemplate {
  id: string;              // UUID
  name: string;            // e.g., "Hypertrophy Phase 1"
  goal: string;            // e.g., "Muscle Gain"
  weeks: WorkoutWeek[];    // JSON structure of weeks/days/exercises
  trainer_id: string;      // UUID
  business_id: string;     // UUID
}

Engagement Score

Client retention prediction metric.

interface EngagementScore {
  client_id: string;       // UUID
  score: number;           // 0-100
  risk_level: 'low' | 'moderate' | 'high';
  last_workout: string;    // ISO 8601 date
  workouts_this_week: number;
}

Rate Limits

BuildStability enforces rate limits to ensure fair usage and cost protection:

Plan	Rate Limit	Daily Cap	Max Clients/Query
Free Trial	25 req/15min	500/day	5
Essential	50 req/15min	1,000/day	10
Starter	100 req/15min	5,000/day	25
Pro	200 req/15min	15,000/day	50
Pro+	500 req/15min	50,000/day	100

Response Headers

All API responses include usage headers:

X-RateLimit-Limit - Your rate limit
X-RateLimit-Remaining - Requests remaining in window
X-DailyLimit-Limit - Your daily cap
X-DailyLimit-Remaining - Requests remaining today
X-DailyLimit-Reset - When daily cap resets (midnight UTC)

Why BuildStability is Agent-Friendly

Unlike competitors who lock your data in proprietary black boxes:

Feature	BuildStability	Competitors
Database	✅ PostgreSQL (standard SQL)	❌ Proprietary formats
API Access	✅ MCP + OpenAPI + REST	❌ Limited or none
Data Export	✅ Full SQL export	❌ Locked in
Integration	✅ Native MCP support	❌ Manual scraping

PostgreSQL Native

Standard SQL database that any tool can query

MCP Native

Direct integration with Claude, ChatGPT, Gemini, and other AI assistants

OpenAPI Spec

Import into GPT Actions or any API client

View Raw Markdown Developer Portal

BuildStability Agent Integration Guide

Quick Start

For AI Agents (Claude, ChatGPT, Gemini, etc.)

For Developers

Architecture Overview

MCP Server (Model Context Protocol)

Overview

Endpoint

Authentication

Security Requirements

Enabling API Access

Protocol

Available Tools

Example Request

Example Response

OpenAPI Specification

Authentication

Method

Getting Your Token

Token Expiration

Security Best Practices

Data Schema (Core Entities)

Client

Program Template

Engagement Score

Rate Limits

Response Headers

Why BuildStability is Agent-Friendly

PostgreSQL Native

MCP Native

OpenAPI Spec

Related Resources

OpenAPI Spec

LLM Context

Auth Guide

Quick Start

Code Examples

Developer Portal