REST API

API 레퍼런스

모든 엔드포인트는 JSON을 주고받습니다. Base URL: https://memory.wiki

요청 제한: IP당 분당 10회. 최대 문서 크기: 500KB.

POST/api/docs

새 문서를 생성합니다. 문서 ID, edit token, 생성 시각을 반환합니다.

매개변수

markdownREQUIREDstring문서의 Markdown 내용.
titlestring문서 제목. 미지정 시 첫 번째 헤딩에서 자동 추출.
isDraftboolean임시 저장 여부. 기본값: false. 임시 저장 문서는 소유자만 볼 수 있습니다.
sourcestring소스 식별자: api, web, vscode, mcp, cli.
passwordstring문서를 비밀번호로 보호합니다. 열람 시 비밀번호 입력이 필요합니다.
expiresInstring문서 만료 시간: 1h, 1d, 7d, 30d. 생략하면 영구 보존.
editModestring편집 권한: token (기본값, editToken 필요), anyone, authenticated.
folderIdstring문서를 특정 폴더에 저장합니다.

Request - curl

bash
curl -X POST https://memory.wiki/api/docs \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Hello World\nThis is my document.",
    "title": "My Document",
    "isDraft": false
  }'

Request - JavaScript

javascript
const res = await fetch("https://memory.wiki/api/docs", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    markdown: "# Hello World\nThis is my document.",
    title: "My Document",
    isDraft: false,
  }),
});
const data = await res.json();

Request - Python

python
import requests

res = requests.post("https://memory.wiki/api/docs", json={
    "markdown": "# Hello World\nThis is my document.",
    "title": "My Document",
    "isDraft": False,
})
data = res.json()

응답 200

json
{
  "id": "abc123",
  "editToken": "tok_aBcDeFgHiJkLmNoP",
  "created_at": "2026-04-15T00:00:00Z"
}
GET/api/docs/{id}

ID로 문서를 조회합니다. 임시 저장 문서는 소유자 인증이 필요합니다. 비밀번호 보호 문서는 x-document-password 헤더가 필요합니다.

헤더 (선택)

x-user-idstring소유권 확인용 사용자 UUID.
x-document-passwordstring비밀번호 보호 문서용 비밀번호.
x-user-emailstring사용자 식별용 이메일.
AuthorizationstringOAuth 인증 요청용 Bearer 토큰.

Request - curl

bash
curl https://memory.wiki/api/docs/abc123

# With password:
curl https://memory.wiki/api/docs/abc123 \
  -H "x-document-password: mysecret"

Request - JavaScript

javascript
const res = await fetch("https://memory.wiki/api/docs/abc123");
const doc = await res.json();

Request - Python

python
import requests

res = requests.get("https://memory.wiki/api/docs/abc123")
doc = res.json()

응답 200

json
{
  "id": "abc123",
  "title": "My Document",
  "markdown": "# Hello World\nThis is my document.",
  "created_at": "2026-04-15T00:00:00Z",
  "updated_at": "2026-04-15T01:00:00Z",
  "view_count": 42,
  "is_draft": false,
  "editMode": "token",
  "isOwner": true,
  "editToken": "tok_...",
  "hasPassword": false
}
PATCH/api/docs/{id}

문서를 수정합니다. edit token 또는 소유자 인증이 필요합니다. 내용 수정, 소프트 삭제, 토큰 갱신, 편집 모드 변경 등 여러 작업을 지원합니다.

매개변수

editTokenREQUIREDstring생성 시 반환된 edit token (token 모드에서 필수).
markdownstring새 Markdown 내용.
titlestring새 문서 제목.
isDraftboolean임시 저장과 게시 상태를 전환합니다.
actionstring특수 작업: soft-delete, rotate-token.
changeSummarystring변경 사항을 설명하는 버전 노트.
editModestring편집 모드 변경: token, anyone, authenticated.

Request - curl (내용 수정)

bash
curl -X PATCH https://memory.wiki/api/docs/abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "editToken": "tok_aBcDeFgH",
    "markdown": "# Updated Content",
    "changeSummary": "Fixed typos"
  }'

Request - curl (소프트 삭제)

bash
curl -X PATCH https://memory.wiki/api/docs/abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "editToken": "tok_aBcDeFgH",
    "action": "soft-delete"
  }'

Request - JavaScript

javascript
const res = await fetch("https://memory.wiki/api/docs/abc123", {
  method: "PATCH",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    editToken: "tok_aBcDeFgH",
    markdown: "# Updated Content",
  }),
});

Request - Python

python
import requests

res = requests.patch("https://memory.wiki/api/docs/abc123", json={
    "editToken": "tok_aBcDeFgH",
    "markdown": "# Updated Content",
})

응답 200

