API reference overview

The reference is organised by resource. Every method follows the same structure: parameters, returns, examples in TypeScript / Python / curl.

Top-level resources

Workspaces

client.workspaces.* — tenants holding users and courses.

Courses

client.courses.* — the syllabus.

Cohorts

client.cohorts.* — runs of a course for a group of students.

Lessons

client.lessons.* — atomic learning units.

Activities

client.activities.* — quizzes, flashcards, explainers, podcasts, …

Assignments

client.assignments.* — gradable artefacts.

Submissions

client.submissions.* — student responses + grades.

Users

client.users.* plus sugar students.* / teachers.*.

SCORM

client.scorm.* — export packages.

Method conventions

Every CRUD resource exposes:

Method	HTTP	Returns
`list(params?)`	`GET /resource`	`{ data, has_more, next_cursor }`
`retrieve(id, opts?)`	`GET /resource/:id`	the full object
`create(params)`	`POST /resource`	the new object
`update(id, params)`	`PATCH /resource/:id`	the updated object
`del(id)`	`DELETE /resource/:id`	`{ deleted: true, id }`

Idiomatic actions are namespaced under the resource — courses.clone(), submissions.gradeWithAi(), etc.

Standard parameters

Every list call:

{
  limit?: number;            // default 20, max 100
  startingAfter?: string;    // cursor
  expand?: string[];         // see Pagination & expanding
  // …resource-specific filters
}

Every retrieve call:

{
  expand?: string[];
}

Every create / update call accepts an options bag:

{
  idempotencyKey?: string;   // see Errors & retries
  maxRetries?: number;
}

Common return shapes

Single object
List
Async generation
Error

{
  "id": "crs_01HX9...",
  "object": "course",
  "name": "Intro to Special Relativity",
  ...,
  "created_at": "2026-05-10T12:00:00Z",
  "updated_at": "2026-05-10T12:00:00Z"
}

{
  "object": "list",
  "data": [ /* ... */ ],
  "has_more": true,
  "next_cursor": "crs_01HX8..."
}

{
  "id": "crs_01HX9...",
  "status": "pending",
  "estimated_ready_at": "2026-05-10T12:01:30Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "name is required.",
    "fields": { "name": "is required" },
    "request_id": "req_01HX9..."
  }
}

​Top-level resources