API Overview

The SaaniCare API provides programmatic access to all SaaniCare features and data.

Base URL

https://api.saanicare.dev

Authentication

All API requests require authentication using JWT tokens.

Getting an Access Token

  1. Authenticate via Auth0
  2. Receive JWT token
  3. Include token in requests

Using the Token

Include the token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN

API Structure

RESTful Design

The API follows RESTful principles:

  • GET: Retrieve resources
  • POST: Create resources
  • PUT: Update resources
  • DELETE: Delete resources

Endpoints

Endpoints are organized by resource:

  • /api/students - Student management
  • /api/activities - Activity management
  • /api/classrooms - Classroom management
  • /api/schools - School management
  • /api/progress - Progress tracking
  • /api/messages - Messaging

Response Format

Success Response

{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Error message",
    "details": { ... }
  }
}

Status Codes

  • 200 - Success
  • 201 - Created
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 500 - Server Error

Rate Limiting

API requests are rate-limited:

  • Standard: 100 requests per minute
  • Premium: 1000 requests per minute

Rate limit headers:

  • X-RateLimit-Limit: Request limit
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Reset time

Pagination

List endpoints support pagination:

GET /api/students?page=1&limit=20

Response includes pagination metadata:

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Filtering & Sorting

Many endpoints support filtering and sorting:

GET /api/students?filter[grade]=K&sort=name&order=asc

Webhooks

Subscribe to webhooks for real-time updates:

  • Student progress updates
  • Activity completions
  • Message notifications
  • System events

SDKs & Libraries

Official SDKs available:

  • JavaScript/TypeScript: @saanicare/api-client
  • React: React Query hooks included
  • Python: Coming soon
  • Ruby: Coming soon

Getting Help

  • Documentation: This site
  • Support: support@saanicare.dev
  • Status: status.saanicare.dev
Previous Production Hostnames