jaysnote
10분

[LLM Wiki 12] Confluence REST API로 회의록을 검색하고 쓰는 법

Confluence REST API의 검색, 읽기, 쓰기, 구조 탐색, 수정일과 버전 조회를 회의록 LLM Wiki 관점에서 설명한다.

#LLM Wiki #Confluence #REST API #CQL #회의록

Confluence REST API를 보는 지도

Confluence를 회의록 LLM Wiki의 원본 저장소로 쓸 수 있다. 이때 핵심은 Confluence를 “사람이 보는 협업 문서”로 두고, REST API를 통해 검색, 읽기, 쓰기, 구조 탐색, 버전 조회를 안정적으로 처리하는 것이다.

Confluence API는 크게 다섯 묶음으로 이해하면 쉽다.

  • Search: CQL로 글을 찾는다.
  • Read: page id로 제목, 본문, 메타데이터를 읽는다.
  • Write: 새 글을 만들거나 기존 글을 수정한다.
  • Tree: children, ancestors로 문서 구조를 탐색한다.
  • Version: 수정일, 수정자, 버전 이력을 확인한다.

Cloud 기준 기본 경로는 보통 다음 형태다.

https://{site}.atlassian.net/wiki/api/v2/...

구버전 v1 API도 여전히 많이 쓰인다.

https://{site}.atlassian.net/wiki/rest/api/...

새로 설계한다면 v2를 우선 보고, 기존 예제나 일부 expand 패턴이 필요하면 v1을 함께 확인하는 방식이 현실적이다.

인증 구조

개인 자동화에서는 이메일과 API token을 이용한 Basic Auth를 가장 많이 쓴다.

curl -u "[email protected]:API_TOKEN" \\
  "https://your-domain.atlassian.net/wiki/api/v2/pages/{pageId}"

앱이나 서비스 계정으로 붙일 때는 OAuth 2.0을 쓰는 편이 낫다. 사내 설치형 Confluence Data Center는 Personal Access Token이나 서버 설정에 따른 인증 방식을 쓴다.

API 토큰의 권한은 검색 결과에도 직접 영향을 준다. 토큰 사용자가 볼 수 없는 문서는 검색 결과에도 나오지 않는다.

검색 API와 CQL

Confluence 검색 결과가 만들어지는 흐름

Confluence 검색의 중심은 CQL이다. CQL은 Confluence Query Language의 줄임말이다. SQL처럼 보이지만 데이터베이스 SQL은 아니고, Confluence 문서 검색용 조건 언어다.

예를 들어 특정 스페이스에서 회의록을 찾으려면 이렇게 쓸 수 있다.

space = "MEETING" AND type = page AND title ~ "회의록"

본문까지 검색하려면 text 조건을 쓴다.

space = "MEETING"
AND type = page
AND text ~ "가격정책"

날짜 조건도 중요하다.

space = "MEETING"
AND type = page
AND created >= "2026-06-01"
AND created < "2026-07-01"
ORDER BY created ASC

특정 상위 페이지 아래에서만 찾고 싶다면 ancestor를 쓴다.

ancestor = 123456789
AND type = page
AND text ~ "QMD"

회의록 시스템에서는 ancestor가 특히 중요하다. “회의록 루트 페이지 아래 문서만 검색” 같은 범위 제한을 만들 수 있기 때문이다.

검색 결과는 어떤 기준으로 나오나

Confluence 검색 결과는 단순 최신순이 아니다. 기본 검색에서는 CQL 조건, 권한 필터, 검색 인덱스, relevance 점수가 함께 작동한다.

대략 이런 요소가 영향을 준다.

  • API 사용자가 볼 수 있는 문서만 남는다.
  • CQL 조건에 맞는 문서만 남는다.
  • 제목, 본문, 첨부 텍스트 등 인덱싱된 내용이 검색된다.
  • 제목 매칭이 본문 매칭보다 더 강하게 작용할 수 있다.
  • Confluence 내부 검색 인덱스의 relevance 점수로 정렬될 수 있다.

다만 정확한 랭킹 공식은 안정적인 API 계약처럼 공개되어 있다고 보기 어렵다. 그래서 중요한 검색은 기본 relevance에만 맡기면 안 된다.

예를 들어 “6월 회의록 전체”를 찾는다면 relevance보다 날짜 정렬이 더 중요하다.

space = "MEETING"
AND type = page
AND created >= "2026-06-01"
AND created < "2026-07-01"
ORDER BY created ASC

반대로 “가격정책을 가장 잘 설명한 문서”를 찾는다면 relevance가 유용할 수 있다. 하지만 업무 자동화에서는 날짜, 공간, 상위 페이지, label, type을 함께 걸어 검색 범위를 좁히는 편이 안정적이다.

글 읽기 API

페이지 하나를 읽을 때는 page id가 필요하다.

GET /wiki/api/v2/pages/{pageId}

본문까지 읽고 싶으면 body format을 지정한다.

GET /wiki/api/v2/pages/{pageId}?body-format=storage
GET /wiki/api/v2/pages/{pageId}?body-format=atlas_doc_format

storage는 Confluence 저장용 XHTML에 가까운 형식이다. 자동화에서 다루기 비교적 쉽다.

atlas_doc_format은 Atlassian의 JSON 문서 포맷이다. 구조적이지만 직접 수정하기는 더 복잡하다.

간단한 자동 생성과 수정은 storage로 시작하는 편이 쉽다. 에디터 내부 구조를 정교하게 보존해야 하면 atlas_doc_format을 검토한다.

