API リファレンス

VoiceBookLM バックエンド API の詳細仕様です。

Note

バージョン: 0.0.1-SNAPSHOT
開発環境: http://localhost:8080
本番環境: https://api.voicebooklm.example.com

認証 API (/api/auth)

POST /api/auth/google - Google OAuth ログイン

Google ID トークンを検証し、JWT トークンペアを発行します。新規ユーザーの場合はアカウントを作成します。

認証: 不要

リクエスト:

{
  "idToken": "string (必須) - Google ID トークン"
}

レスポンス:

{
  "accessToken": "string - アクセストークン（1日有効）",
  "refreshToken": "string - リフレッシュトークン（180日間有効）"
}

POST /api/auth/refresh - トークンリフレッシュ

リフレッシュトークンを使用して新しいトークンペアを発行します（トークンローテーション）。

認証: 不要

リクエスト:

{
  "refreshToken": "string (必須) - リフレッシュトークン"
}

レスポンス:

{
  "accessToken": "string - 新しいアクセストークン",
  "refreshToken": "string - 新しいリフレッシュトークン"
}

POST /api/auth/logout - ログアウト

リフレッシュトークンを無効化してログアウトします。

認証: 不要

リクエスト:

{
  "refreshToken": "string (必須) - リフレッシュトークン"
}

レスポンス:

DELETE /api/auth/account - アカウント削除

ユーザーアカウントとすべての関連データを完全に削除します。

認証: 必須（JWT Bearer トークン）

レスポンス:

GET /api/auth/me - 現在のユーザー情報取得

認証済みユーザーの情報を取得します。

認証: 必須（JWT Bearer トークン）

レスポンス:

{
  "id": "UUID - ユーザー ID",
  "email": "string - メールアドレス",
  "name": "string - ユーザー名"
}

音声メモ API (/api/voice)

POST /api/voice/memos - 音声ファイルからメモを生成

音声ファイルをアップロードし、文字起こし → AI整形 → 保存を行います。60秒以内のレスポンスを想定。

認証: 必須（JWT Bearer トークン）

Content-Type: multipart/form-data

リクエスト:

レスポンス:

{
  "memoId": "UUID - メモ ID",
  "title": "string - タイトル",
  "content": "string - 整形されたメモ内容",
  "tags": ["string"],
  "transcription": "string | null - 文字起こしテキスト",
  "transcriptionStatus": "COMPLETED | FAILED | PENDING",
  "formattingStatus": "COMPLETED | FAILED | PENDING",
  "processingTimeMillis": {
    "transcription": "number (ms)",
    "formatting": "number (ms)",
    "persistence": "number (ms)",
    "total": "number (ms)"
  },
  "fallback": {
    "transcription": "boolean",
    "formatting": "boolean"
  }
}

メモ API (/api/memos)

GET /api/memos - メモ一覧取得

認証ユーザーのメモを取得します。フォルダーによるフィルタリング、キーワード検索、ソート、件数制限が可能。

認証: 必須（JWT Bearer トークン）

クエリパラメータ:

レスポンス:

{
  "memos": [
    {
      "memoId": "UUID",
      "title": "string | null",
      "tags": ["string"],
      "transcriptionStatus": "COMPLETED | FAILED | PENDING",
      "formattingStatus": "COMPLETED | FAILED | PENDING",
      "folder": {
        "id": "UUID",
        "name": "string",
        "path": "string"
      },
      "createdAt": "ISO 8601 datetime",
      "updatedAt": "ISO 8601 datetime"
    }
  ]
}

GET /api/memos/{id} - メモ詳細取得

指定されたIDのメモの詳細情報を取得します。セキュリティ上、権限のないメモも404として返します。

認証: 必須（JWT Bearer トークン）

パスパラメータ:

レスポンス:

{
  "memoId": "UUID",
  "title": "string | null",
  "content": "string | null",
  "tags": ["string"],
  "transcriptionText": "string | null",
  "transcriptionStatus": "COMPLETED | FAILED | PENDING",
  "formattingStatus": "COMPLETED | FAILED | PENDING",
  "createdAt": "ISO 8601 datetime",
  "updatedAt": "ISO 8601 datetime"
}

PATCH /api/memos/{id} - メモ更新

メモの部分更新を行います。指定されたフィールドのみ更新されます。

認証: 必須（JWT Bearer トークン）

パスパラメータ:

リクエスト:

{
  "title": "string (任意, 最大100文字)",
  "content": "string (任意)",
  "tags": ["string (任意)"]
}

レスポンス:

