> ## 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 Study Block — POST /blocks Endpoint Reference

> POST /v1/blocks — create a new study block. Requires subject_id, date, start, and end. Returns the created block object with HTTP 201.

Use `POST /v1/blocks` to add a new study block to your schedule. Provide the subject, date, and time range — and optionally a topic. The API returns the created block.

## Endpoint

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

## Body Parameters

<ParamField body="subject_id" type="string" required>
  The ID of the subject this block should belong to. Must be a valid subject ID from your account.
</ParamField>

<ParamField body="date" type="string" required>
  The date for the block in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="start" type="string" required>
  The start time for the block in `HH:MM` format.
</ParamField>

<ParamField body="end" type="string" required>
  The end time for the block in `HH:MM` format. Must be a time after `start` on the same date.
</ParamField>

<ParamField body="topic" type="string">
  An optional topic or syllabus item label for this block.
</ParamField>

## Response

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

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

<ResponseField name="subject_id" type="string">
  The ID of the subject this block belongs to.
</ResponseField>

<ResponseField name="subject_name" type="string">
  The display name of the subject.
</ResponseField>

<ResponseField name="date" type="string">
  The date of the block in `YYYY-MM-DD` format.
</ResponseField>

<ResponseField name="start" type="string">
  The block's start time in `HH:MM` format.
</ResponseField>

<ResponseField name="end" type="string">
  The block's end time in `HH:MM` format.
</ResponseField>

<ResponseField name="topic" type="string">
  The topic label for this block, or `null` if none was provided.
</ResponseField>

<ResponseField name="done" type="boolean">
  Whether the block has been marked as complete. Always `false` on creation.
</ResponseField>

**Example response**

```json theme={null}
{
  "data": {
    "id": "blk_abc123",
    "subject_id": "sub_xyz",
    "subject_name": "JavaScript",
    "date": "2026-06-11",
    "start": "09:00",
    "end": "10:00",
    "topic": "Ch. 3 — Arrays",
    "done": false
  },
  "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/blocks \
    -H "Authorization: Bearer tt_live_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "subject_id": "sub_xyz",
      "date": "2026-06-11",
      "start": "09:00",
      "end": "10:00",
      "topic": "Ch. 3 — Arrays"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.taketime.app/v1/blocks', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer tt_live_your_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subject_id: 'sub_xyz',
      date: '2026-06-11',
      start: '09:00',
      end: '10:00',
      topic: 'Ch. 3 — Arrays',
    }),
  });

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

  if (error) {
    console.error('Failed to create block:', error.code, error.message);
  } else {
    console.log('Created block:', data.id);
  }
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.post(
      "https://api.taketime.app/v1/blocks",
      headers={
          "Authorization": "Bearer tt_live_your_key_here",
          "Content-Type": "application/json",
      },
      json={
          "subject_id": "sub_xyz",
          "date": "2026-06-11",
          "start": "09:00",
          "end": "10:00",
          "topic": "Ch. 3 — Arrays",
      },
  )

  payload = response.json()

  if payload["error"]:
      print("Error:", payload["error"]["code"], payload["error"]["message"])
  else:
      print("Created block:", payload["data"]["id"])
  ```
</CodeGroup>

<Note>
  A newly created block always has `done` set to `false`. Use the [Update Block](/api-reference/blocks/update) endpoint to mark it complete after your session.
</Note>