KRL.KR
후원
REST API v1

KRL.KR API 문서

URL 단축, QR 생성, 파일 공유, 이메일 별칭, 서브도메인 등 모든 기능을 REST API로 사용하세요.

BASE URLhttps://krl.kr/api/v1
FORMATapplication/json

시작하기

일부 엔드포인트(URL 단축, QR 코드 등)는 인증 없이 사용할 수 있습니다. 링크 관리, 분석 등 고급 기능은 API 키가 필요합니다.

# URL 단축 — 인증 없이 사용 가능
curl -X POST https://krl.kr/api/v1/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very-long-path"}'
응답
{
  "id": "lnk_xxxxxxxxxxxx",
  "slug": "abc123",
  "short_url": "https://krl.kr/abc123",
  "original_url": "https://example.com/very-long-path",
  "qr_url": "https://krl.kr/api/qr/abc123",
  "created_at": "2026-01-01T00:00:00.000Z",
  "expires_at": null,
  "has_password": false
}

인증

API 키는 X-API-Key 헤더로 전달합니다. Authorization: Bearer도 지원합니다.

curl https://krl.kr/api/v1/links \
  -H "X-API-Key: krl_xxxxxxxxxxxxxxxxxxxx"
⚠
API 키는 서버 환경 변수에만 저장하세요. 클라이언트 코드나 Git에 노출하지 마세요.
✦
API 키가 노출된 경우 대시보드에서 즉시 폐기하고 새로 발급하세요.

요청 한도

Rate Limits
대상한도초기화
로그인 시도5회1분
회원가입5회1시간
URL 단축 (비회원)20회1분
URL 단축 (API 키)3,000회1일
일반 API 요청100회1일 (무료 플랜)

한도 초과 시 429 Too Many Requests를 반환합니다. Retry-After 헤더에서 대기 시간을 확인하세요.

URL 단축

POST/api/v1/shorten
긴 URL을 단축합니다. 익명 사용 가능 (커스텀 슬러그는 API 키 필요)

분석

GET/api/v1/links/:id/stats
인증
링크별 클릭 통계. 국가·기기·브라우저·날짜별 집계를 반환합니다.

QR 코드

GET/api/qr/:slug
슬러그의 QR 코드 이미지를 반환합니다. SVG(기본) 또는 PNG.
GET/api/v1/qr
인증
내 QR 코드 목록 조회
POST/api/v1/qr
인증
커스텀 스타일 QR 코드 생성

Pastebin

POST/api/v1/paste
텍스트 또는 코드를 단축 링크로 공유합니다. 익명 사용 가능.
GET/api/v1/paste/:slug
페이스트 내용을 가져옵니다. 비밀번호 보호 시 ?p=비밀번호 추가.
DELETE/api/v1/paste/:slug
인증
페이스트를 삭제합니다. 본인 소유만 가능.

파일 공유

POST/api/v1/files
인증
파일을 업로드하고 단축 링크를 받습니다.
GET/api/v1/files
인증
업로드한 파일 목록. ?page=1&limit=20
DELETE/api/v1/files/:slug
인증
파일을 삭제합니다. 저장소에서 영구 제거됩니다.

이메일 별칭

ℹ
이메일 별칭을 생성하면 이름@krl.kr 주소로 이메일을 받을 수 있습니다. 수신 이메일은 인박스 API로 조회합니다.
GET/api/v1/email
인증
내 이메일 별칭 목록
POST/api/v1/email
인증
새 이메일 별칭 생성
GET/api/v1/email/inbox
인증
수신된 이메일 목록 조회
DELETE/api/v1/email?id=xxx
인증
이메일 별칭 삭제

서브도메인

ℹ
서브도메인을 생성하면 이름.krl.kr이 할당됩니다. GitHub Pages, Vercel, HTML 배포, 리다이렉트, A/AAAA/CNAME 직접 DNS 레코드 등 8가지 타입을 지원합니다.
GET/api/v1/subdomains
인증
내 서브도메인 목록
POST/api/v1/subdomains
인증
새 서브도메인 생성
PATCH/api/v1/subdomains/:id
인증
서브도메인 타입·목적지·활성 상태 변경. 타입 또는 target 변경 시 Cloudflare DNS가 자동 업데이트됩니다.
DELETE/api/v1/subdomains/:id
인증
서브도메인 삭제. Cloudflare DNS 레코드도 자동 제거됩니다.
POST/api/v1/subdomains/:id/sync-dns
인증
Cloudflare DNS 레코드를 강제 재동기화합니다. DNS가 불일치할 때 사용하세요.