{
  "memoId": "UUID",
  "title": "string | null",
  "content": "string | null",
  "tags": ["string"],
  "transcriptionText": "string | null",
  "transcriptionStatus": "COMPLETED | FAILED | PENDING",
  "formattingStatus": "COMPLETED | FAILED | PENDING",
  "createdAt": "ISO 8601 datetime",
  "updatedAt": "ISO 8601 datetime"
}

DELETE /api/memos/{id} - メモ削除

指定されたメモを削除します。

認証: 必須（JWT Bearer トークン）

パスパラメータ:

レスポンス:

POST /api/memos/{id}/resummarize - 再要約

編集された文字起こしテキストから再度AI整形（要約）を行います。

認証: 必須（JWT Bearer トークン）

パスパラメータ:

リクエスト:

{
  "editedTranscription": "string (必須) - 編集された文字起こしテキスト"
}

レスポンス:

{
  "memoId": "UUID",
  "title": "string | null",
  "content": "string | null",
  "tags": ["string"],
  "transcriptionText": "string | null",
  "transcriptionStatus": "COMPLETED | FAILED | PENDING",
  "formattingStatus": "COMPLETED | FAILED | PENDING",
  "createdAt": "ISO 8601 datetime",
  "updatedAt": "ISO 8601 datetime"
}

フォルダー API (/api/folders)

GET /api/folders - フォルダー一覧取得

認証ユーザーのフォルダー一覧をパス情報付きで取得します。

認証: 必須（JWT Bearer トークン）

レスポンス:

{
  "folders": [
    {
      "id": "UUID",
      "name": "string",
      "parentId": "UUID | null",
      "path": "string"
    }
  ]
}

POST /api/folders - フォルダー作成

新しいフォルダーを作成します。親フォルダーを指定して階層構造を作成可能。

認証: 必須（JWT Bearer トークン）

リクエスト:

{
  "name": "string (必須, 最大50文字)",
  "parentId": "UUID (任意) - 親フォルダー ID"
}

レスポンス:

{
  "id": "UUID",
  "name": "string",
  "parentId": "UUID | null",
  "path": "string"
}

PATCH /api/folders/{id} - フォルダー更新

フォルダーのリネームまたは移動を行います。両方同時に指定可能。

認証: 必須（JWT Bearer トークン）

パスパラメータ:

リクエスト:

{
  "name": "string (任意, 最大50文字)",
  "parentId": "UUID (任意) - 新しい親フォルダー ID",
  "moveToRoot": "boolean (必須) - ルートに移動する場合 true"
}

レスポンス:

{
  "id": "UUID",
  "name": "string",
  "parentId": "UUID | null",
  "path": "string"
}

DELETE /api/folders/{id} - フォルダー削除

フォルダーを削除します。子フォルダーまたはメモが存在する場合は削除できません。

認証: 必須（JWT Bearer トークン）

パスパラメータ:

レスポンス:

タグ API (/api/tags)

GET /api/tags - タグ一覧取得

認証ユーザーが使用している全タグを取得します。ソート順と件数制限が指定可能。

認証: 必須（JWT Bearer トークン）

クエリパラメータ:

使用例:

• 人気タグを取得: GET /api/tags?sort=usage_count&order=desc&limit=10

レスポンス:

{
  "tags": ["開発", "コード", "ミーティング"]
}

開発用 API (/api/dev)

Caution

これらの API は 開発環境（dev）でのみ有効です。本番環境では使用できません。

POST /api/dev/token - 開発用トークン取得

指定したメールアドレスのユーザーのアクセストークンを取得します。OAuth不要で、Swagger UIからすぐにAPIテストができます。

認証: 不要

クエリパラメータ:

レスポンス:

{
  "accessToken": "string - アクセストークン（JWT）",
  "userId": "string - ユーザーID",
  "email": "string - メールアドレス",
  "message": "string - 使い方の説明"
}

POST /api/dev/seed - テストデータ作成

認証ユーザー用にテスト用のフォルダーとメモを作成します。データは seed-data.yml から読み込まれます。冪等性を持ち、既にフォルダーが存在する場合はスキップします。

認証: 必須（JWT Bearer トークン）

レスポンス:

{
  "foldersCreated": 3,
  "memosCreated": 10,
  "skipped": false,
  "message": "string - 結果メッセージ"
}

共通仕様

認証方式

JWT (JSON Web Token) を使用。

認証が必要な API には Authorization ヘッダーを設定:

Authorization: Bearer <access_token>

エラーレスポンス

{
  "error": "string - エラーメッセージ",
  "code": "string - エラーコード"
}

OpenAPI ドキュメント

• Swagger UI: http://localhost:8080/swagger-ui.html
• API 仕様 (JSON): http://localhost:8080/v3/api-docs