MDEX Knowledge Engine

MDEX API 사용 가이드

원문 마크다운(MD)을 수정 없이 보존하고, 그 위에 연결 정보 인덱스를 얹어 AI가 필요한 문서를 정확히 찾아 열람할 수 있게 하는 지식 저장소입니다.

서버 도메인: https://mdex.r-e.kr 보관 문서 수: 0개 연결 인덱스: 0개 OpenAI 호환 AI 연동: true

1. 원문 불변 & 버전 관리

업로드된 MD 원문은 단 1바이트도 수정하지 않고 보존합니다. 동일 문서(ID·슬러그·제목 일치)를 재업로드하면 덮어쓰지 않고 새 버전(v1, v2...)으로 쌓입니다.

2. 하이브리드 검색

키워드, 벡터 임베딩, 엔티티/태그 일치를 결합하여 문서 단위로 묶어 반환하며, 왜 검색되었는지 일치 이유(match_reasons)를 함께 제공합니다.

3. 유기적 관련 문서 확장

작성자가 본문에 적은 링크([[문서]], [링크](문서.md)), 역참조, 공유 엔티티, 의미 유사도를 바탕으로 관련 문서(related_docs)를 함께 제안합니다.

1. 인증 및 토큰 발급 안내

모든 API 호출은 역할이 분리된 쓰기 토큰(write) 또는 읽기 토큰(read)이 필요합니다. 토큰은 텔레그램 봇에서 신청 후 관리자 승인을 거쳐 발급됩니다.

쓰기 토큰 신청: 텔레그램 봇에 /request_write <토큰명칭> 전송 (사용자별 토큰 명칭 중복 불가)
읽기 토큰 신청: 텔레그램 봇에 /request_read <토큰명칭> 전송
내 토큰 조회 및 제거: /mytokens (인라인 버튼으로 2단계 확인 후 제거 가능)

토큰 전달 방법 (택 1)

권장: HTTP 헤더 Authorization: Bearer <발급받은_토큰>
대체 헤더: X-MDEX-Token: <발급받은_토큰>
쿼리 파라미터: ?token=<발급받은_토큰>

요청 속도 제한 (사용자별 공유 토큰 버킷 + 시간당 상한)

동일 사용자의 모든 토큰(쓰기·읽기)은 하나의 사용자 버킷을 공유합니다.
기본 버킷 최대 보유량: 100 / 기본 분당 적립량: +30 / 분 (시간당 상한과 함께 적용)
토큰 소모량: 쓰기 토큰(저장 API) 호출 시 20 소모, 읽기 토큰(검색·열람 API) 호출 시 1 소모
한도 초과 시 HTTP 429 Too Many Requests 및 Retry-After 헤더가 반환되며, 관리자가 텔레그램 봇에서 이용자별로 상한과 적립량을 조정할 수 있습니다.

2. 역할 분리된 3대 API 요약

역할	메서드 및 경로	필요 토큰	핵심 동작
저장	`POST /api/documents` (별칭: `POST /api/save`)	쓰기 토큰 (write)	MD 원문을 수정 없이 보관 (재업로드 시 새 버전 적재 + 요약/엔티티/임베딩 인덱스 자동 생성)
검색	`GET\|POST /api/search`	읽기 토큰 (read)	연관된 MD 목록 반환 (제목, 요약, 일치 이유, 관련 문서 제안)
열람	`GET /api/documents/{id}` (별칭: `GET /api/view?id=...`)	읽기 토큰 (read)	선택한 MD 원문 반환 (`?format=raw` 시 순수 마크다운 원문 바이트 반환, `?version=N` 특정 버전 열람)

3. API 상세 사용법 및 예제

POST /api/documents — 문서 원문 저장

쓰기 토큰 (write) 필수

마크다운 원문을 수정 없이 보관합니다. text/markdown 바이트 직접 전송 또는 application/json 방식을 모두 지원합니다. 동일한 id, slug, 또는 # 제목으로 다시 업로드하면 자동으로 v2, v3 등 새 버전으로 쌓입니다.

방식 A: 순수 마크다운(text/markdown) 원문 업로드

선택 쿼리 파라미터: ?slug=문서슬러그&title=문서제목&id=문서ID (생략 시 본문 첫 # 제목에서 자동 추출)

curl -X POST "https://mdex.r-e.kr/api/documents?slug=mdex-overview" \
  -H "Authorization: Bearer mdex_w_YOUR_WRITE_TOKEN" \
  -H "Content-Type: text/markdown; charset=utf-8" \
  --data-binary $'# MDEX 아키텍처 개요\n\n원문 마크다운을 수정 없이 보관합니다.\n관련 문서: [[하이브리드 검색 가이드]]\n#MDEX #아키텍처'

방식 B: JSON(application/json) 업로드

curl -X POST "https://mdex.r-e.kr/api/documents" \
  -H "Authorization: Bearer mdex_w_YOUR_WRITE_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "slug": "mdex-overview",
    "title": "MDEX 아키텍처 개요",
    "content": "# MDEX 아키텍처 개요\n\n원문 마크다운을 수정 없이 보관합니다.\n관련 문서: [[하이브리드 검색 가이드]]\n#MDEX #아키텍처"
  }'

응답 예시 (201 Created)

