Create a Study Block — POST /blocks Endpoint Reference

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

string

required

The ID of the subject this block should belong to. Must be a valid subject ID from your account.

string

required

The date for the block in YYYY-MM-DD format.

string

required

The start time for the block in HH:MM format.

string

required

The end time for the block in HH:MM format. Must be a time after start on the same date.

string

An optional topic or syllabus item label for this block.

Response

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

string

Unique identifier for the newly created study block.

string

The ID of the subject this block belongs to.

string

The display name of the subject.

string

The date of the block in YYYY-MM-DD format.

string

The block’s start time in HH:MM format.

string

The block’s end time in HH:MM format.

string

The topic label for this block, or null if none was provided.

boolean

Whether the block has been marked as complete. Always false on creation.

Example response

{
  "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

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"
  }'

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);
}

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"])

A newly created block always has done set to false. Use the Update Block endpoint to mark it complete after your session.

Overview

Blocks

Subjects

Stats & Schedule

Create a Study Block — POST /blocks Endpoint Reference

Endpoint

Body Parameters

Response

Examples

​Endpoint

​Body Parameters

​Response

​Examples

Endpoint

Body Parameters

Response

Examples