Complete REST API documentation for Schoolyst. Explore all endpoints, parameters, request/response formats, and examples.

API Reference

Complete reference for the Schoolyst REST API. All endpoints, parameters, and examples you need to integrate with our platform.

Base URL

All API requests should be made to:

https://api.schoolyst.com/v1

Authentication

All API requests require authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See the Authentication guide for detailed information.

Response Format

All API responses use a consistent JSON format:

Success Response

{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 100,
    "total_pages": 10
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  }
}

Pagination

List endpoints support pagination using these parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number to retrieve
`limit`	integer	10	Number of items per page (max: 100)
`sort`	string	`created_at`	Field to sort by
`order`	string	`desc`	Sort order (`asc` or `desc`)

Example:

GET /v1/students?page=2&limit=20&sort=name&order=asc

Students

Manage student information, enrollment, and profiles.

List Students

Get a paginated list of students.

GET /v1/students

Query Parameters:

Parameter	Type	Description
`class_id`	string	Filter by class ID
`status`	string	Filter by status (`active`, `inactive`, `graduated`)
`search`	string	Search by name or admission number
`page`	integer	Page number
`limit`	integer	Items per page

Example Request:

curl -X GET "https://api.schoolyst.com/v1/students?class_id=cls_123&status=active&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  "https://api.schoolyst.com/v1/students?class_id=cls_123&status=active&limit=20",
  {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

const students = await response.json();

response = requests.get(
    'https://api.schoolyst.com/v1/students',
    params={
        'class_id': 'cls_123',
        'status': 'active',
        'limit': 20
    },
    headers={'Authorization': f'Bearer {api_key}'}
)

students = response.json()

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "std_123456",
      "admission_number": "2024001",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "date_of_birth": "2010-05-15",
      "gender": "male",
      "class_id": "cls_123",
      "class_name": "Grade 10-A",
      "status": "active",
      "enrollment_date": "2024-01-15",
      "parent": {
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "phone": "+1234567891"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

Get Student by ID

Retrieve detailed information about a specific student.

GET /v1/students/{student_id}

Example:

curl -X GET "https://api.schoolyst.com/v1/students/std_123456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create Student

Add a new student to the system.

POST /v1/students

Request Body:

{
  "admission_number": "2024002",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+1234567892",
  "date_of_birth": "2010-08-20",
  "gender": "female",
  "class_id": "cls_123",
  "enrollment_date": "2024-01-20",
  "parent": {
    "name": "Robert Smith",
    "email": "robert.smith@example.com",
    "phone": "+1234567893",
    "relation": "father"
  },
  "address": {
    "street": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "zip": "62701",
    "country": "USA"
  }
}

Update Student

Update student information.

PUT /v1/students/{student_id}

Delete Student

Remove a student from the system.

DELETE /v1/students/{student_id}

Deleting a student is permanent and cannot be undone. Consider marking them as inactive instead.

Attendance

Track and manage student attendance records.

Mark Attendance

Record attendance for one or more students.

POST /v1/attendance

Request Body:

{
  "date": "2024-11-21",
  "class_id": "cls_123",
  "records": [
    {
      "student_id": "std_123456",
      "status": "present",
      "check_in_time": "08:00:00",
      "remarks": "On time"
    },
    {
      "student_id": "std_789012",
      "status": "absent",
      "reason": "Sick leave",
      "remarks": "Parent notified"
    },
    {
      "student_id": "std_345678",
      "status": "late",
      "check_in_time": "08:45:00",
      "remarks": "Traffic"
    }
  ]
}

Status Values:

present - Student attended
absent - Student did not attend
late - Student arrived late
excused - Excused absence

Get Attendance

Retrieve attendance records.

GET /v1/attendance

Query Parameters:

Parameter	Type	Description
`date`	string	Date (YYYY-MM-DD)
`class_id`	string	Filter by class
`student_id`	string	Filter by student
`status`	string	Filter by status
`start_date`	string	Date range start
`end_date`	string	Date range end

Example:

curl -X GET "https://api.schoolyst.com/v1/attendance?class_id=cls_123&date=2024-11-21" \
  -H "Authorization: Bearer YOUR_API_KEY"

Attendance Report

Get attendance statistics and reports.

GET /v1/attendance/report

Query Parameters:

Parameter	Type	Description
`start_date`	string	Report start date (required)
`end_date`	string	Report end date (required)
`class_id`	string	Filter by class
`student_id`	string	Filter by student

Response:

{
  "success": true,
  "data": {
    "period": {
      "start_date": "2024-11-01",
      "end_date": "2024-11-21",
      "total_days": 21
    },
    "statistics": {
      "total_students": 30,
      "average_attendance": 92.5,
      "total_present": 585,
      "total_absent": 45,
      "total_late": 15
    },
    "by_student": [
      {
        "student_id": "std_123456",
        "student_name": "John Doe",
        "present": 20,
        "absent": 1,
        "late": 0,
        "attendance_rate": 95.2
      }
    ]
  }
}

Classes

Manage academic classes and sections.

List Classes

Get all classes in the school.

GET /v1/classes

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "cls_123",
      "name": "Grade 10-A",
      "grade": 10,
      "section": "A",
      "academic_year": "2024-2025",
      "teacher_id": "tch_456",
      "teacher_name": "Ms. Johnson",
      "room_number": "201",
      "capacity": 35,
      "current_students": 30,
      "subjects": ["Mathematics", "Science", "English"],
      "schedule": {
        "start_time": "08:00",
        "end_time": "15:00"
      }
    }
  ]
}

