API Reference
API Reference
HeyCMO API — REST endpoints, MCP protocol, authentication, and integration guide.
API Reference
HeyCMO exposes both a REST API for account management and an MCP server over SSE for AI tool integration. The primary way to interact with HeyCMO's agents and workflows is through the MCP protocol via Claude Desktop, Cursor, or any MCP-compatible client.
Base URL
https://heycmo.aiQuick Start
# Health check
curl https://heycmo.ai/api/health
# Get customer info
curl -H "Authorization: Bearer hcmo_live_YOUR_KEY" \
https://heycmo.ai/api/customer/CUSTOMER_ID
# Connect via MCP (Claude Desktop / Cursor)
# Add to your MCP config:
# { "url": "https://heycmo.ai/mcp/sse?token=hcmo_live_YOUR_KEY" }Authentication
All authenticated endpoints require a Bearer token in the Authorization header:
Authorization: Bearer hcmo_live_YOUR_KEYMCP endpoints use a token query parameter instead:
GET /mcp/sse?token=hcmo_live_YOUR_KEYSee Authentication for details on API key management.
Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/health | None | Liveness check |
GET | /api/health/ready | None | Readiness check (with DB) |
GET | /mcp/sse | Token | MCP SSE connection |
POST | /mcp/message | Token | MCP message handler |
POST | /api/checkout | None | Create Stripe checkout |
POST | /api/webhooks/stripe | Stripe | Webhook handler |
GET | /api/session/:id | None | Get session customer |
GET | /api/customer/:id | Bearer | Get customer details |
GET | /api/events/:id | Bearer | Get customer events |
GET | /api/dashboard/:id | Bearer | Render dashboard |
POST | /api/onboard/:id | Bearer | Trigger onboarding |
POST | /api/connect/:id | Bearer | Generate connect links |
GET | /api/connections/:id | Bearer | Platform connection status |
POST | /api/admin/provision | Admin | Provision customer |
GET|POST|PUT | /api/inngest | Inngest | Cron/event functions |
See Endpoints for complete documentation of each endpoint.
Rate Limiting
Rate limiting is applied per API key or IP address:
| Scope | Limit |
|---|---|
| REST API | 60 requests/minute |
| MCP | 30 requests/minute per customer |
| Checkout | 5 requests/minute |
| Webhooks | 100 requests/minute |
Error Responses
All errors follow a consistent format:
{
"error": "Error message describing what went wrong"
}| Status Code | Meaning |
|---|---|
400 | Bad request — invalid input |
401 | Unauthorized — invalid or missing API key |
413 | Request body too large |
429 | Rate limited — too many requests |
500 | Internal server error |
503 | Service unavailable (readiness check failed) |
CORS
The API allows requests from:
https://heycmo.aihttps://app.heycmo.aihttp://localhost:3000(development only)http://localhost:3001(development only)
Security Headers
All responses include:
X-Content-Type-Options: nosniffX-Frame-Options: DENYReferrer-Policy: strict-origin-when-cross-originPermissions-Policy: camera=(), microphone=(), geolocation=()Strict-Transport-Security: max-age=31536000; includeSubDomains(production)