Take Time API Quickstart — First Call in 5 Minutes

This guide walks you through making your first Take Time API call. By the end, you’ll have listed your study blocks and created a new one — all in under 5 minutes.

1. Get your API key

After creating your account at taketime.app, open Settings and generate an API key under the Developer section.

Your API key starts with tt_live_ for production or tt_test_ for sandbox mode. Keep it secret — treat it like a password.

2. Make your first request

List your study blocks for a specific date:

curl -X GET "https://api.taketime.app/v1/blocks?date=2026-06-11" \
  -H "Authorization: Bearer tt_live_your_key_here"

const response = await fetch('https://api.taketime.app/v1/blocks?date=2026-06-11', {
  headers: {
    'Authorization': 'Bearer tt_live_your_key_here'
  }
});
const { data } = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.taketime.app/v1/blocks',
    params={'date': '2026-06-11'},
    headers={'Authorization': 'Bearer tt_live_your_key_here'}
)
data = response.json()['data']
print(data)

3. Create a study block

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": "Arrays & Loops"
  }'

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: 'Arrays & Loops'
  })
});
const { data } = await response.json();

import requests

response = requests.post(
    'https://api.taketime.app/v1/blocks',
    headers={'Authorization': 'Bearer tt_live_your_key_here'},
    json={
        'subject_id': 'sub_xyz',
        'date': '2026-06-11',
        'start': '09:00',
        'end': '10:00',
        'topic': 'Arrays & Loops'
    }
)
data = response.json()['data']

Don’t have a subject_id yet? Call GET /v1/subjects first to list your activities and grab an ID, or create a new subject with POST /v1/subjects.

4. Understand the response format

Every API response follows this structure:

{
  "data": { },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}

When an error occurs, data will be null and error will contain a message and code:

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Start time must be before end time"
  },
  "meta": { }
}

Get Started

Core Concepts

Guides

Take Time API Quickstart — First Call in 5 Minutes

1. Get your API key

2. Make your first request

3. Create a study block

4. Understand the response format

Next steps

Authentication

MCP Server

​1. Get your API key

​2. Make your first request

​3. Create a study block

​4. Understand the response format

​Next steps

Authentication

MCP Server

1. Get your API key

2. Make your first request

3. Create a study block

4. Understand the response format

Next steps