커뮤니티

Community
GET/api/v1/community
게시글 목록 조회. 게시판·페이지·검색어 지원.
POST/api/v1/community
인증
새 게시글 작성
GET/api/v1/community/:id
특정 게시글 상세 조회 (조회수 자동 증가)
PATCH/api/v1/community/:id
인증
게시글 수정 (작성자 또는 관리자)
DELETE/api/v1/community/:id
인증
게시글 삭제 (작성자 또는 관리자)
POST/api/v1/community/:id/like
인증
좋아요 토글 (이미 좋아요 시 취소)
GET/api/v1/community/:id/comments
댓글 목록 (오래된 순)
POST/api/v1/community/:id/comments
인증
댓글 작성
DELETE/api/v1/community/:id/comments
인증
댓글 삭제 (?comment_id=xxx). 작성자 또는 게시글 작성자 가능.

아바타

Avatar
✦
인증 없이 사용 가능합니다. 이름·ID·이메일 어떤 문자열이든 결정적(deterministic) SVG 아바타를 즉시 반환합니다.
GET/api/v1/avatar/:identifier
문자열로부터 SVG 아바타 이미지를 생성합니다.

카운트다운

Countdown
ℹ
카운트다운 페이지를 생성하면 krl.kr/countdown/슬러그 주소로 공유할 수 있습니다.
GET/api/v1/countdown
인증
내 카운트다운 목록 조회
POST/api/v1/countdown
인증
새 카운트다운 생성
GET/api/v1/countdown/:slug
카운트다운 공개 조회 (조회수 증가)
PATCH/api/v1/countdown/:slug
인증
카운트다운 수정 (소유자)
DELETE/api/v1/countdown/:slug
인증
카운트다운 삭제 (소유자)

웨이트리스트

Waitlist
ℹ
이메일 수집 + 추천인 시스템이 내장된 대기자 명단입니다. 공개 URL: krl.kr/waitlist/슬러그
GET/api/v1/waitlist
인증
내 웨이트리스트 목록 조회
POST/api/v1/waitlist
인증
새 웨이트리스트 생성
POST/api/v1/waitlist/:slug/signup
웨이트리스트에 이메일 등록 (공개, 인증 불필요)
GET/api/v1/waitlist/:slug/signup
인증
신청자 목록 조회 (소유자)
GET/api/v1/waitlist/:slug
웨이트리스트 공개 정보 조회
PATCH/api/v1/waitlist/:slug
인증
웨이트리스트 설정 수정 (소유자)
DELETE/api/v1/waitlist/:slug
인증
웨이트리스트 삭제 (소유자)

방명록

Guestbook
ℹ
방명록 페이지 URL: krl.kr/guestbook/슬러그 · embed 위젯: <script src="https://krl.kr/api/guestbook/embed.js?key=슬러그"></script>
GET/api/v1/guestbook
인증
내 방명록 목록 조회
POST/api/v1/guestbook
인증
새 방명록 생성
GET/api/v1/guestbook/:slug/entries
방명록 게시글 목록 (공개, CORS 허용)
POST/api/v1/guestbook/:slug/entries
방명록 게시글 작성 (공개, 분당 3회 제한)
DELETE/api/v1/guestbook/:slug/entries
인증
게시글 삭제 (?id=항목ID). 소유자만 가능.
GET/api/guestbook/embed.js
방명록 embed 위젯 JavaScript. ?key=슬러그 필수.

런치패드

