API Overview

The CheerKeeper API provides programmatic access to events, schedules, teams, and more. Use it to integrate CheerKeeper with your existing systems or build custom applications.

Base URL

https://admin.cheerkeeper.com/api

All API endpoints are served from this base URL.

Authentication

Most API endpoints require authentication. CheerKeeper uses JWT (JSON Web Tokens) for API access.

Getting a Token

curl -X POST https://admin.cheerkeeper.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Response:

{
  "user": {
    "id": "user_123",
    "email": "you@example.com",
    "name": "Your Name"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Using the Token

Include the access token in the Authorization header:

curl https://admin.cheerkeeper.com/api/events \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

See Authentication for full details.

API Categories

The API is organized into these categories:

Events

Method	Endpoint	Description
GET	/api/events	List all events
POST	/api/events	Create an event
GET	/api/events/:id	Get event details
PUT	/api/events/:id	Update an event
DELETE	/api/events/:id	Delete an event
POST	/api/events/:id/publish	Publish event to mobile

Schedule

Method	Endpoint	Description
GET	/api/events/:id/schedule	Get event schedule
POST	/api/events/:id/schedule/v2/sync	Sync schedule changes
GET	/api/events/:id/sessions	List sessions
POST	/api/events/:id/sessions	Create session

Performances

Method	Endpoint	Description
GET	/api/events/:id/performances	List performances
POST	/api/events/:id/performances	Add performance
PUT	/api/events/:id/performances/:perfId	Update performance
DELETE	/api/events/:id/performances/:perfId	Delete performance

Teams & Organizations

Method	Endpoint	Description
GET	/api/teams-orgs	List organizations
POST	/api/teams-orgs	Create organization
GET	/api/teams-orgs/:id/teams	List teams in org
POST	/api/teams-orgs/:id/teams	Add team to org

Users

Method	Endpoint	Description
GET	/api/company/users	List company users
POST	/api/company/users/invite	Invite user
PUT	/api/company/users/:id/role	Update user role
DELETE	/api/company/users/:id	Remove user

Import

Method	Endpoint	Description
POST	/api/spreadsheet/upload	Upload Excel/CSV
POST	/api/uploads	Upload PDF for AI extraction
GET	/api/uploads/:id/status	Check extraction status

Request Format

Content Type

All requests should use Content-Type: application/json.

Request Body

{
  "name": "Spring Championship 2025",
  "startDate": "2025-03-15",
  "endDate": "2025-03-16",
  "location": {
    "venue": "Convention Center",
    "address": "123 Main St",
    "city": "Orlando",
    "state": "FL",
    "zip": "32801"
  }
}

Response Format

Success Response

{
  "success": true,
  "data": {
    "id": "event_123",
    "name": "Spring Championship 2025",
    "...": "..."
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Event name is required",
    "details": {
      "field": "name"
    }
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid input
401	Unauthorized - Missing/invalid token
403	Forbidden - Insufficient permissions
404	Not Found
409	Conflict - Version mismatch or duplicate
422	Unprocessable - Business logic error
500	Server Error

Rate Limiting

API requests are rate limited:

Plan	Requests/minute
Starter	60
Professional	120
Enterprise	300

Rate limit headers are included in responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1625097600

Versioning

The API is versioned via the URL path:

• v1 (current): /api/events
• v2 (schedule sync): /api/events/:id/schedule/v2/sync

We maintain backward compatibility within major versions.

Pagination

List endpoints support pagination:

GET /api/events?page=1&limit=20

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Filtering

Filter results with query parameters:

# Events by date range
GET /api/events?startDate=2025-01-01&endDate=2025-12-31

# Performances by division
GET /api/events/:id/performances?division=Senior

# Search by name
GET /api/events?search=championship

Webhooks

Register webhooks to receive real-time notifications:

POST /api/webhooks
{
  "url": "https://your-server.com/webhook",
  "events": ["schedule.updated", "event.published"]
}

See Webhooks for full documentation.

SDKs and Libraries

Official libraries coming soon:

• JavaScript/TypeScript
• Python
• PHP

Getting Help

• API Issues: support@cheerkeeper.com
• Status Page: status.cheerkeeper.com

Next Steps

• Authentication - Full auth documentation
• Events API - Working with events
• Schedule Sync - Real-time schedule updates