Noteは、1回の録音セッションを表すトップレベルのコンテナです。その内容は、3種類の子要素を通じて公開されます。Paragraphs（トランスクリプト）、NoteSummary（1ページの要約）、NoteDocument（複数セクションからなる構造化レポート）です。このページでは、各エンティティを整理し、目的に応じてどのAPIを呼び出すべきかを説明します。
エンティティの関係
エンティティ
Note
録音セッションが開始されたとき（または音声・テキストがインポートされたとき）に作成されるコンテナです。guidフィールドで識別され、API pathでは{noteGuid}として参照されます。タイトル、ソースタイプ、録音時間、共同作業者などのメタデータを保持します。実際の内容は、以下の子要素に含まれます。
Paragraph
Noteのトランスクリプトの意味的な単位です。通常は話者の発話のまとまりやトピックの区切りであり、文章としての段落（prose paragraph）ではありません。各Paragraphはtranscript、translated（翻訳がリクエストされた場合）、summary（paragraphレベルの短い要約）、およびタイムスタンプを保持します。各テキストフィールドは{ type, content }という形のTextObjectであり（typeはtext/plainまたはtext/markdown）、これらのフィールドは、文字起こし、翻訳、要約が非同期に完了するにつれて、段階的にnullでない値になります。
NoteSummary
Note全体をカバーする1つの要約テキストのブロックです。「1ページ」要約として表示されるものにあたります。そのcontentフィールドは生の文字列ではなく、TextObject（{ type, content }）です。1つのNoteは複数のNoteSummary（異なる言語やテンプレート）を持つことができます。NoteDocumentとは異なり、セクションに分かれていません。
NoteDocument
複数セクションからなる構造化されたドキュメントです。たとえば、議事録、アクションアイテム、営業コールのノートなどです。どのセクションが存在するかを定義するNoteDocumentTemplateから生成されます。各セクションは個別にレンダリングされます。自由形式の要約ではなく、テンプレート化された構造的な成果物が必要な場合に使用します。
NoteDocumentTemplate
NoteDocumentのセクション構造を定義します。プラットフォーム管理（isManaged: true、例:「Meeting Minutes」）か、チームのカスタムのいずれかです。NoteDocumentを作成する前に利用可能なテンプレートを確認し、適切な形を選べるようにしてください。
Folder
Noteを階層的に整理します。1つのNoteは最大で1つのFolderに属します。Folderはユーザー所有またはチーム所有のいずれかで、共有ルールを持ちます。どのAPIを呼び出すべきか
| やりたいこと | 使用するAPI |
|---|---|
| ノートの完全なトランスクリプト | GET /v1/external/notes/{noteGuid}/paragraphs |
| 1ページの要約 | GET /v1/external/notes/{noteGuid}/summaries |
| 構造化レポート（議事録など） | GET /v1/external/notes/{noteGuid}/documents |
| 利用可能なドキュメントテンプレート | GET /v1/external/note-document-templates |
| フォルダの詳細 | GET /v1/external/teams/me/folders/{folderId} |
FAQ
「1ページ」要約はどこにありますか？NoteSummaryにあります。GET /v1/external/notes/{noteGuid}/summariesを呼び出してください。NoteDocumentは複数セクションの構造化レポート向けであり、1ページの要約向けではありません。
NoteSummaryとNoteDocumentのどちらを使うべきですか？
- 1つの要約テキストのブロック →
NoteSummary。 - 複数セクションの構造化レポート（テンプレート駆動）→
NoteDocument。