Launchpad
ℹ
사이드 프로젝트 소개 페이지 URL: krl.kr/launchpad/슬러그 · 업데이트 내역(changelog)과 피드백 폼이 기본 포함됩니다.
GET/api/v1/launchpad
인증
내 런치패드 프로젝트 목록
POST/api/v1/launchpad
인증
새 프로젝트 생성
POST/api/v1/launchpad/:slug/changelog
인증
업데이트 내역 추가
POST/api/v1/launchpad/:slug/feedback
피드백 제출 (공개, 시간당 3회 제한)
GET/api/v1/launchpad/:slug
프로젝트 공개 정보 + changelog 조회
GET/api/v1/launchpad/:slug/changelog
업데이트 내역 목록
DELETE/api/v1/launchpad/:slug/changelog?id=xxx
인증
업데이트 내역 삭제 (소유자)
GET/api/v1/launchpad/:slug/feedback
인증
수신된 피드백 목록 (소유자)
PATCH/api/v1/launchpad/:slug
인증
프로젝트 정보 수정 (소유자)
DELETE/api/v1/launchpad/:slug
인증
프로젝트 삭제 (소유자)

공지 배너

Patch
ℹ
embed 코드 한 줄로 어떤 웹사이트에도 긴급 공지를 표시합니다. 배너가 비활성 상태면 자동으로 숨겨집니다.
GET/api/v1/patch
인증
내 배너 목록 조회
POST/api/v1/patch
인증
새 공지 배너 생성
GET/api/v1/patch/:siteKey
배너 공개 조회 (banner.js 내부에서 사용)
PATCH/api/v1/patch/:siteKey
인증
배너 내용·활성 상태 수정
DELETE/api/v1/patch/:siteKey
인증
배너 삭제
GET/api/patch/banner.js
배너 embed 스크립트. ?key=site_key 필수. CORS 허용.

스크린샷

Snapshot
✦
인증 없이 사용 가능합니다. SCREENSHOTONE_KEY 환경 변수 설정 시 고품질 스크린샷, 미설정 시 Microlink 무료 API를 폴백으로 사용합니다.
GET/api/snapshot
URL의 스크린샷을 PNG 또는 SVG 플레이스홀더로 반환합니다.

API 키 관리

GET/api/v1/keys
인증
발급된 API 키 목록 (키 해시 앞 12자만 노출)
POST/api/v1/keys
인증
새 API 키 발급. 발급 시점에만 전체 키 확인 가능.
DELETE/api/v1/keys/:id
인증
API 키 즉시 폐기. 해당 키로의 모든 요청이 차단됩니다.

AI 채팅

✦
인증 없이 사용할 수 있습니다. AI가 생성한 내용은 부정확할 수 있으니 중요한 정보는 직접 확인하세요.
POST/api/v1/ai/chat
AI와 대화합니다. 멀티턴 대화를 지원합니다.
POST/api/v1/ai/search-summary
검색 결과를 기반으로 AI 요약을 생성합니다. 검색 페이지의 'AI 요약' 기능에 사용됩니다.

오류 코드

모든 오류 응답은 아래 형식으로 반환됩니다.

{
  "error": "오류 설명 메시지",
  "code": "ERROR_CODE"    // 기계 판독 가능한 오류 코드
}
상태코드설명
400VALIDATION_ERROR요청 형식 또는 파라미터 오류
400ALTCHA_FAILED보안 인증(PoW) 실패
400INVALID_URL유효하지 않은 URL 형식
400INVALID_SLUG사용 불가 슬러그 (예약어, 특수문자 등)
401UNAUTHORIZEDAPI 키 없음 또는 만료
403FORBIDDEN해당 리소스에 대한 권한 없음
404NOT_FOUND요청한 리소스를 찾을 수 없음
409EMAIL_TAKEN이미 사용 중인 이메일 주소
409SLUG_TAKEN이미 사용 중인 슬러그
410EXPIRED만료된 링크·파일·페이스트
413FILE_TOO_LARGE파일 크기 한도 초과
429RATE_LIMITED요청 한도 초과. Retry-After 헤더 확인
503DB_UNAVAILABLE데이터베이스 연결 오류
500INTERNAL_ERROR서버 내부 오류

문의 및 지원

API 문제·버그·개선 제안은 [email protected] 또는 커뮤니티 기능 제안에 남겨주세요.