글 쓰기 API와 버전 번호

Confluence 글 수정은 version 번호가 핵심이다

새 페이지 생성은 POST /wiki/api/v2/pages로 한다. 필요한 값은 대략 spaceId, title, parentId, body다.

{
  "spaceId": "123456",
  "status": "current",
  "title": "2026-06-28 주간 회의록",
  "parentId": "987654",
  "body": {
    "representation": "storage",
    "value": "<h1>회의록</h1><p>내용...</p>"
  }
}

기존 페이지 수정은 더 조심해야 한다.

PUT /wiki/api/v2/pages/{pageId}

Confluence에서는 수정할 때 version number를 반드시 올려야 한다. 현재 문서가 version 7이면, 수정 요청은 version 8로 보내야 한다.

{
  "id": "123456789",
  "status": "current",
  "title": "수정된 제목",
  "body": {
    "representation": "storage",
    "value": "<p>수정된 내용</p>"
  },
  "version": {
    "number": 8,
    "message": "회의록 요약 업데이트"
  }
}

그래서 수정 플로우는 항상 이 순서를 따른다.

  • 먼저 page를 읽는다.
  • 현재 version.number를 확인한다.
  • 본문 수정안을 만든다.
  • version.number + 1로 PUT 요청을 보낸다.
  • 저장된 페이지를 다시 읽어 version, 수정일, 작성자를 기록한다.

LLM이 Confluence 글을 수정하는 시스템이라면 이 단계가 특히 중요하다. 다른 사람이 방금 문서를 수정했을 수 있기 때문이다. 버전 충돌은 귀찮은 에러가 아니라 협업 문서를 보호하는 안전장치다.

수정일과 버전 조회

페이지 조회 결과에는 보통 id, title, spaceId, parentId, status, createdAt, version 정보가 들어 있다. 실무에서 마지막 수정일은 최신 version의 createdAt을 보는 경우가 많다.

버전 목록은 페이지별로 조회할 수 있다.

GET /wiki/api/v2/pages/{pageId}/versions

특정 버전도 조회할 수 있다.

GET /wiki/api/v2/pages/{pageId}/versions/{versionNumber}

이 정보는 다음 용도에 필요하다.

  • 누가 언제 수정했는지 확인
  • LLM 자동 수정 전후 비교
  • 잘못된 수정의 롤백 후보 찾기
  • 월간 회의록 요약이 어느 버전을 근거로 했는지 기록
  • 외부 검색 인덱스를 언제 재색인해야 하는지 판단

회의록 LLM Wiki에서는 pageId와 version number를 반드시 함께 저장하는 것이 좋다. 그래야 “이 요약은 어느 시점의 Confluence 문서를 읽고 만든 것인가”를 추적할 수 있다.

구조 탐색과 월간 요약

“6월 회의록 전체 요약”은 구조 탐색으로 시작한다

Confluence는 문서 트리 구조를 가진다. 스페이스 아래에 페이지가 있고, 페이지 아래에 자식 페이지가 있다.

회의록이 잘 정리되어 있다면 검색보다 구조 탐색이 더 안정적일 때가 많다.

예를 들어 “6월 회의록 전체 요약”은 이렇게 처리할 수 있다.

  • 회의록 루트 pageId를 찾는다.
  • children API로 2026 페이지를 찾는다.
  • 다시 children API로 06 페이지를 찾는다.
  • 06 페이지 아래의 회의록 page 목록을 가져온다.
  • 각 page의 본문과 version을 읽는다.
  • LLM이 월간 요약을 작성한다.

구조가 깔끔하지 않다면 CQL로 보완한다.

ancestor = {회의록루트ID}
AND type = page
AND created >= "2026-06-01"
AND created < "2026-07-01"
ORDER BY created ASC

즉 구조 탐색과 검색은 경쟁 관계가 아니다. 구조 탐색은 범위를 안정적으로 좁히고, CQL 검색은 그 안에서 필요한 문서를 찾는다.

Confluence와 LLM Wiki를 함께 쓰는 구조

Confluence 위에 회의록 LLM Wiki를 붙이는 구조

Confluence API만으로도 작은 자동화는 가능하다. 하지만 회의록이 많아지면 Confluence API만으로 모든 검색과 요약을 처리하는 구조는 느리고 불안정해질 수 있다.

큰 시스템에서는 역할을 나누는 편이 좋다.

  • Confluence는 원본 저장소와 사람용 협업 UI다.
  • REST API sync는 검색, 읽기, 구조 탐색, 버전 조회, 쓰기를 담당한다.
  • Metadata DB는 pageId, spaceId, parentId, 날짜, version, 수정일을 저장한다.
  • Search Index는 BM25와 vector search를 맡는다.
  • LLM Wiki Layer는 Meeting, Decision, Action, Project 카드와 월간 요약을 관리한다.
  • Confluence Write Back은 검토된 결과만 version + 1로 반영한다.

이 구조를 쓰면 Confluence를 버리지 않고도 LLM Wiki 방식으로 확장할 수 있다. 사람은 Confluence에서 문서를 보고, 시스템은 API로 필요한 정보를 읽고, 별도 인덱스와 LLM Wiki 계층에서 검색과 요약 품질을 높인다.

Confluence는 좋은 원본 저장소다. 하지만 대규모 자연어 검색, 관계 추적, 월간 요약, LLM 기반 갱신까지 맡기기에는 별도 검색 인덱스와 메타데이터 계층을 붙이는 편이 더 안정적이다.

관련 글

← 목록으로