Appointments API

Endpoints for managing tutoring sessions (appointments). Appointments are the core transactional records in NIVAA, representing scheduled sessions between tutors and students.

GET /api/appointments All authenticated roles

List appointments visible to the current user. Results are scoped by role: Admin sees all, Tutor sees their matches only, Parent sees their children only.

Parameter	Type	Description
`date`	`string`	Filter by date (YYYY-MM-DD)
`status`	`string`	Filter by lowercase status (e.g., `scheduled`, `approved`)
`match_id`	`number`	Filter by match ID
`page`	`number`	Page number (default: 1)
`limit`	`number`	Results per page (default: 20, max: 100)

Response

{
  "ok": true,
  "data": {
    "appointments": [
      {
        "id": 42,
        "match_id": 10,
        "date": "2026-03-27",
        "start_time": "09:00",
        "end_time": "10:00",
        "status": "scheduled",
        "checked_in_at": null,
        "checked_out_at": null,
        "tutor_notes": null,
        "billed_as_addon": 0,
        "child_name": "Emily Chen",
        "tutor_name": "Alex Tan",
        "created_at": "2026-03-20T10:00:00Z",
        "updated_at": "2026-03-20T10:00:00Z"
      }
    ],
    "total": 48,
    "page": 1,
    "limit": 20
  }
}

POST /api/appointments admin

Create a new appointment.

Parameter	Type	Description
`match_id`	`number`	Match ID linking tutor to student
`date`	`string`	Session date (YYYY-MM-DD)
`start_time`	`string`	Start time (HH:MM)
`end_time`	`string`	End time (HH:MM)

Response

{
  "ok": true,
  "data": { "id": 43, ... }
}

PATCH /api/appointments/:id/status Role-dependent

Update the status of an appointment. Machine status values are lowercase. Available transitions depend on the current status and the caller's role.

Parameter	Type	Description
`status`	`string`	New status value

Response

{
  "ok": true,
  "data": { "status": "approved" }
}

Allowed Transitions

From Status	To Status	Who
`scheduled`	`cancelled_by_tutor`	Tutor, Admin
`awaiting_approval_parent`	`approved`	Parent after tutor check-in/out; Admin via verify with reason
`awaiting_approval_parent`	`disputed`	Parent, Admin
`disputed`	`approved`	admin via verify with reason

POST /api/appointments/:id/checkin Tutor, Admin

Check in to a session. Enforces the 30-minute time window.

Response

{
  "ok": true,
  "data": {
    "checked_in_at": "2026-03-27T08:35:00Z"
  }
}

POST /api/appointments/:id/checkout Tutor, Admin

Check out of a session. Sets status to awaiting_approval_parent and implicitly confirms the tutor side.

Response

{
  "ok": true,
  "data": {
    "checked_out_at": "2026-03-27T10:05:00Z",
    "status": "awaiting_approval_parent"
  }
}

Appointment Statuses

scheduled On the calendar, not yet started

checked_in Tutor has checked in, session in progress

awaiting_approval_parent Tutor checked out, waiting for parent acknowledgement

approved Parent acknowledged the checked-out session

disputed Parent flagged an issue

cancelled_by_tutor Tutor cancelled before session started