Create Class

POST /v1/classes

Request Body:

{
  "name": "Grade 11-B",
  "grade": 11,
  "section": "B",
  "academic_year": "2024-2025",
  "teacher_id": "tch_789",
  "room_number": "305",
  "capacity": 35
}

Get Class Timetable

Retrieve the timetable for a specific class.

GET /v1/classes/{class_id}/timetable

Teachers

Manage teacher profiles and assignments.

List Teachers

GET /v1/teachers

Get Teacher

GET /v1/teachers/{teacher_id}

Get Teacher Schedule

GET /v1/teachers/{teacher_id}/schedule

Library

Manage library books, members, and circulation.

List Books

Get catalog of library books.

GET /v1/library/books

Query Parameters:

Parameter	Type	Description
`search`	string	Search by title, author, ISBN
`category`	string	Filter by category
`status`	string	`available`, `issued`, `reserved`
`page`	integer	Page number
`limit`	integer	Items per page

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "book_123",
      "isbn": "978-0-123456-78-9",
      "title": "Introduction to Computer Science",
      "author": "John Author",
      "publisher": "Tech Publishing",
      "category": "Computer Science",
      "edition": "3rd Edition",
      "publication_year": 2023,
      "copies_total": 5,
      "copies_available": 3,
      "status": "available",
      "location": "Shelf A-15"
    }
  ]
}

Issue Book

Issue a book to a student or teacher.

POST /v1/library/issue

Request Body:

{
  "book_id": "book_123",
  "member_id": "std_123456",
  "member_type": "student",
  "issue_date": "2024-11-21",
  "due_date": "2024-12-05",
  "notes": "Handle with care"
}

Return Book

Process book return.

POST /v1/library/return

Request Body:

{
  "issue_id": "iss_789",
  "return_date": "2024-12-04",
  "condition": "good",
  "late_fee": 0,
  "notes": "Returned in good condition"
}

Reports & Analytics

Generate reports and analytics data.

Academic Performance Report

GET /v1/reports/academic-performance

Attendance Summary

GET /v1/reports/attendance-summary

Financial Report

GET /v1/reports/financial

Query Parameters:

Parameter	Type	Description
`start_date`	string	Report start date
`end_date`	string	Report end date
`report_type`	string	`fees`, `expenses`, `revenue`
`format`	string	`json`, `pdf`, `csv`

Webhooks

Subscribe to real-time events. See Webhooks documentation for details.

Available Events

student.created
student.updated
student.deleted
attendance.marked
book.issued
book.returned
fee.paid
exam.result.published

Rate Limits

API requests are rate-limited based on your plan:

Plan	Requests/Hour	Burst Limit
Standard	1,000	100/min
Premium	5,000	500/min
Enterprise	Custom	Custom

Monitor rate limit headers:

const response = await fetch("https://api.schoolyst.com/v1/students");

console.log(response.headers.get("X-RateLimit-Limit")); // 1000
console.log(response.headers.get("X-RateLimit-Remaining")); // 995
console.log(response.headers.get("X-RateLimit-Reset")); // Unix timestamp

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	422	Invalid request parameters
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`SERVER_ERROR`	500	Internal server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable

SDKs & Libraries

Official SDKs available:

npm install @schoolyst/sdk

const Schoolyst = require("@schoolyst/sdk");

const client = new Schoolyst({
  apiKey: process.env.SCHOOLYST_API_KEY,
});

// List students
const students = await client.students.list({ limit: 20 });

// Get student
const student = await client.students.get("std_123456");

// Mark attendance
await client.attendance.mark({
  date: "2024-11-21",
  records: [{ student_id: "std_123456", status: "present" }],
});

pip install schoolyst

from schoolyst import Schoolyst

client = Schoolyst(api_key=os.getenv('SCHOOLYST_API_KEY'))

# List students
students = client.students.list(limit=20)

# Get student
student = client.students.get('std_123456')

# Mark attendance
client.attendance.mark(
    date='2024-11-21',
    records=[
        {'student_id': 'std_123456', 'status': 'present'}
    ]
)

composer require schoolyst/sdk

<?php
use Schoolyst\Client;

$client = new Client(['api_key' => getenv('SCHOOLYST_API_KEY')]);

// List students
$students = $client->students->list(['limit' => 20]);

// Get student
$student = $client->students->get('std_123456');

// Mark attendance
$client->attendance->mark([
    'date' => '2024-11-21',
    'records' => [
        ['student_id' => 'std_123456', 'status' => 'present']
    ]
]);
?>

gem install schoolyst

require 'schoolyst'

client = Schoolyst::Client.new(
  api_key: ENV['SCHOOLYST_API_KEY']
)

# List students
students = client.students.list(limit: 20)

# Get student
student = client.students.get('std_123456')

# Mark attendance
client.attendance.mark(
  date: '2024-11-21',
  records: [
    { student_id: 'std_123456', status: 'present' }
  ]
)

Need More Help?

Can't find what you're looking for? Check our guides or contact support.

Next Steps

Authentication

Learn about API authentication and security

Webhooks

Set up real-time event notifications

Guides

Step-by-step integration guides

Code Examples

Ready-to-use code examples

API Reference

Authentication

Webhooks

Guides

Code Examples

On this page