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

# ノートデータモデル

> Noteの構造（Paragraphs、NoteSummary、NoteDocument、NoteDocumentTemplate）と、目的に応じて呼び出すべきAPI

`Note`は、1回の録音セッションを表すトップレベルのコンテナです。その内容は、3種類の子要素を通じて公開されます。**Paragraphs**（トランスクリプト）、**NoteSummary**（1ページの要約）、**NoteDocument**（複数セクションからなる構造化レポート）です。このページでは、各エンティティを整理し、目的に応じてどのAPIを呼び出すべきかを説明します。

## エンティティの関係

```mermaid theme={"system"}
erDiagram
    Note ||--o{ Paragraph : "has"
    Note ||--o{ NoteSummary : "has"
    Note ||--o{ NoteDocument : "has"
    NoteDocumentTemplate ||--o{ NoteDocument : "generates"
    Folder o|--o{ Note : "contains"
```

## エンティティ

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

1つのNoteは両方を持つことができます。アプリケーションが想定する形に応じて選んでください。機能ごとの比較（利用可能なテンプレート、作成方法、Webhookのサポート）については、[Summary And Document](/ja/developers/template-based-documents/summary-and-document)を参照してください。