> ## 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`는 단일 녹음 세션을 담는 최상위 컨테이너예요. 그 내용은 세 종류의 하위 항목으로 노출돼요. **Paragraphs**(전사), **NoteSummary**(한 페이지 요약), 그리고 **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 경로에서는 `{noteGuid}`로 참조해요. 제목, 소스 타입, 녹음 길이, 협업자 같은 메타데이터를 담아요. 실제 내용은 아래 하위 항목에 들어 있어요.

### Paragraph

Note 전사의 의미 단위예요. 보통 화자 발화 구간이나 주제 덩어리이며, 일반적인 산문 문단이 **아니에요**. 각 Paragraph는 `transcript`, `translated`(번역을 요청한 경우), `summary`(짧은 문단 단위 요약), 그리고 타임스탬프를 담아요. 각 텍스트 필드는 `{ type, content }` 형태의 `TextObject`(`type`은 `text/plain` 또는 `text/markdown`)이며, 전사·번역·요약이 비동기로 완료됨에 따라 단계적으로 non-null이 돼요.

### NoteSummary

Note 전체를 다루는 단일 요약 텍스트 블록이에요. "한 페이지" 요약으로 보이는 것이 바로 이거예요. `content` 필드는 raw 문자열이 아니라 `TextObject`(`{ type, content }`)예요. 하나의 Note는 여러 개의 NoteSummary를 가질 수 있어요(언어나 템플릿이 다를 때). NoteDocument와 달리 섹션으로 나뉘지 않아요.

### NoteDocument

여러 섹션으로 구성된 구조화된 문서예요. 예를 들면 회의록, 액션 아이템, 영업 통화 노트 같은 거예요. 어떤 섹션이 있는지 정의하는 `NoteDocumentTemplate`으로부터 생성돼요. 각 섹션은 개별적으로 렌더링돼요. 자유 형식 요약이 아니라 템플릿 기반의 구조화된 산출물이 필요할 때 사용하세요.

### NoteDocumentTemplate

NoteDocument의 섹션 구조를 정의해요. 플랫폼에서 관리하거나(`isManaged: true`, 예: "회의록") 팀이 커스텀할 수 있어요. NoteDocument를 생성하기 전에 사용 가능한 템플릿을 둘러보고 적절한 형태를 고르세요.

### Folder

Note를 계층적으로 정리해요. 하나의 Note는 최대 하나의 Folder에 속해요. Folder는 사용자 소유이거나 팀 소유일 수 있고, 공유 규칙이 적용돼요.

## 어떤 API를 호출해야 하나요?

| 원하는 것...         | 사용할 API                                        |
| ---------------- | ---------------------------------------------- |
| 노트의 전체 전사        | `GET /v1/external/notes/{noteGuid}/paragraphs` |
| 한 페이지 요약         | `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

**"한 페이지" 요약은 어디에 있나요?**

`NoteSummary`에 있어요. `GET /v1/external/notes/{noteGuid}/summaries`를 호출하세요. `NoteDocument`는 여러 섹션으로 구성된 구조화된 리포트를 위한 것이지, 한 페이지 요약을 위한 게 아니에요.

**NoteSummary와 NoteDocument 중 무엇을 써야 하나요?**

* 단일 요약 텍스트 블록 → `NoteSummary`.
* 여러 섹션으로 구성된 구조화된 리포트(템플릿 기반) → `NoteDocument`.

하나의 Note는 둘 다 가질 수 있어요. 애플리케이션이 기대하는 형태에 맞춰 고르세요. 기능별 비교(사용 가능한 템플릿, 생성 경로, webhook 지원)는 [Summary And Document](/ko/developers/template-based-documents/summary-and-document)를 참고하세요.