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
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 |
{
"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"
}
}
{
"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.
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.
| Type | Format | Example |
|---|
| Date | YYYY-MM-DD | 2026-06-11 |
| Time | HH:MM | 09:00 |