Skip to main content
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

​
subject_id
string
required
The ID of the subject this block should belong to. Must be a valid subject ID from your account.
​
date
string
required
The date for the block in YYYY-MM-DD format.
​
start
string
required
The start time for the block in HH:MM format.
​
end
string
required
The end time for the block in HH:MM format. Must be a time after start on the same date.
​
topic
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.
​
id
string
Unique identifier for the newly created study block.
​
subject_id
string
The ID of the subject this block belongs to.
​
subject_name
string
The display name of the subject.
​
date
string
The date of the block in YYYY-MM-DD format.
​
start
string
The block’s start time in HH:MM format.
​
end
string
The block’s end time in HH:MM format.
​
topic
string
The topic label for this block, or null if none was provided.
​
done
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"
  }'
A newly created block always has done set to false. Use the Update Block endpoint to mark it complete after your session.