webapp

Backend API

All backend endpoints currently mapped by the server. Routes are relative to the app root, and every body shown here is JSON.

GET /api/opening-tree

Loads a saved opening tree state.

Notes

  • If stateKey is omitted, the default white opening tree is used.
  • The value field contains serialized opening-tree JSON.

Parameters

Name Type Source Description
stateKey string? query Optional query parameter for the opening tree key.

Responses

Status Body Description
200 OK OpeningTreeStateDocument Returns the stored opening tree document.
JSON fields
  • stateKey : string
  • value : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the supplied state key is not supported.
JSON fields
  • error : string
404 Not Found No body Returned when no tree has been saved yet for the requested state key.
POST /api/opening-tree

Creates or overwrites an opening tree state.

Notes

  • If stateKey is omitted, the default white opening tree is used.
  • Send expectedUpdatedAtUtc to protect against overwriting a newer version.

Parameters

Name Type Source Description
stateKey string? query Optional query parameter for the opening tree key.
request SaveOpeningTreeStateRequest body JSON request body with the serialized tree payload.
JSON fields
  • value : string
  • expectedUpdatedAtUtc : string

Responses

Status Body Description
200 OK OpeningTreeStateDocument Returns the saved opening tree document.
JSON fields
  • stateKey : string
  • value : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the state key or request payload is invalid.
JSON fields
  • error : string
409 Conflict BackendApiErrorResponse Returned when `expectedUpdatedAtUtc` does not match the current server version.
JSON fields
  • error : string
PUT /api/opening-tree

Updates an opening tree state using the same handler as POST.

Notes

  • If stateKey is omitted, the default white opening tree is used.
  • This endpoint uses the same save logic as the POST variant.

Parameters

Name Type Source Description
stateKey string? query Optional query parameter for the opening tree key.
request SaveOpeningTreeStateRequest body JSON request body with the serialized tree payload.
JSON fields
  • value : string
  • expectedUpdatedAtUtc : string

Responses

Status Body Description
200 OK OpeningTreeStateDocument Returns the saved opening tree document.
JSON fields
  • stateKey : string
  • value : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the state key or request payload is invalid.
JSON fields
  • error : string
409 Conflict BackendApiErrorResponse Returned when `expectedUpdatedAtUtc` does not match the current server version.
JSON fields
  • error : string
POST /api/opening-tree/merge

Merges an opening tree payload through the shared save handler.

Notes

  • Despite the route name, this endpoint currently delegates to the same save handler as POST and PUT /api/opening-tree.

Parameters

Name Type Source Description
stateKey string? query Optional query parameter for the opening tree key.
request SaveOpeningTreeStateRequest body JSON request body with the serialized tree payload.
JSON fields
  • value : string
  • expectedUpdatedAtUtc : string

Responses

Status Body Description
200 OK OpeningTreeStateDocument Returns the saved opening tree document.
JSON fields
  • stateKey : string
  • value : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the state key or request payload is invalid.
JSON fields
  • error : string
409 Conflict BackendApiErrorResponse Returned when `expectedUpdatedAtUtc` does not match the current server version.
JSON fields
  • error : string
GET /api/openings

Lists the saved openings.

Parameters

No route, query, header, or body parameters.

Responses

Status Body Description
200 OK OpeningSummary[] Returns every opening summary, including the built-in default opening.
Collection item fields
  • id : string
  • name : string
  • repertoireSide : string
  • updatedAtUtc : DateTimeOffset
POST /api/openings

Creates a new opening entry.

Notes

  • If initialTreeValue is omitted, the opening starts with the default root position.

Parameters

Name Type Source Description
request CreateOpeningRequest body JSON request body describing the new opening.
JSON fields
  • name : string
  • repertoireSide : string
  • initialTreeValue : string?

Responses

Status Body Description
200 OK OpeningSummary Returns the created opening summary.
JSON fields
  • id : string
  • name : string
  • repertoireSide : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the opening name, repertoire side, or initial tree payload is invalid.
JSON fields
  • error : string
GET /api/curriculum

Loads the saved curriculum list.

Parameters

No route, query, header, or body parameters.

Responses

Status Body Description
200 OK CurriculumDocument Returns the current curriculum document.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string
  • updatedAtUtc : DateTimeOffset
POST /api/curriculum

Creates or overwrites the curriculum list.

Parameters

Name Type Source Description
request SaveCurriculumRequest body JSON request body containing the full curriculum item list.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string

Responses

Status Body Description
200 OK CurriculumDocument Returns the saved curriculum document.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the curriculum payload fails validation.
JSON fields
  • error : string
PUT /api/curriculum

Updates the curriculum list using the shared save handler.

Parameters

Name Type Source Description
request SaveCurriculumRequest body JSON request body containing the full curriculum item list.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string

Responses

Status Body Description
200 OK CurriculumDocument Returns the saved curriculum document.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the curriculum payload fails validation.
JSON fields
  • error : string
GET /api/students

Loads the saved student roster grouped by classes.

Parameters

No route, query, header, or body parameters.

Responses

Status Body Description
200 OK StudentRosterDocument Returns the current student roster document.
JSON fields
  • classes : List<StudentClass>
    • id : string
    • name : string
    • students : List<StudentEntry>
      • id : string
      • name : string
  • updatedAtUtc : DateTimeOffset
POST /api/students

Creates or overwrites the student roster.

Parameters

Name Type Source Description
request SaveStudentRosterRequest body JSON request body containing the full class and student list.
JSON fields
  • classes : List<StudentClass>
    • id : string
    • name : string
    • students : List<StudentEntry>
      • id : string
      • name : string

