Kounisou REST API

Complete API reference for programmatic access to your Kounisou account

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