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

​
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"
  }'
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": { }
}

​
Next steps

Authentication

Deep dive into API keys, key types, and rate limits

MCP Server

Connect your AI assistant for natural language control