> ## 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 API Quickstart — First Call in 5 Minutes

> Learn how to authenticate, list your study blocks, and create your first block with the Take Time REST API. Copy-paste examples in cURL, Node.js, and Python.

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](https://taketime.app), open **Settings** and generate an API key under the **Developer** section.

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

## 2. Make your first request

List your study blocks for a specific date:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.taketime.app/v1/blocks?date=2026-06-11" \
    -H "Authorization: Bearer tt_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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)
  ```
</CodeGroup>

## 3. Create a study block

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript Node.js theme={null}
  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();
  ```

  ```python Python theme={null}
  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']
  ```
</CodeGroup>

<Tip>
  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`.
</Tip>

## 4. Understand the response format

Every API response follows this structure:

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

<Warning>
  When an error occurs, `data` will be `null` and `error` will contain a message and code:

  ```json theme={null}
  {
    "data": null,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Start time must be before end time"
    },
    "meta": { }
  }
  ```
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/authentication">
    Deep dive into API keys, key types, and rate limits
  </Card>

  <Card title="MCP Server" icon="bolt" href="/mcp/overview">
    Connect your AI assistant for natural language control
  </Card>
</CardGroup>