# Clipboard EMS Public API

> REST API for accessing a school's own extracurricular data on Clipboard: activities, sessions, rolls, teams and the students enrolled in them. Available to schools on the Clipboard Core plan.

Key facts:

- The API is served from https://api.clipboard.app. This documentation site, https://api-docs.clipboard.app, does not serve the API.
- Authenticate with a Bearer API token provisioned on the Clipboard Integration page (IT Admin only), sent as `Authorization: Bearer YOUR_TOKEN` on every request.
- List endpoints are paginated and return a `{ data, pagination }` envelope.
- Requests are rate limited. A `429 Too Many Requests` response should be retried with exponential backoff (wait 1s, then 2s, 4s, 8s and so on).
- Backwards-incompatible changes are announced to all API consumers with multiple months' notice; versioning will be introduced as usage grows.

## Docs

- [OpenAPI specification](https://api-docs.clipboard.app/clipboard-ems/openapi.yaml): the machine-readable OpenAPI 3.1 contract.
- [Interactive API reference](https://api-docs.clipboard.app/clipboard-ems/): the specification rendered for people.
- [Integration Data Processing Terms](https://www.clipboard.app/legal/integration-data-processing-terms): the terms that govern access to the API.

## Endpoints

The operations the specification covers, grouped by resource.

### Activities

Activities offered by the organisation, each belonging to a department.

- GET /activities: List activities

### Activity Selections

Student selections of activities offered for a season.

- GET /activity-selections: List activity selections

### Attendance Records

Student attendance records for session rolls.

- GET /attendance-records: List attendance records

### Departments

Overarching categories that activities fall under, e.g. Music, Co-Curricular or Sport.

- GET /departments: List departments

### Incidents

Incident reports logged against students, e.g. injuries or concussion checks.

- GET /incidents: List incidents

### Locations

Places or venues at which sessions or fixtures can be held.

- GET /locations: List locations

### Pre-Explained Absences

Planned absences submitted ahead of time so a student is excused.

- GET /pre-explained-absences: List pre-explained absences
- POST /pre-explained-absences: Create pre-explained absences
- PATCH /pre-explained-absences: Update pre-explained absences
- DELETE /pre-explained-absences: Delete pre-explained absences

### Sessions

Calendar events such as lessons, rehearsals and fixtures, and the rolls taken for them.

- GET /sessions: List sessions
- POST /sessions: Create sessions
- PATCH /sessions: Update sessions
- DELETE /sessions: Delete sessions
- GET /sessions/{id}: Get a session

### Students

Students enrolled at the school.

- GET /students: List students
- PATCH /students: Add and remove student tags

### Student Teams

A student's membership of a team, and the window over which it was held.

- GET /student-teams: List student teams

### Tags

Tags are the labels a school applies to its students, such as awards, colours and house points. A tag has a label, an optional code and value, and an optional category and subcategory.

- GET /tags: List tags

### Teams

Teams, ensembles and groups of students.

- GET /teams: List teams
- GET /teams/{id}: Get a team

### Users

Staff users of the Clipboard App.

- GET /users: List users
- POST /users: Create users
- PATCH /users: Update users

### Year Groups

Groupings of students by age or the academic year they are enrolled in.

- GET /year-groups: List year groups