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

# Quickstart

> From zero to your first AI-generated lesson in under 60 seconds.

## 1. Get an API key

Grab a key from [your dashboard](https://app.hawkings.education/api-keys).
Keys start with `hk-` and are scoped to a single workspace.

```bash theme={null}
export HAWKINGS_API_KEY="hk-..."
```

<Tip>
  Test keys are unmetered for the first 10,000 requests. You won't be
  billed for anything you build in this guide.
</Tip>

## 2. Install the SDK

<CodeGroup>
  ```bash npm theme={null}
  npm install @hawkings/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @hawkings/sdk
  ```

  ```bash yarn theme={null}
  yarn add @hawkings/sdk
  ```

  ```bash bun theme={null}
  bun add @hawkings/sdk
  ```

  ```bash composer theme={null}
  composer require hawkings/sdk
  ```
</CodeGroup>

Officially supported: **Node 18+**, Deno, Bun, Cloudflare Workers, Vercel
Edge, **PHP 8.1+**. Python and Go SDKs are in private beta —
[join the list](https://hawkings.education/sdk).

## 3. Make your first call

<CodeGroup>
  ```ts TypeScript theme={null}
  import Hawkings from "@hawkings/sdk";

  const hk = new Hawkings();

  const course = await hk.courses.create({
    name: "Intro to Special Relativity",
    language: "en",
    hours: 12,
  });

  console.log(course.id);
  ```

  ```php PHP theme={null}
  $hk = new \Hawkings\Client();

  $course = $hk->courses->create([
      'name' => 'Intro to Special Relativity',
      'language' => 'en',
      'hours' => 12,
  ]);

  echo $course->id;
  ```

  ```python Python theme={null}
  from hawkings import Hawkings

  hk = Hawkings()

  course = hk.courses.create(
      name="Intro to Special Relativity",
      language="en",
      hours=12,
  )

  print(course.id)
  ```

  ```bash curl theme={null}
  curl https://api.hawkings.education/v1/courses \
    -H "x-api-key: $HAWKINGS_API_KEY" \
    -H "X-Learning-Platform-Code: $HAWKINGS_PLATFORM_CODE" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Intro to Special Relativity",
      "language": "en",
      "hours": 12
    }'
  ```
</CodeGroup>

You should see something like:

```json theme={null}
{
  "id": "crs_01HX9N5AB3...",
  "name": "Intro to Special Relativity",
  "language": "en",
  "hours": 12,
  "status": "draft",
  "created_at": "2026-05-10T12:00:00Z"
}
```

## 4. Let the AI write the syllabus

<CodeGroup>
  ```ts TypeScript theme={null}
  await hk.courses.generateSyllabus(course.id, {
    brief: "An introductory undergraduate course on special relativity, " +
           "ending with the equivalence of mass and energy.",
  });

  // Poll until ready (≈ 30s)
  const ready = await hk.poll(() => hk.courses.retrieve(course.id), {
    until: c => c.status === "ready",
  });
  ```

  ```php PHP theme={null}
  $hk->courses->generateSyllabus($course->id, [
      'brief' => 'An introductory undergraduate course on special relativity, '
               . 'ending with the equivalence of mass and energy.',
  ]);

  // Poll until ready (≈ 30s)
  $ready = $hk->poll(
      fn () => $hk->courses->retrieve($course->id),
      ['until' => fn ($c) => $c->status === 'ready'],
  );
  ```
</CodeGroup>

When that resolves, your course has units, lessons, and learning
objectives. You're ready to [generate activities](/api-reference/activities/generate)
or [export to SCORM](/guides/export-to-scorm).

## 5. Read it back

<CodeGroup>
  ```ts TypeScript theme={null}
  const full = await hk.courses.retrieve(course.id, {
    expand: ["cohorts", "cohorts.lessons", "cohorts.lessons.activities"],
  });
  ```

  ```php PHP theme={null}
  $full = $hk->courses->retrieve($course->id, [
      'expand' => ['cohorts', 'cohorts.lessons', 'cohorts.lessons.activities'],
  ]);
  ```
</CodeGroup>

The `expand` option works on every retrieval. See
[Pagination & expanding](/pagination-and-expanding).

## What's next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    API keys, scopes, and the difference between user keys and platform keys.
  </Card>

  <Card title="Data model" icon="diagram-project" href="/concepts/data-model">
    The full graph: workspaces → courses → cohorts → lessons → activities.
  </Card>

  <Card title="AI generation" icon="wand-magic-sparkles" href="/concepts/ai-generation">
    How async generation works, polling vs. webhooks, and grounded research.
  </Card>

  <Card title="Errors & retries" icon="triangle-exclamation" href="/errors-and-retries">
    Error taxonomy, automatic retries, and idempotency keys.
  </Card>
</CardGroup>