API docs by Redocly

Kibooz API (1)

Download OpenAPI specification:

License: MIT

REST API of Kibooz, the kindergarten app where teachers record the mood of children and parents follow it and earn points for sorting trash.

Every JSON response uses one envelope. A success has success: true with an optional message and data. A failure has success: false, a message and a stable errorCode, and validation failures also carry a details object with one message per field.

Protected routes need the access token from login as a bearer token. Rate limits answer 429 with RATE_LIMITED.

Auth

Registration, login and sessions

Create an account

A GURU registers together with a new class and becomes its teacher. A WALI registers with the class code of the teacher and the details of the child. A class whose teachers were all deleted cannot accept new children.

Request Body schema: application/json
required
email
required
string <email> <= 255 characters
password
required
string <password> [ 8 .. 72 ] characters

At most 72 bytes, which is the limit of bcrypt

fullName
required
string [ 2 .. 150 ] characters
role
required
string
Enum: "GURU" "WALI"
phoneNumber
string <= 30 characters
nip
string <= 50 characters
schoolName
string <= 150 characters
address
string <= 1000 characters
whatsappNumber
string <= 30 characters
object

Required for a GURU

classCode
string [ 4 .. 12 ] characters ^[A-Za-z0-9]+$

Required for a WALI, the join code from the dashboard of the teacher

object

Required for a WALI

Responses

Request samples

Content type
application/json
Example
{
  • "email": "teacher@example.com",
  • "password": "{{password}}",
  • "fullName": "Ibu Siti",
  • "role": "GURU",
  • "class": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Sign in

Request Body schema: application/json
required
email
required
string <email> <= 255 characters
password
required
string <password> <= 72 characters
role
required
string (Role)
Enum: "GURU" "WALI" "ADMIN"

Teacher, parent or administrator. ADMIN cannot be registered.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "role": "GURU"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Exchange a refresh token for a new pair

The refresh token is single use, so the old one stops working as soon as this call succeeds.

Request Body schema: application/json
required
refreshToken
required
string <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Revoke a refresh token

Request Body schema: application/json
required
refreshToken
required
string <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Parent

Routes for the WALI role

Dashboard of a child

The child, today's mood, the points summary and the recommended guidance. Without studentId the oldest child is used.

Authorizations:
bearerAuth
query Parameters
studentId
string <uuid>

A child of the signed in parent

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Tell the teacher that a guidance was applied at home

Authorizations:
bearerAuth
Request Body schema: application/json
required
guidanceId
required
string <= 64 characters
studentId
required
string <uuid>
parentNotes
string <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "guidanceId": "string",
  • "studentId": "316b73a5-f34b-4c3c-9a64-99b549057ec7",
  • "parentNotes": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Teacher

Routes for the GURU role

Overview of a class

The class overview and the distribution of today's moods. Without classId the first class of the teacher is used.

Authorizations:
bearerAuth
query Parameters
classId
string <uuid>

A class of the signed in user

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Record the mood of a child

Only the latest mood of a child per local day counts in the dashboards and charts.

Authorizations:
bearerAuth
Request Body schema: application/json
required
studentId
required
string <uuid>
moodType
required
string (Mood)
Enum: "SENANG" "SEDIH" "MARAH" "BINGUNG"

Happy, sad, angry or confused

source
string
Default: "MANUAL_INPUT"
Enum: "AI_CAMERA" "MANUAL_INPUT"
confidenceScore
number <float> [ 0 .. 1 ]

Required for the AI_CAMERA source, 1 by default otherwise

notes
string <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "studentId": "316b73a5-f34b-4c3c-9a64-99b549057ec7",
  • "moodType": "SENANG",
  • "source": "AI_CAMERA",
  • "confidenceScore": 0,
  • "notes": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Mood charts of a class

The donut summary and the Monday to Friday trend. The monthly range adds the distribution of the month.

Authorizations:
bearerAuth
query Parameters
classId
string <uuid>

A class of the signed in user

range
string
Default: "weekly"
Enum: "weekly" "monthly"

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Trash

Claiming points and the leaderboard

Claim points for sorted trash

A child can claim a limited number of times per local day. The optional photo is stored as evidence and has to be a JPEG, PNG or WebP image of at most 4 MiB, given as base64 or as a data URI.

Authorizations:
bearerAuth
Request Body schema: application/json
required
studentId
required
string <uuid>
trashType
required
string (TrashType)
Enum: "ORGANIK" "ANORGANIK" "B3"
confidenceScore
number <float> [ 0 .. 1 ]
Default: 0
photoBase64
string

Optional evidence photo as base64 or a data URI, at most 4 MiB once decoded

Responses

Request samples

Content type
application/json
{
  • "studentId": "316b73a5-f34b-4c3c-9a64-99b549057ec7",
  • "trashType": "ORGANIK",
  • "confidenceScore": 0,
  • "photoBase64": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "data": {
    }
}

Podium and ranking of a class

Ranked by points, then name. A parent sees the class of their child and a teacher sees a class they teach.

Authorizations:
bearerAuth
query Parameters
classId
string <uuid>

A class of the signed in user

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Account

Profile photo and account deletion

Upload a profile photo

Sets the photo of the signed in user, or of one of their children when studentId is given by a parent. The file has to be a JPEG, PNG or WebP image of at most 2 MiB. The previous photo is deleted from storage.

Authorizations:
bearerAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>
studentId
string <uuid>

A child of the signed in parent

Responses

Response samples

Content type
application/json
{}

Delete the own account

Soft deletes the account after the password is confirmed. The sessions are revoked, the account can no longer sign in, and the children of a parent are deleted with it.

Authorizations:
bearerAuth
Request Body schema: application/json
required
password
required
string <password> <= 72 characters

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Operations

Health check

Health of the service and its dependencies

Answers 200 when the database works, with degraded when Redis is down, and 503 when the database is down. This route lives at the root and not under /api/v1.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "status": "ok",
  • "version": "string",
  • "checks": {
    }
}