# ブロック API リファレンス

TaskWorks API のタスクブロッキングウィンドウ関連エンドポイントの詳細ドキュメントです。

## 認証方式

### ApiKey 認証（推奨）
```
Authorization: ApiKey <token>
```
- 設定 > APIキー管理 から生成
- トークンは一度しか表示されないため安全に保管
- ほとんどのエンドポイントで使用可能
- ⚠️ このエンドポイントはApiKeyに対応していません

### Bearer トークン認証（必須）
```
Authorization: Bearer <token>
```
- サービス間通信で使用
- このエンドポイントで必須

### Cookie 認証
- 標準のセッションベース認証
- Webクライアントで使用

## 共通レスポンス形式

すべての成功レスポンスは以下の構造に従います：
```json
{
  "data": <response_data>,
  "error": null
}
```

すべてのエラーレスポンスは以下の構造に従います：
```json
{
  "error": "<error_type>",
  "message": "<human_readable_message>",
  "code": "<optional_error_code>",
  "context": <optional_additional_context>
}
```

## HTTP ステータスコード

- 200: 成功
- 201: 作成完了
- 400: 不正なリクエスト（検証エラー）
- 401: 未認証（認証が必要）
- 403: 禁止（権限なし）
- 404: 未検出
- 409: 衝突（リソースの競合）
- 500: サーバー内部エラー

## ページネーション

一部のエンドポイントはカーソルベースのページネーションをサポート：
- cursor: 次ページの開始位置
- limit: 返す項目数（1-100、デフォルトはエンドポイントにより異なる）

レスポンス形式：
```json
{
  "data": {
    "items": [...],
    "nextCursor": "string | null",
    "hasMore": boolean
  },
  "error": null
}
```

## API エンドポイント

### ブロック（Blocks）

#### GET /api/v1/blocks/windows

TaskWorks用タスクブロッキングウィンドウを取得します。

**認証:** ⚠️ Bearer / Session のみ（ApiKey非対応）

**クエリパラメータ:**
- date: string（オプション、ISO 8601形式）
- timezone: string（オプション、デフォルト: "UTC"）
- focus_only: boolean（オプション、デフォルト: false）
- merge: boolean（オプション、デフォルト: false）
- debug: boolean（オプション、デフォルト: false）
- pre_grace_min: number（オプション、デフォルト: 0）
- post_grace_min: number（オプション、デフォルト: 0）
- duration_default_min: number（オプション、デフォルト: 60）

**レスポンス スキーマ（debug: false）:**
```json
{
  "data": [
    {
      "taskId": "string",
      "taskTitle": "string",
      "startTime": "string",
      "endTime": "string",
      "redirectUrl": "string"
    }
  ],
  "error": null
}
```

**レスポンス スキーマ（debug: true）:**
```json
{
  "data": [
    /* Same window objects */
  ],
  "meta": {
    "dateIso": "string",
    "timeZone": "string",
    "focusOnly": boolean,
    "mergeOverlaps": boolean,
    "taskCount": number,
    "completedTaskCount": number,
    "completedCounts": Record<string, number>,
    "windowCount": number
  },
  "error": null
}
```

**エラーケース:**
- 401: 未認証（ApiKeyはサポートされていません）
- 401: ユーザーが見つかりません