> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hawkings.education/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference overview

> Every resource, every method, in one place.

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

## Top-level resources

<CardGroup cols={2}>
  <Card title="Workspaces" icon="building" href="/api-reference/workspaces/object">
    `client.workspaces.*` — tenants holding users and courses.
  </Card>

  <Card title="Courses" icon="book" href="/api-reference/courses/object">
    `client.courses.*` — the syllabus.
  </Card>

  <Card title="Cohorts" icon="users-rectangle" href="/api-reference/cohorts/object">
    `client.cohorts.*` — runs of a course for a group of students.
  </Card>

  <Card title="Lessons" icon="file-lines" href="/api-reference/lessons/object">
    `client.lessons.*` — atomic learning units.
  </Card>

  <Card title="Activities" icon="puzzle-piece" href="/api-reference/activities/object">
    `client.activities.*` — quizzes, flashcards, explainers, podcasts, …
  </Card>

  <Card title="Assignments" icon="clipboard-list" href="/api-reference/assignments/object">
    `client.assignments.*` — gradable artefacts.
  </Card>

  <Card title="Submissions" icon="square-check" href="/api-reference/submissions/object">
    `client.submissions.*` — student responses + grades.
  </Card>

  <Card title="Users" icon="user" href="/api-reference/users/object">
    `client.users.*` plus sugar `students.*` / `teachers.*`.
  </Card>

  <Card title="SCORM" icon="box-archive" href="/api-reference/scorm/object">
    `client.scorm.*` — export packages.
  </Card>
</CardGroup>

## 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:

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

Every retrieve call:

```ts theme={null}
{
  expand?: string[];
}
```

Every create / update call accepts an options bag:

```ts theme={null}
{
  idempotencyKey?: string;   // see Errors & retries
  maxRetries?: number;
}
```

## Common return shapes

<Tabs>
  <Tab title="Single object">
    ```json theme={null}
    {
      "id": "crs_01HX9...",
      "object": "course",
      "name": "Intro to Special Relativity",
      ...,
      "created_at": "2026-05-10T12:00:00Z",
      "updated_at": "2026-05-10T12:00:00Z"
    }
    ```
  </Tab>

  <Tab title="List">
    ```json theme={null}
    {
      "object": "list",
      "data": [ /* ... */ ],
      "has_more": true,
      "next_cursor": "crs_01HX8..."
    }
    ```
  </Tab>

  <Tab title="Async generation">
    ```json theme={null}
    {
      "id": "crs_01HX9...",
      "status": "pending",
      "estimated_ready_at": "2026-05-10T12:01:30Z"
    }
    ```
  </Tab>

  <Tab title="Error">
    ```json theme={null}
    {
      "error": {
        "type": "invalid_request_error",
        "code": "missing_field",
        "message": "name is required.",
        "fields": { "name": "is required" },
        "request_id": "req_01HX9..."
      }
    }
    ```
  </Tab>
</Tabs>