json
{
  "success": true,
  "id": "abc123",
  "updated_at": "2026-04-15T02:00:00Z"
}
HEAD/api/docs/{id}

문서의 마지막 수정 시각을 확인합니다. x-updated-at 응답 헤더를 반환합니다. 전체 내용을 다운로드하지 않고 동기화 폴링에 유용합니다.

Request - curl

bash
curl -I https://memory.wiki/api/docs/abc123

# Response headers:
# x-updated-at: 2026-04-15T01:00:00Z
# x-content-length: 1234

Request - JavaScript

javascript
const res = await fetch("https://memory.wiki/api/docs/abc123", {
  method: "HEAD",
});
const updatedAt = res.headers.get("x-updated-at");

Request - Python

python
import requests

res = requests.head("https://memory.wiki/api/docs/abc123")
updated_at = res.headers["x-updated-at"]
GET/api/user/documents

사용자가 소유한 모든 문서를 조회합니다. 헤더를 통한 사용자 식별이 필요합니다.

헤더

x-user-idREQUIREDstring사용자 UUID. 또는 x-user-email 또는 Authorization: Bearer를 사용할 수 있습니다.

Request - curl

bash
curl https://memory.wiki/api/user/documents \
  -H "x-user-id: user-uuid-here"

Request - JavaScript

javascript
const res = await fetch("https://memory.wiki/api/user/documents", {
  headers: { "x-user-id": "user-uuid-here" },
});
const { documents } = await res.json();

Request - Python

python
import requests

res = requests.get("https://memory.wiki/api/user/documents",
    headers={"x-user-id": "user-uuid-here"})
documents = res.json()["documents"]

응답 200

json
{
  "documents": [
    {
      "id": "abc123",
      "title": "My Document",
      "created_at": "2026-04-15T00:00:00Z",
      "updated_at": "2026-04-15T01:00:00Z",
      "is_draft": false,
      "view_count": 42
    }
  ]
}
POST/api/upload

이미지 파일을 업로드합니다. 공개 URL을 반환합니다. file 필드가 포함된 multipart form-data를 사용합니다.

Request - curl

bash
curl -X POST https://memory.wiki/api/upload \
  -F "file=@screenshot.png"

Request - JavaScript

javascript
const form = new FormData();
form.append("file", fileBlob, "screenshot.png");

const res = await fetch("https://memory.wiki/api/upload", {
  method: "POST",
  body: form,
});
const { url } = await res.json();

Request - Python

python
import requests

with open("screenshot.png", "rb") as f:
    res = requests.post("https://memory.wiki/api/upload",
        files={"file": f})
url = res.json()["url"]

응답 200

json
{
  "url": "https://storage.memory.wiki/uploads/screenshot.png"
}

Raw + /llms.txt

모든 공개 Memory.Wiki URL 은 AI 에이전트용 클린 마크다운 변형을 함께 제공합니다.?compact 또는 ?digest 을 붙이면 토큰을 줄일 수 있습니다 — 답변은 동일하고, 비용만 줄어듭니다.

/raw/{id}GET단일 문서의 순수 마크다운.
/raw/b/{bundleId}GET번들 다이제스트: 프론트매터 + 캔버스 분석(테마, 인사이트, 컨셉 서브그래프) + 멤버 문서의 번호 매겨진 링크 리스트.?full=1 로 모든 문서 본문을 인라인, ?graph=0 으로 분석을 제외할 수 있습니다. 아래 Bundle URL 구조 참고.
/raw/hub/{slug}GET허브 전체 마크다운. ?digest=1 은 컨셉 클러스터링된 요약을 반환합니다.
/raw/hub/{slug}/c/{concept}GET허브 내 모든 문서를 가로지르는 컨셉별 패시지 페이지.
/hub/{slug}/llms.txtGET에이전트가 먼저 가져가서 무엇이 있는지 파악할 수 있는 매니페스트.
/hub/{slug}/llms-full.txtGET허브 전체를 압축한 번들 (기본 80k 토큰, ?cap= 로 조정).

Bundle URL 구조

번들 URL (memory.wiki/b/{id}) 을 Claude, ChatGPT, Cursor 에 붙여넣으면 문서 목록 이상이 반환됩니다. 기본 응답은 캔버스의 크로스 도큐먼트 분석 — 테마, 인사이트, 갭, 핵심 takeaway, 주목할 연결, 컨셉 서브그래프 — 까지 포함하는 다이제스트입니다. 그래서 다음 AI 는 이전 AI 의 분석을 다시 만드는 대신 그대로 이어받을 수 있습니다.

벡터 임베딩은 서버에만 남습니다 (숫자 배열이라 LLM 이 쓸 수 없음). 와이어로 나가는 것은 분석이 이미 만들어둔 텍스트 결과물뿐입니다.

