REST API

API 레퍼런스

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

요청 제한: 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://mdfy.app/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://mdfy.app/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://mdfy.app/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://mdfy.app/api/docs/abc123

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

Request - JavaScript

javascript

const res = await fetch("https://mdfy.app/api/docs/abc123");
const doc = await res.json();

Request - Python

python

import requests

res = requests.get("https://mdfy.app/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://mdfy.app/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://mdfy.app/api/docs/abc123 \
  -H "Content-Type: application/json" \
  -d '{
    "editToken": "tok_aBcDeFgH",
    "action": "soft-delete"
  }'

Request - JavaScript

javascript

const res = await fetch("https://mdfy.app/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://mdfy.app/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://mdfy.app/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://mdfy.app/api/docs/abc123", {
  method: "HEAD",
});
const updatedAt = res.headers.get("x-updated-at");

Request - Python

python

import requests

res = requests.head("https://mdfy.app/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://mdfy.app/api/user/documents \
  -H "x-user-id: user-uuid-here"

Request - JavaScript

javascript

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

Request - Python

python

import requests

res = requests.get("https://mdfy.app/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://mdfy.app/api/upload \
  -F "file=@screenshot.png"

Request - JavaScript

javascript

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

const res = await fetch("https://mdfy.app/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://mdfy.app/api/upload",
        files={"file": f})
url = res.json()["url"]

응답 200

json

{
  "url": "https://storage.mdfy.app/uploads/screenshot.png"
}

인증

mdfy.app는 점진적 인증 방식을 사용합니다. 기본 작업은 인증이 필요 없습니다. 고급 기능은 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 모두 mdfy login의 JWT를 사용합니다. 실행: npm install -g mdfy-cli && mdfy 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
}