Clever API TypeScript Client

A fully typed TypeScript client for the Clever Data API v3.1. Clever is an education data platform that connects Student Information Systems (SIS) and Learning Management Systems (LMS) to applications used by schools and districts. This client provides type-safe access to all Clever API endpoints including courses, districts, schools, sections, users, assignments, submissions, attendance records, and events.

Generated from the official Clever Swagger 2.0 specification using swagger-typescript-api.

Installation

npm install @clever-api/client

Quick Start

import { HttpClient, Api } from "@clever-api/client";

// Create an HTTP client with your OAuth bearer token
const httpClient = new HttpClient({
  baseURL: "https://api.clever.com",
  headers: {
    Authorization: "Bearer YOUR_OAUTH_TOKEN",
  },
});

// Initialize the API client
const clever = new Api(httpClient);

// Fetch a list of schools
const schoolsResponse = await clever.schools.getSchools({ limit: 10 });
const schools = schoolsResponse.data.data; // SchoolResponse[]

for (const school of schools ?? []) {
  console.log(school.data?.name, school.data?.id);
}

// Get a specific user (student, teacher, etc.)
const userResponse = await clever.users.getUser({ id: "USER_ID" });
const user = userResponse.data.data;
console.log(user?.name?.first, user?.name?.last, user?.roles);

Auto-pagination with starting_after cursor

The Clever API uses cursor-based pagination. List responses include a links array with next and prev URIs. You can extract the starting_after parameter from the next link to iterate through all results:

import { HttpClient, Api, type SchoolResponse } from "@clever-api/client";

const httpClient = new HttpClient({
  baseURL: "https://api.clever.com",
  headers: { Authorization: "Bearer YOUR_OAUTH_TOKEN" },
});
const clever = new Api(httpClient);

async function getAllSchools(): Promise<SchoolResponse[]> {
  const allSchools: SchoolResponse[] = [];
  let startingAfter: string | undefined;

  while (true) {
    const response = await clever.schools.getSchools({
      limit: 100,
      starting_after: startingAfter,
    });

    const page = response.data;
    if (page.data) {
      allSchools.push(...page.data);
    }

    // Find the "next" link to get the cursor for the next page
    const nextLink = page.links?.find((link) => link.rel === "next");
    if (!nextLink?.uri) break;

    // Extract starting_after from the next link URI
    const url = new URL(nextLink.uri, "https://api.clever.com");
    startingAfter = url.searchParams.get("starting_after") ?? undefined;
    if (!startingAfter) break;
  }

  return allSchools;
}

API Reference

The client is organized into namespaced resource groups that mirror the Clever API:

| Namespace | Methods | | ------------------ | -------------------------------------------------------------------------------------------- | | courses | getCourses, getCourse, getDistrictForCourse, getResourcesForCourse, getSchoolsForCourse, getSectionsForCourse | | districts | getDistricts, getDistrict | | resources | getResources, getResource, getCoursesForResource, getSectionsForResource, getUsersForResource | | schools | getSchools, getSchool, getCoursesForSchool, getDistrictForSchool, getSectionsForSchool, getTermsForSchool, getUsersForSchool | | sections | getSections, getSection, getCourseForSection, getDistrictForSection, getResourcesForSection, getSchoolForSection, getTermForSection, getUsersForSection, createAssignmentForSection, getAssignmentForSection, updateAssignmentForSection, deleteAssignmentForSection, getSubmissionsForAssignment, getSubmissionForAssignment, updateSubmissionForAssignment | | terms | getTerms, getTerm, getDistrictForTerm, getSectionsForTerm, getSchoolsForTerm | | users | getUsers, getUser, getDistrictForUser, getContactsForUser, getStudentsForUser, getTeachersForUser, getResourcesForUser, getSchoolsForUser, getSectionsForUser | | attendance | listAttendanceForSchool, listAttendanceForSection | | events | getEvents, getEvent |

Authentication

The Clever API uses OAuth 2.0. You must obtain a bearer token through Clever's OAuth flow and pass it in the Authorization header:

const httpClient = new HttpClient({
  headers: {
    Authorization: "Bearer YOUR_OAUTH_TOKEN",
  },
});

Alternatively, you can use the securityWorker option for dynamic token management:

const httpClient = new HttpClient<string>({
  securityWorker: (token) => {
    if (token) {
      return { headers: { Authorization: `Bearer ${token}` } };
    }
  },
});

// Set or update the token at any time
httpClient.setSecurityData("YOUR_OAUTH_TOKEN");

Pagination

The Clever API uses cursor-based pagination with the following query parameters:

| Parameter | Type | Description | | ---------------- | -------- | ---------------------------------------------------- | | limit | number | Maximum number of results to return (varies by endpoint) | | starting_after | string | Cursor ID to fetch results after (for forward pagination) | | ending_before | string | Cursor ID to fetch results before (for backward pagination) |

List responses include a links array with Link objects containing:

• rel: "self", "next", or "prev"
• uri: The full URI for that page of results

License

MIT