{
  "ok": true,
  "message": "MD 원문이 수정 없이 보관되었으며 연결 인덱스가 갱신되었습니다.",
  "document": {
    "id": "doc_1c95e00d5bbc",
    "slug": "mdex-overview",
    "title": "MDEX 아키텍처 개요",
    "version": 1,
    "latest_version": 1,
    "sha256": "d97603e05c78d0e72d6871bb4f94653cf97e595ec5c9f9c1e00f2e937a9278a5",
    "size_bytes": 168,
    "owner_id": 1346390843,
    "owner_name": "홍길동 (@gildong)",
    "created_at": "2026-11-04T12:30:00+09:00"
  },
  "index": {
    "summary": "MDEX는 원문 마크다운을 수정 없이 보관하고 연결 인덱스를 생성하는 지식 저장소이다.",
    "tags": ["MDEX", "아키텍처"],
    "entities": ["MDEX 아키텍처 개요", "하이브리드 검색 가이드"],
    "outgoing_links": ["하이브리드 검색 가이드"],
    "indexed_by_ai": true
  }
}

GETPOST /api/search — 하이브리드 검색 및 관련 문서 확장

읽기 토큰 (read) 필수

질의어(q 또는 query)와 관련해 키워드, 엔티티/태그 일치, 벡터 임베딩 유사도를 합산하여 문서 단위로 묶어 반환합니다. 각 결과에는 제목, 요약, 일치 이유(match_reasons), 유기적 관련 문서(related_docs)가 포함됩니다.

GET 방식 호출

curl -G "https://mdex.r-e.kr/api/search" \
  -H "Authorization: Bearer mdex_r_YOUR_READ_TOKEN" \
  --data-urlencode "q=임베딩과 엔티티 일치를 합친 하이브리드 검색" \
  --data-urlencode "limit=5"

POST 방식 호출 (AI 에이전트 / 도구 연동 권장)

curl -X POST "https://mdex.r-e.kr/api/search" \
  -H "Authorization: Bearer mdex_r_YOUR_READ_TOKEN" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "query": "임베딩과 엔티티 일치를 합친 하이브리드 검색",
    "limit": 5
  }'

응답 예시 (200 OK)

{
  "ok": true,
  "query": "임베딩과 엔티티 일치를 합친 하이브리드 검색",
  "count": 1,
  "results": [
    {
      "id": "doc_ae95d4b398da",
      "slug": "hybrid-search",
      "title": "하이브리드 검색 가이드",
      "summary": "키워드, 벡터 임베딩, 엔티티 일치를 결합한 하이브리드 검색과 링크 기반 관련 문서 확장을 설명한다.",
      "latest_version": 1,
      "owner_name": "홍길동 (@gildong)",
      "updated_at": "2026-11-04 12:31:00",
      "score": 1.22,
      "match_reasons": [
        "엔티티 일치: 하이브리드 검색, 벡터 임베딩, 엔티티 일치",
        "태그 일치: #검색, #임베딩",
        "키워드 일치 (5/5): 검색, 엔티티, 일치, 임베딩, 하이브리드"
      ],
      "tags": ["검색", "임베딩", "MDEX"],
      "entities": ["하이브리드 검색 가이드", "벡터 임베딩", "엔티티 일치"],
      "related_docs": [
        {
          "id": "doc_1c95e00d5bbc",
          "slug": "mdex-overview",
          "title": "MDEX 아키텍처 개요",
          "summary": "MDEX는 원문 마크다운을 수정 없이 보관하고 연결 인덱스를 생성하는 지식 저장소이다.",
          "relation_type": "explicit_link",
          "reason": "작성자 직접 링크 (→ MDEX 아키텍처 개요) | 공유 태그: #MDEX",
          "score": 1.45
        }
      ]
    }
  ]
}

GET /api/documents/{id_or_slug} — 문서 원문 열람

읽기 토큰 (read) 필수

검색 결과에서 선택한 문서의 id 또는 slug로 불변 마크다운 원문을 열람합니다.

?version=N: 특정 버전 지정 (생략 시 최신 버전 반환)
?format=raw (또는 Accept: text/markdown 헤더): JSON 래퍼 없이 순수 마크다운 원문 바이트 그대로 반환

1) JSON 형식으로 원문 + 버전 이력 열람

curl "https://mdex.r-e.kr/api/documents/mdex-overview" \
  -H "Authorization: Bearer mdex_r_YOUR_READ_TOKEN"

2) 순수 마크다운 원문(Raw Markdown) 그대로 열람 및 특정 버전 조회

curl "https://mdex.r-e.kr/api/documents/mdex-overview?version=1&format=raw" \
  -H "Authorization: Bearer mdex_r_YOUR_READ_TOKEN"

JSON 열람 응답 예시 (200 OK)

{
  "ok": true,
  "id": "doc_1c95e00d5bbc",
  "slug": "mdex-overview",
  "title": "MDEX 아키텍처 개요",
  "version": 1,
  "latest_version": 1,
  "sha256": "d97603e05c78d0e72d6871bb4f94653cf97e595ec5c9f9c1e00f2e937a9278a5",
  "size_bytes": 168,
  "owner_id": 1346390843,
  "owner_name": "홍길동 (@gildong)",
  "created_at": "2026-11-04T12:30:00+09:00",
  "content": "# MDEX 아키텍처 개요\n\n원문 마크다운을 수정 없이 보관합니다.\n관련 문서: [[하이브리드 검색 가이드]]\n#MDEX #아키텍처",
  "versions": [
    {
      "version": 1,
      "raw_path": "raw/doc_1c95e00d5bbc/v1.md",
      "sha256": "d97603e05c78d0e72d6871bb4f94653cf97e595ec5c9f9c1e00f2e937a9278a5",
      "size_bytes": 168,
      "uploaded_by": 1346390843,
      "uploader": "홍길동 (@gildong)",
      "token_id": "req_d5e0e2012679",
      "created_at": "2026-11-04T12:30:00+09:00"
    }
  ]
}