응답 형태

markdown
---
mw_bundle: 1
id: <bundleId>
title: "..."
url: https://memory.wiki/b/<id>
document_count: N
updated: <ISO>
analysis_generated_at: <ISO>   # 캔버스가 실행된 적이 있을 때만
analysis_stale: true           # 분석 이후 멤버 문서가 수정된 경우에만
source: "Memory.Wiki"
---

# <Bundle title>
> <description>
**Intent:** <intent>

> ⚠ _Analysis may be stale — 캔버스를 다시 실행해 새로고침하세요._   (stale 일 때만)

## Summary
<캔버스 요약>

## Themes
- ...

## Cross-document insights
- ...

## Key takeaways
- ...

## Open questions / gaps
- ...

## Notable connections
- **doc A 제목** ↔ **doc B 제목** — <relationship>

## Concepts (this bundle)
- **concept label** (from **doc title**)

## Concept relations
- **conceptA** ↔ **conceptB** — <edge label>

1. [Doc 1 title](https://memory.wiki/<docId>) — annotation
2. [Doc 2 title](https://memory.wiki/<docId>) — annotation

쿼리 파라미터

fullboolean?full=1 는 멤버 문서 본문 전체를 doc 리스트 섹션 뒤에 인라인으로 붙입니다. 생략하면(기본) 링크 리스트만 반환되고, AI 가 필요한 시점에 링크를 따라갑니다.
graphboolean?graph=0 (또는 false / off) 는 캔버스 분석 섹션을 제거하고 기존의 doc 리스트만 있는 다이제스트를 반환합니다. 분석이 무겁거나 호출자가 인벤토리만 필요할 때 사용합니다.
compactboolean?compact 는 페이로드 전체에서 중복 공백을 제거하고 긴 인용 블록을 잘라냅니다.full, graph 와 조합 가능합니다.

두 개의 온톨로지 레이어

Memory.Wiki 는 두 개의 서로 다른 온톨로지 레이어를 제공하며, 각각 별도의 URL 에 실립니다:

  • concept_index — 허브 전체. 컨셉 라벨 + 그 컨셉이 등장하는 문서들. 이미 /raw/hub/{slug} 에 포함됩니다.
  • ai_graph — 번들 스코프. 캔버스가 생성한 테마, 인사이트, 갭, 연결, 컨셉 서브그래프. 이번 릴리스부터 /raw/b/{id} 에 포함됩니다.

Stale 판정

캔버스 분석은 스냅샷입니다. 멤버 문서 중 어느 것의 updated_at 이 graph_generated_at 보다 나중이면, 응답은 프론트매터에 analysis_stale: true 를 박고 본문 맨 위에 경고 블록쿼트를 한 줄 붙여 다음 AI 가 분석을 어느 정도 가중치로 받아들일지 판단할 수 있게 합니다.

인증

Memory.Wiki는 점진적 인증 방식을 사용합니다. 기본 작업은 인증이 필요 없습니다. 고급 기능은 edit token 또는 사용자 식별 정보를 사용합니다.

인증 불필요

POST /api/docs와 GET /api/docs/{id}는 인증 없이 동작합니다. 반환된 editToken이 소유권 증명이 됩니다.

Edit token

모든 문서는 생성 시 editToken을 받습니다. PATCH 요청 시 이 토큰을 포함하여 수정하거나 삭제합니다. MCP 서버와 CLI는 토큰을 자동으로 관리합니다.

사용자 식별

사용자 범위 작업(목록 조회, 소유권 확인)에는 x-user-id 헤더, x-user-email 헤더, 또는 Authorization: Bearer JWT 토큰을 제공합니다.

MCP / CLI 인증

MCP 서버와 CLI 모두 Memory.Wiki login의 JWT를 사용합니다. 실행: npm install -g memory-wiki-cli && Memory.Wiki login

요청 제한

모든 엔드포인트는 IP당 분당 10회로 요청이 제한됩니다. 제한 초과 시 429 Too Many Requests를 반환합니다. 응답에 포함된 Retry-After 헤더로 대기 시간(초)을 확인할 수 있습니다. 최대 문서 크기는 500KB입니다.

에러

400errorBad Request. 필수 필드 누락 또는 잘못된 매개변수.
401errorUnauthorized. 유효하지 않거나 누락된 edit token / 인증 정보.
403errorForbidden. 비밀번호가 필요하거나 비밀번호가 틀림.
404errorNot Found. 문서가 존재하지 않거나 삭제됨.
410errorGone. 문서가 만료됨.
429errorToo Many Requests. 요청 제한 초과.
500errorInternal Server Error. 다시 시도하거나 지원팀에 문의해 주세요.

에러 응답 형식

json
{
  "error": "Document not found",
  "status": 404
}