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

# Create a Subject — POST /subjects Endpoint Reference

> POST /v1/subjects — create a new subject profile with a name, type, optional color, and weekly time slots. Returns the created subject object.

Use `POST /v1/subjects` to create a new subject profile. Choose a type — `study`, `training`, or `inactive` — which determines what content the subject tracks and how its blocks appear in the app.

## Endpoint

```
POST https://api.taketime.app/v1/subjects
```

## Body Parameters

<ParamField body="name" type="string" required>
  Display name for the subject. Maximum 40 characters. Must be unique across your account — the API returns a `VALIDATION_ERROR` if the name is already in use.
</ParamField>

<ParamField body="type" type="string" required>
  The subject type. Must be one of `study`, `training`, or `inactive`. This determines what content fields are available and cannot be changed after creation.
</ParamField>

<ParamField body="color" type="string">
  A hex color code to represent this subject in the app (e.g. `#6366f1`). If omitted, a color is assigned automatically.
</ParamField>

<ParamField body="slots" type="array">
  An array of weekly time slot objects. Each slot defines when this subject is regularly scheduled. If omitted, the subject is created with no scheduled slots.

  Each slot object has the following shape:

  ```json theme={null}
  {
    "days": [1, 3, 5],
    "start": "09:00",
    "end": "10:00"
  }
  ```

  * `days` — array of integers representing days of the week
  * `start` — slot start time in `HH:MM` format
  * `end` — slot end time in `HH:MM` format; must be after `start`
</ParamField>

## Response

Returns the newly created subject object inside the `data` field with HTTP status `201 Created`.

<ResponseField name="id" type="string">
  Unique identifier for the newly created subject.
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the subject.
</ResponseField>

<ResponseField name="type" type="string">
  The subject type: `study`, `training`, or `inactive`.
</ResponseField>

<ResponseField name="color" type="string">
  Hex color code assigned to this subject.
</ResponseField>

<ResponseField name="slots" type="array">
  The weekly time slots configured for this subject. Empty array if none were provided.
</ResponseField>

<ResponseField name="syllabus" type="array">
  Array of syllabus topic objects. Empty on creation. Each item has `title` (string), `duration` (integer, minutes), and `done` (boolean).
</ResponseField>

**Example response**

```json theme={null}
{
  "data": {
    "id": "sub_xyz",
    "name": "JavaScript",
    "type": "study",
    "color": "#6366f1",
    "slots": [
      {
        "days": [1, 3, 5],
        "start": "09:00",
        "end": "10:00"
      }
    ],
    "syllabus": []
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}
```

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.taketime.app/v1/subjects \
    -H "Authorization: Bearer tt_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "JavaScript",
      "type": "study",
      "color": "#6366f1",
      "slots": [
        {
          "days": [1, 3, 5],
          "start": "09:00",
          "end": "10:00"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.taketime.app/v1/subjects', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tt_live_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'JavaScript',
      type: 'study',
      color: '#6366f1',
      slots: [
        {
          days: [1, 3, 5],
          start: '09:00',
          end: '10:00',
        },
      ],
    }),
  });

  const { data, error } = await response.json();

  if (error) {
    console.error('Failed to create subject:', error.code, error.message);
  } else {
    console.log('Created subject:', data.id, data.name);
  }
  ```
</CodeGroup>

<Info>
  After creating a subject, use the [List Blocks](/api-reference/blocks/list) or [Create Block](/api-reference/blocks/create) endpoints to start scheduling study sessions for it.
</Info>