Kounisou REST API

Complete API reference for programmatic access to your Kounisou account

Machine-readable spec & Kounisou MCP

The full API is described as OpenAPI 3.1 — generate an SDK, a Postman collection, or wire it straight into an AI agent. There’s also an official MCP server so Claude (and any Model Context Protocol client) can drive Kounisou in natural language.

OpenAPI spec →kounisou-mcp →

# Let Claude use your Kounisou account:
claude mcp add kounisou -e KOUNISOU_API_KEY=kns_live_... -- npx -y kounisou-mcp

Access & tiers

A valid account is required for every request. Free accounts get read-only access with a small hourly quota — enough to try the API and build light read integrations. Pro raises the limit to 1,000 req/hr, and Studio unlocks full read/write at 10,000 req/hr with unlimited webhooks.

Authentication

All API requests must include an API key in the Authorization header:

curl https://kounisou.com/api/v1/clients \
  -H "Authorization: Bearer kns_live_..."

Generate API keys in your account settings.

Rate Limiting

API requests are rate limited to 1,000 requests per hour per API key. Rate limit info is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 2026-05-06T12:00:00Z

Pagination

List endpoints use cursor-based pagination. Pass cursor and limit query parameters:

GET /api/v1/clients?limit=20&cursor=abc123

{
  "data": [...],
  "meta": {
    "cursor": "xyz789",
    "hasMore": true,
    "count": 20
  }
}

Endpoints

Clients

GET/api/v1/clients

List all clients. Supports pagination.

POST/api/v1/clients

Create a new client invite.

GET/api/v1/clients/:id

Get client details.

PATCH/api/v1/clients/:id

Update client status or notes.

Workouts

GET/api/v1/workouts

List all workout programs. Supports pagination.

POST/api/v1/workouts

Create a new workout program.

Exercises

GET/api/v1/exercises

List exercises (global + your custom). Supports filters: category, difficulty, muscle_group.

Messages

POST/api/v1/messages

Send a message to a client.

Analytics

GET/api/v1/analytics

Get analytics summary (clients, workouts, engagement).

Webhooks

GET/api/v1/webhooks

List webhook endpoints.

POST/api/v1/webhooks

Create a webhook endpoint. Returns secret once.

DELETE/api/v1/webhooks?id=:id

Delete a webhook endpoint.

Webhook Events

Available webhook event types:

client.created - New client added
client.updated - Client profile updated
client.deleted - Client removed
workout.completed - Client completed a workout
checkin.submitted - Client submitted a check-in
habit.completed - Client completed a habit
goal.reached - Client reached a goal
payment.received - Payment received
client.inactive - Client became inactive

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "message": "Invalid API key",
    "code": "INVALID_KEY"
  }
}

Common error codes: MISSING_AUTH, INVALID_KEY, KEY_REVOKED, KEY_EXPIRED, RATE_LIMIT_EXCEEDED, INSUFFICIENT_SCOPE, VALIDATION_ERROR, NOT_FOUND