⚡
KayAI
API Reference
v1

API Reference

The KayAI REST API gives enterprise customers programmatic access to athlete APEX data, session history, and team analytics. Use it to integrate mental performance insights directly into your platform.

🔑 Authentication

All authenticated endpoints require an X-API-Key header. Contact your KayAI account manager to obtain an enterprise API key.

curl https://app.coachkayteam.com/api/v1/athletes \
  -H "X-API-Key: ek_live_your_key_here"
⚠️ Keep your API key secret. Never expose it in client-side code or public repositories.

⏱️ Rate Limits

Starter
100 req/min
Growth
500 req/min
Enterprise
2,000 req/min

Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining. Exceeding limits returns 429 Too Many Requests.

Endpoints

GET/api/v1/health

API health check. No authentication required.

cURL
curl https://app.coachkayteam.com/api/v1/health
JavaScript
const res = await fetch('https://app.coachkayteam.com/api/v1/health');
const data = await res.json();
// console.log(data.status); // "ok"
Response
{
  "status": "ok",
  "version": "v1",
  "timestamp": "2026-05-06T14:00:00.000Z",
  "service": "KayAI API"
}
GET/api/v1/athletes🔒 Auth required

List all athletes in your organization.

Parameters
org_id
string
Filter by organization ID (UUID)
page
number
Page number (default: 1)
per_page
number
Results per page, max 100 (default: 25)
cURL
curl https://app.coachkayteam.com/api/v1/athletes \
  -H "X-API-Key: your_api_key_here"
JavaScript
const res = await fetch('https://app.coachkayteam.com/api/v1/athletes', {
  headers: { 'X-API-Key': process.env.KAY_API_KEY }
});
const { data, meta } = await res.json();
Response
{
  "data": [
    {
      "id": "uuid-...",
      "email": "athlete@school.edu",
      "full_name": "Jane Smith",
      "sport": "Basketball",
      "position": "Point Guard",
      "team_id": "uuid-..."
    }
  ],
  "meta": {
    "total": 48,
    "page": 1,
    "per_page": 25,
    "pages": 2
  }
}
GET/api/v1/athletes/:id/apex🔒 Auth required

Get an athlete's latest APEX score and domain breakdown.

Parameters
id
stringrequired
Athlete UUID
cURL
curl https://app.coachkayteam.com/api/v1/athletes/UUID/apex \
  -H "X-API-Key: your_api_key_here"
JavaScript
const res = await fetch(`https://app.coachkayteam.com/api/v1/athletes/${athleteId}/apex`, {
  headers: { 'X-API-Key': process.env.KAY_API_KEY }
});
const { data } = await res.json();
// console.log(data.apex_score); // 734
Response
{
  "data": {
    "athlete_id": "uuid-...",
    "athlete_name": "Jane Smith",
    "apex_score": 734,
    "tier": 3,
    "assessed_at": "2026-05-05T10:30:00Z",
    "domains": {
      "FG-ME": { "score": 95, "pillar": "FEEL GOOD" },
      "FG-MS": { "score": 88, "pillar": "FEEL GOOD" },
      "TH-EH": { "score": 102, "pillar": "TRY HARD" },
      "TH-SG": { "score": 91, "pillar": "TRY HARD" },
      "BL-TB": { "score": 78, "pillar": "BELONG" },
      "BL-CC": { "score": 85, "pillar": "BELONG" },
      "SH-PR": { "score": 99, "pillar": "STAY HEALTHY" },
      "SH-LB": { "score": 96, "pillar": "STAY HEALTHY" }
    }
  },
  "meta": { "generated_at": "2026-05-06T14:00:00.000Z" }
}
GET/api/v1/athletes/:id/sessions🔒 Auth required

Get session history for an athlete (last 30 check-ins).

Parameters
id
stringrequired
Athlete UUID
cURL
curl https://app.coachkayteam.com/api/v1/athletes/UUID/sessions \
  -H "X-API-Key: your_api_key_here"
JavaScript
const res = await fetch(`https://app.coachkayteam.com/api/v1/athletes/${athleteId}/sessions`, {
  headers: { 'X-API-Key': process.env.KAY_API_KEY }
});
const { data } = await res.json();
Response
{
  "data": [
    {
      "id": "uuid-...",
      "apex_score": 734,
      "tier": 3,
      "survey_type": "daily",
      "created_at": "2026-05-05T10:30:00Z"
    }
  ],
  "meta": {
    "total": 14,
    "athlete_id": "uuid-...",
    "limit": 30
  }
}
GET/api/v1/teams/:id/summary🔒 Auth required

Get team summary: avg APEX, tier distribution, at-risk athlete count.

Parameters
id
stringrequired
Team UUID
cURL
curl https://app.coachkayteam.com/api/v1/teams/UUID/summary \
  -H "X-API-Key: your_api_key_here"
JavaScript
const res = await fetch(`https://app.coachkayteam.com/api/v1/teams/${teamId}/summary`, {
  headers: { 'X-API-Key': process.env.KAY_API_KEY }
});
const { data } = await res.json();
// console.log(data.at_risk_count);
Response
{
  "data": {
    "team_id": "uuid-...",
    "team_name": "Varsity Basketball",
    "athlete_count": 12,
    "athletes_assessed": 10,
    "avg_apex_score": 701,
    "at_risk_count": 2,
    "tier_distribution": {
      "1": 1, "2": 1, "3": 5, "4": 2, "5": 1
    }
  },
  "meta": { "generated_at": "2026-05-06T14:00:00.000Z" }
}

Error Codes

StatusCodeDescription
200OKRequest succeeded.
401UNAUTHORIZEDInvalid or missing X-API-Key header.
404NOT_FOUNDResource does not exist.
429RATE_LIMITEDToo many requests. Back off and retry.
500SERVER_ERRORInternal server error. Contact support.

Need help? Email support@coachkay.ai or visit our support portal.

© 2026 KayAI — KayAI LLC