API Overview
BuildStability Developer API
---
Overview
BuildStability provides multiple ways for developers and AI agents to interact with the platform. All methods use secure JWT authentication and respect Row Level Security (RLS) policies to ensure data isolation.
---
API Access Methods
MCP Server (Model Context Protocol)
Recommended for AI Agents
What It Is
High-level API designed specifically for AI assistants (Claude, ChatGPT, Gemini). Provides pre-built tools with business logic built-in.
Technical Details
- Protocol: JSON-RPC 2.0 over HTTP - Endpoint: `POST /api/mcp` - Authentication: Bearer token (JWT from user login) - Rate Limiting: Yes, tiered by subscription plan (see Rate Limits section)
Use Cases
- AI agents interacting with business data - High-level operations (e.g., "get clients at risk of churning") - Structured responses with business logic built-in - When you want pre-built tools rather than custom queries
Example
`buildstability/get_schedule` returns formatted appointment data with client names, times, and status - all in one call.
---
OpenAPI Specification
Same API, Different Format
What It Is
The MCP endpoints documented in OpenAPI 3.1 format for integration with standard API tooling.
Use Cases
- Import into OpenAI GPT Actions - Generate client SDKs (TypeScript, Python, etc.) - API documentation tools (Swagger UI, Postman) - API testing and validation
Important Note
This is the same MCP API, just documented in OpenAPI format for different tooling. You're not choosing a different API - just a different way to access it.
Download
`/buildstability-openapi.json`
---
Supabase PostgREST API
Advanced Custom Queries
What It Is
Auto-generated REST endpoints from PostgreSQL schema via Supabase. Provides direct access to database tables through REST API.
Access Methods
- Supabase client SDK (recommended) - Direct HTTP requests to PostgREST endpoints
Authentication & Security
- Authentication: Same JWT tokens (user login required) - NO database credentials exposed - You never get direct database access - Row Level Security (RLS): All queries automatically filtered to your business data - User-scoped: You can only access data for businesses where you're an active member
Use Cases
- Complex filtering and joins not available in MCP tools - Real-time subscriptions for live data updates - Bulk operations on multiple records - Custom reporting queries - When you need direct SQL-like query capabilities
Example Query
`GET /rest/v1/appointments?select=*,client:profiles(*)&business_id=eq.{id}`
Rate Limiting
Yes, Supabase enforces rate limits on PostgREST endpoints: - Free tier: 500 requests/hour - Pro tier: 5,000 requests/hour - Team tier: 50,000 requests/hour
These limits are separate from MCP rate limits.
Learn More
See the PostgREST API Guide for detailed usage examples and best practices.
---
Security Model
All API access methods share the same security model:
✅ No Database Credentials Exposed
Developers never get direct database access. You use JWT tokens from user login, not database passwords or connection strings.
✅ User-Scoped Access
All requests use JWT tokens from user login. Your token is automatically scoped to your business membership.
✅ Row Level Security (RLS)
Database policies ensure users can only access data for businesses where they are active members AND where API access has been enabled.
✅ Public Keys Only
Supabase URL and ANON key are public and safe to expose. These are designed to be public.
✅ Service Role Key Protected
Only BuildStability backend has service role access. This key never leaves our servers and is never exposed to developers.
---
Which API Should You Use?
For AI Agents
Use MCP Server - It's specifically designed for AI assistants with high-level tools and structured responses.
For Custom Integrations
Start with MCP Server, then use PostgREST API if you need: - Custom queries not available in MCP tools - Real-time subscriptions - Bulk operations - Complex joins and filtering
For API Tooling
Use OpenAPI Specification to import into: - Postman - Swagger UI - GPT Actions - SDK generators
---
Getting Started
1. Get started with a free trial at https://buildstability.com/signup 2. Enable API access in Business Settings → API & Integrations 3. Read the Quick Start Guide - Get up and running in 5 minutes 4. Review Code Examples - Ready-to-use code snippets 5. Check the Agent Integration Guide - Complete technical documentation 6. See PostgREST Usage Guide - For advanced custom queries
---
Related Resources
- Authentication Guide - How to get and use JWT tokens - Rate Limits & Best Practices - Understanding rate limits - MCP Server Integration - Detailed MCP guide - Error Handling - Common errors and solutions