> ## Documentation Index
> Fetch the complete documentation index at: https://docs.taketime.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Take Time REST API Reference — Getting Started Guide

> The Take Time API gives programmatic access to study blocks and schedules. All endpoints use Bearer token auth and return a consistent JSON envelope.

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.

```bash theme={null}
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.

<Warning>
  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.
</Warning>

## 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.

```bash theme={null}
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**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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"
  }
}
```

<Info>
  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.
</Info>

## 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                       |

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

## 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.