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

# Create a course

> Create an empty course (status `draft`). Generate a syllabus next.

## Parameters

<ParamField body="name" type="string" required>
  Human-readable course name.
</ParamField>

<ParamField body="language" type="string" required>
  BCP-47 language code: `"en"`, `"es"`, `"pt-BR"`, etc.
</ParamField>

<ParamField body="description" type="string">
  Long-form description; doubles as the default brief when you call
  `generateSyllabus()` without one.
</ParamField>

<ParamField body="hours" type="integer" default="8">
  Target total student hours.
</ParamField>

<ParamField body="ai" type="object">
  <Expandable title="properties">
    <ParamField body="instructions" type="string">
      Free-text guidance applied to every AI call scoped to this course.
    </ParamField>

    <ParamField body="evaluator" type="object">
      Default rubric / model for assignments in this course.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tutor" type="object">
  Tutor configuration. See [Build an AI tutor](/guides/build-an-ai-tutor).
</ParamField>

<ParamField body="metadata" type="object">
  Free-form key-value store.
</ParamField>

## Returns

A [Course](/api-reference/courses/object) with `status: "draft"`.

## Examples

<CodeGroup>
  ```ts TypeScript theme={null}
  const course = await hk.courses.create({
    name: "Intro to Special Relativity",
    language: "en",
    hours: 12,
    description: "An undergraduate intro course...",
  });
  ```

  ```php PHP theme={null}
  $course = $hk->courses->create([
      'name' => 'Intro to Special Relativity',
      'language' => 'en',
      'hours' => 12,
      'description' => 'An undergraduate intro course...',
  ]);
  ```

  ```python Python theme={null}
  course = hk.courses.create(
      name="Intro to Special Relativity",
      language="en",
      hours=12,
  )
  ```

  ```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>

```json Response theme={null}
{
  "id": "crs_01HX9N5AB3...",
  "object": "course",
  "name": "Intro to Special Relativity",
  "language": "en",
  "duration": { "hours": 12, "hours_generated": 0 },
  "status": "draft",
  "cohorts": [],
  "created_at": "2026-05-10T12:00:00Z"
}
```

<Tip>
  A course on its own has no lessons. Either call
  [`generateSyllabus`](/api-reference/courses/generate-syllabus) for an
  AI-built tree, or create units, lessons, and content by hand.
</Tip>