Responses

Status Body Description
200 OK StudentRosterDocument Returns the saved student roster document.
JSON fields
  • classes : List<StudentClass>
    • id : string
    • name : string
    • students : List<StudentEntry>
      • id : string
      • name : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the student payload fails validation.
JSON fields
  • error : string
PUT /api/students

Updates the student roster using the shared save handler.

Parameters

Name Type Source Description
request SaveStudentRosterRequest body JSON request body containing the full class and student list.
JSON fields
  • classes : List<StudentClass>
    • id : string
    • name : string
    • students : List<StudentEntry>
      • id : string
      • name : string

Responses

Status Body Description
200 OK StudentRosterDocument Returns the saved student roster document.
JSON fields
  • classes : List<StudentClass>
    • id : string
    • name : string
    • students : List<StudentEntry>
      • id : string
      • name : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the student payload fails validation.
JSON fields
  • error : string
GET /api/milestones

Loads the saved milestone list.

Parameters

No route, query, header, or body parameters.

Responses

Status Body Description
200 OK MilestoneDocument Returns the current milestone document.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string
  • updatedAtUtc : DateTimeOffset
POST /api/milestones

Creates or overwrites the milestone list.

Parameters

Name Type Source Description
request SaveMilestonesRequest body JSON request body containing the full milestone list.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string

Responses

Status Body Description
200 OK MilestoneDocument Returns the saved milestone document.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the milestone payload fails validation.
JSON fields
  • error : string
PUT /api/milestones

Updates the milestone list using the shared save handler.

Parameters

Name Type Source Description
request SaveMilestonesRequest body JSON request body containing the full milestone list.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string

Responses

Status Body Description
200 OK MilestoneDocument Returns the saved milestone document.
JSON fields
  • items : List<CurriculumItem>
    • id : string
    • name : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the milestone payload fails validation.
JSON fields
  • error : string
GET /api/attendance

Loads the saved attendance selections.

Parameters

No route, query, header, or body parameters.

Responses

Status Body Description
200 OK AttendanceDocument Returns the current attendance document.
JSON fields
  • entries : List<AttendanceEntry>
    • topicId : string
    • classId : string
    • learnedStudentIds : List<string>
  • updatedAtUtc : DateTimeOffset
POST /api/attendance

Creates or overwrites the attendance selections.

Parameters

Name Type Source Description
request SaveAttendanceRequest body JSON request body containing topic, class, and learned student mappings.
JSON fields
  • entries : List<AttendanceEntry>
    • topicId : string
    • classId : string
    • learnedStudentIds : List<string>

Responses

Status Body Description
200 OK AttendanceDocument Returns the saved attendance document.
JSON fields
  • entries : List<AttendanceEntry>
    • topicId : string
    • classId : string
    • learnedStudentIds : List<string>
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the attendance payload fails validation.
JSON fields
  • error : string
PUT /api/attendance

Updates the attendance selections using the shared save handler.

Parameters

Name Type Source Description
request SaveAttendanceRequest body JSON request body containing topic, class, and learned student mappings.
JSON fields
  • entries : List<AttendanceEntry>
    • topicId : string
    • classId : string
    • learnedStudentIds : List<string>

Responses

Status Body Description
200 OK AttendanceDocument Returns the saved attendance document.
JSON fields
  • entries : List<AttendanceEntry>
    • topicId : string
    • classId : string
    • learnedStudentIds : List<string>
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the attendance payload fails validation.
JSON fields
  • error : string
GET /api/user-state/{stateKey}

Loads per-client user state using a server-issued signed cookie.

Notes

  • The server manages the chessapp.user-state-client HttpOnly cookie automatically.
  • Supported stateKey values: "mate_exercises_solved", "opening_training_statistics_v1", "opening_training_priorities_v1", "opening_training_alpha_v1".

Parameters

Name Type Source Description
stateKey string route Route parameter for the supported user-state key.

Responses

Status Body Description
200 OK UserStateDocument Returns the stored user-state document for the current client.
JSON fields
  • stateKey : string
  • value : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the requested state key is not supported.
JSON fields
  • error : string
404 Not Found No body Returned when the current client has no saved value for the requested state key.
POST /api/user-state/{stateKey}

Saves per-client user state using a server-issued signed cookie.

Notes

  • The server manages the chessapp.user-state-client HttpOnly cookie automatically.
  • Supported stateKey values: "mate_exercises_solved", "opening_training_statistics_v1", "opening_training_priorities_v1", "opening_training_alpha_v1".

Parameters

Name Type Source Description
stateKey string route Route parameter for the supported user-state key.
request SaveUserStateRequest body JSON request body containing the state value.
JSON fields
  • value : string?

Responses

Status Body Description
200 OK UserStateDocument Returns the saved user-state document for the current client.
JSON fields
  • stateKey : string
  • value : string
  • updatedAtUtc : DateTimeOffset
400 Bad Request BackendApiErrorResponse Returned when the requested state key is not supported.
JSON fields
  • error : string
DELETE /api/openings/{openingId}

Deletes a saved opening by opening id and repertoire side.

Notes

  • The built-in default opening cannot be deleted.

Parameters

Name Type Source Description
openingId string route Route parameter for the opening identifier.
repertoireSide string? query Required query parameter with 'white' or 'black'.

Responses

Status Body Description
204 No Content No body Deletes the requested opening and returns no body.
400 Bad Request BackendApiErrorResponse Returned when the opening id, repertoire side, or delete request is invalid.
JSON fields
  • error : string
An unhandled error has occurred. Reload 🗙