🔑 1. 인증 방식 (API Key Authentication)
모든 API 요청 시 HTTP 헤더에 발급받은 API Key를 포함하여 호출합니다. (로그인된 상태라면 아래에 본인의 API Key가 자동 표시됩니다.)
✅ 지원 인증 헤더 (둘 중 하나 사용):
•
•
🛡️ 보안 정책 (삭제 제외): 외부 API를 통해 단축링크 생성, 동영상/문서 업로드, 목록·통계 조회, 원본 URL 변경, 파일 교체, 만료 기한 연장, 휴지통 복원 등 모든 서비스를 이용할 수 있습니다. 단, 데이터 보호를 위해 삭제(DELETE) API는 외부 키 호출이 차단(403 Forbidden)되며 웹 대시보드에서만 삭제할 수 있습니다.
•
X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx•
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx🛡️ 보안 정책 (삭제 제외): 외부 API를 통해 단축링크 생성, 동영상/문서 업로드, 목록·통계 조회, 원본 URL 변경, 파일 교체, 만료 기한 연장, 휴지통 복원 등 모든 서비스를 이용할 수 있습니다. 단, 데이터 보호를 위해 삭제(DELETE) API는 외부 키 호출이 차단(403 Forbidden)되며 웹 대시보드에서만 삭제할 수 있습니다.
⚡ 2. 브라우저에서 바로 API 테스트해보기 (Live API Tester)
내 API Key를 이용해 실제 운영 서버의 POST /api/shorten 엔드포인트를 즉시 테스트할 수 있습니다.
// 버튼을 클릭하면 실제 API 응답이 여기에 표시됩니다.
📡 3. 전체 API 엔드포인트 일람 (삭제 제외 전 기능)
Base URL: https://link.prok.or.kr
| 구분 | Method | Endpoint | 요청 형식 | 기능 설명 |
|---|---|---|---|---|
| 계정/용량 | GET | /api/me |
- | API Key 인증 확인, 기관명/권한 및 동영상·문서 잔여 용량 조회 |
| 코드 중복확인 | GET | /api/check-code?code={코드} |
Query | 커스텀 단축 단어 사용 가능 여부 및 추천 대체 코드 조회 |
| URL 단축 생성 | POST | /api/shorten |
application/json |
긴 URL을 단축 링크로 변환 (original_url, custom_code, qr_details) |
| 통합 파일 업로드 | POST | /api/upload-file |
multipart/form-data |
확장자를 자동 판별하여 동영상·오디오(최대 1GB, 단 500MB 초과 시 3일 후 자동 삭제) 또는 문서(최대 500MB) 업로드 및 단축링크 생성 (file, custom_code, expiry_option, qr_details) |
| 동영상·오디오 업로드 | POST | /api/upload-video |
multipart/form-data |
동영상·오디오(최대 1GB — 500MB 이하 기본 30일 / 500MB 초과~1GB 최대 3일 보관 후 자동 삭제 · MP4/M4V/WebM/MOV/AVI/MKV 및 MP3/M4A/WAV/OGG/FLAC/AAC/WMA/OPUS) 업로드 및 스트리밍/다운로드 단축링크 생성 |
| 문서 업로드 | POST | /api/upload-document |
multipart/form-data |
문서·압축파일(최대 500MB, PDF/HWP/HWPX/DOC/DOCX/XLS/XLSX/PPT/PPTX/TXT/CSV/ZIP/RAR) 업로드 및 단축링크 생성 |
| URL 목록 조회 | GET | /api/history |
- | 생성된 단축 URL 목록 및 실시간 클릭수 조회 |
| 동영상 목록 조회 | GET | /api/video-history |
- | 업로드된 동영상 단축링크 목록, 파일 크기, 만료일, 조회수 조회 |
| 문서 목록 조회 | GET | /api/document-history |
- | 업로드된 문서 단축링크 목록, 파일 크기, 만료일, 조회수 조회 |
| 상세 통계 조회 | GET | /api/urls/{short_code}/regions |
Path | 해당 단축코드의 지역별 클릭 분포(data) 및 최근 14일 일별 클릭 추이(daily_trends) 조회 |
| 저장공간 조회 | GET | /api/video-storage/api/document-storage |
- | 기관별 할당량(기본 미디어 20GB·문서 10GB) 및 교단 전체(미디어 250GB·문서 100GB) 사용 용량 조회 |
| 서버 헬스체크 | GET | /api/health |
Public | 서비스 상태, SQLite WAL 연결 여부, 물리 디스크 가용 여유 용량(GB) 실시간 모니터링 |
| 원본 URL 변경 | PUT | /api/update-url/{short_code} |
application/json |
단축코드는 유지하고 리다이렉트될 원본 URL(original_url)만 수정 |
| 파일 교체 | PUT | /api/replace-video/{short_code}/api/replace-document/{short_code} |
multipart/form-data |
단축코드(인쇄된 QR 포함)는 그대로 유지하고 미디어(최대 1GB, 500MB 초과 시 3일 후 자동 삭제) 또는 문서(최대 500MB) 파일만 새 버전으로 교체 |
| 만료기한 변경 | PUT | /api/update-video-expiry/{short_code}/api/update-doc-expiry/{short_code} |
application/json |
동영상/문서 다운로드 만료일 변경 — 단, 500MB 초과 대용량 미디어는 연장 불가 ({"expiry_option": "30" | "7" | "3" | "YYYY-MM-DD"}) |
| QR 용도 메모 | PUT | /api/update-qr-details |
application/json |
QR 코드 상세 용도 메모 저장 ({"type": "url|video|document", "short_code": "...", "qr_details": "..."}) |
| 휴지통 조회/복원 | GET / POST | /api/trash/api/restore/{short_code} |
- | 휴지통 내역 조회 및 활성 상태로 복원 |
| AI MCP 서버 | POST / GET | /mcp |
application/json |
Model Context Protocol (JSON-RPC 2.0) 엔드포인트 — 외부 AI 에이전트 도구 호출 |
💻 4. 상세 연동 코드 예제 (MCP / cURL / Python / JavaScript)
다른 인공지능(MCP) 및 외부 프로그램에 바로 붙여넣어 사용할 수 있는 표준 예제입니다.