Take Time REST API Reference — Getting Started Guide

The Take Time API is a REST API that lets you read and manage your study schedule programmatically. Every endpoint requires a Bearer token and returns the same JSON envelope — making error handling predictable and integrations easy to build.

Base URL

All requests are made to the following base URL:

https://api.taketime.app/v1

Authentication

Every request must include your API key as a Bearer token in the Authorization header.

Authorization: Bearer tt_live_your_key_here

API keys are prefixed by environment: tt_live_ keys access your real data; tt_test_ keys operate in sandbox mode and do not affect real data. Generate keys from the Settings → Developer section of the Take Time app.

Keep your API key secret. Do not expose it in client-side code, public repositories, or logs. If a key is compromised, rotate it immediately from your account settings.

Content-Type

For endpoints that accept a request body (POST and PATCH), set the Content-Type header to application/json and send the body as a JSON object.

Content-Type: application/json

Response Envelope

Every response — success or error — is wrapped in the same JSON envelope with three top-level keys.

Key	Type	Description
`data`	object \| array \| null	The response payload on success; `null` on error
`error`	object \| null	Error details on failure; `null` on success
`meta`	object	Request metadata including `request_id` and `timestamp`

Success envelope

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

Error envelope

{
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'start' field is required.",
    "field": "start"
  },
  "meta": {
    "request_id": "req_7d2b1e",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}

The meta.request_id field is useful when contacting support. Include it in any bug reports or support requests so the team can trace the exact request.

Error Codes

When a request fails, the error object in the response envelope contains a code field that identifies the problem.

Code	HTTP Status	Meaning
`VALIDATION_ERROR`	400	Invalid or missing input field
`UNAUTHORIZED`	401	Missing or invalid API key
`NOT_FOUND`	404	Resource doesn’t exist
`RATE_LIMITED`	429	Too many requests — check `Retry-After`
`INTERNAL_ERROR`	500	Server-side error

When you receive a RATE_LIMITED response, check the Retry-After header for the number of seconds to wait before retrying the request.

Pagination

List endpoints return all matching results as an array inside the data field. There is no cursor or page-based pagination at this time — apply query parameter filters (such as date_from / date_to or subject_id) to narrow large result sets.

Date and Time Formats

Type	Format	Example
Date	`YYYY-MM-DD`	`2026-06-11`
Time	`HH:MM`	`09:00`

All times are interpreted in the timezone configured on your Take Time account.

Overview

Blocks

Subjects

Stats & Schedule

Take Time REST API Reference — Getting Started Guide

Base URL

Authentication

Content-Type

Response Envelope

Error Codes

Date and Time Formats

​Base URL

​Authentication

​Content-Type

​Response Envelope

​Error Codes

​Pagination

​Date and Time Formats

Base URL

Authentication

Content-Type

Response Envelope

Error Codes

Pagination

Date and Time Formats