Endpoints

Complete reference for all HeyCMO API endpoints. The API is built on Hono and served at https://heycmo.ai.

Health

Liveness Check

GET /api/health

Returns a basic health status. No authentication required.

Response:

{
  "status": "ok",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Readiness Check

GET /api/health/ready

Checks database connectivity. No authentication required. Returns 503 if the database is unreachable.

Response (healthy):

{
  "status": "ready",
  "db": true,
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Response (unhealthy):

// HTTP 503
{
  "status": "not_ready",
  "db": false,
  "timestamp": "2025-01-15T10:30:00.000Z"
}

MCP (Model Context Protocol)

HeyCMO exposes an MCP server over Server-Sent Events (SSE). This is the primary interface for Claude Desktop, Cursor, and other MCP clients.

SSE Connection

GET /mcp/sse?token=hcmo_live_YOUR_KEY

Opens an SSE stream for the MCP session. Authentication is via the token query parameter.

• Creates a dedicated MCP server instance per session
• Returns a sessionId in the SSE stream for subsequent message routing
• Rate limited to 30 requests/minute per customer

Message Endpoint

POST /mcp/message?token=hcmo_live_YOUR_KEY&sessionId=SESSION_ID

Sends JSON-RPC messages to an active MCP session. The sessionId must match an active SSE connection.

Response: Returns the MCP protocol response for the given request.

Error (session not found):

// HTTP 400
{
  "error": "Session not found — reconnect to /mcp/sse"
}

Billing

Create Checkout Session

POST /api/checkout

Creates a Stripe checkout session for subscription management. No authentication required (uses email from body).

Request Body:

{
  "email": "user@example.com"
}

Response:

{
  "url": "https://checkout.stripe.com/c/pay/cs_live_..."
}

Stripe Webhook

POST /api/webhooks/stripe

Handles Stripe webhook events for subscription lifecycle management. Called by Stripe directly — not by your application. Uses the raw request body for signature verification.

Session

Get Session Customer

GET /api/session/:sessionId

Retrieves customer info associated with a Stripe checkout session. Used after checkout completion.

Response:

{
  "customerId": "cust_abc123",
  "email": "user@example.com",
  "apiKey": "hcmo_live_...",
  "mcpEndpoint": "https://heycmo.ai/mcp/sse?token=..."
}

Customer

Get Customer Details

GET /api/customer/:customerId

Returns customer account information. Requires API key authentication.

Headers:

Authorization: Bearer hcmo_live_YOUR_KEY

Response:

{
  "id": "cust_abc123",
  "email": "user@example.com",
  "plan": "pro",
  "status": "active",
  "mcpEndpoint": "https://heycmo.ai/mcp/sse?token=...",
  "brandName": "Acme Corp",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Get Customer Events

GET /api/events/:customerId

Returns the event log for a customer. Requires API key authentication.

Headers:

Authorization: Bearer hcmo_live_YOUR_KEY

Response:

{
  "events": [
    { "type": "workflow.started", "timestamp": "2025-01-15T10:30:00.000Z", "data": {} }
  ]
}

Dashboard

Render Dashboard

GET /api/dashboard/:customerId

Returns an HTML dashboard for the customer. Requires API key authentication.

Onboarding

Trigger Onboarding

POST /api/onboard/:customerId

Triggers the onboarding flow (brand interview + platform connections). Requires API key authentication.

Response:

{
  "status": "onboarding_started"
}

Generate Connect Links

POST /api/connect/:customerId

Generates OAuth connection links for marketing platforms via Composio. Requires API key authentication.

Request Body:

{
  "platforms": ["google_analytics", "search_console", "instagram"]
}

Get Connection Status

GET /api/connections/:customerId

Returns the current Composio connection status for all platforms. Requires API key authentication.

Response:

{
  "customerId": "cust_abc123",
  "connections": {
    "google_analytics": { "connected": true },
    "search_console": { "connected": true },
    "instagram": { "connected": false }
  }
}

Composio OAuth Callback

GET /api/composio/callback

Handles the OAuth redirect from Composio after a user connects a platform. Redirects back to the dashboard.

Admin

Provision Customer

POST /api/admin/provision

Manually provisions a customer account (admin use only). Rate limited to 10 requests/minute.

Inngest

Inngest Serve

GET|POST|PUT /api/inngest

Serves the Inngest function handlers for durable workflow execution and cron scheduling. Used by the Inngest platform to invoke scheduled and event-driven functions.

Authentication Summary

Rate Limits