🔗 PROK Link Hub — 외부 연동 API 매뉴얼

단축 링크 생성 · 동영상·오디오(최대 1GB, 500MB 초과 시 3일 후 자동 삭제) · 문서(최대 500MB) 업로드 · 통계 조회 · 파일 교체 REST API 가이드

← 대시보드로 돌아가기

🔑 1. 인증 방식 (API Key Authentication)

모든 API 요청 시 HTTP 헤더에 발급받은 API Key를 포함하여 호출합니다. (로그인된 상태라면 아래에 본인의 API Key가 자동 표시됩니다.)

내 계정 API Key (Header: X-API-Key) 로그인 후 자동 표시됩니다 (대시보드 로그인 필요)
✅ 지원 인증 헤더 (둘 중 하나 사용):
• 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) 및 외부 프로그램에 바로 붙여넣어 사용할 수 있는 표준 예제입니다.

🤖 0. 인공지능 에이전트 (Claude, Antigravity, Cursor 등) MCP 서버 연동 설정


            

① 단축 링크 생성 (POST /api/shorten)


            

② 파일 업로드 및 단축링크 생성 (POST /api/upload-file, /api/upload-document, /api/upload-video)


            

③ 기존 단축링크 파일 교체 · 원본 URL 수정 · 기한 연장 (PUT)


            

④ 목록 및 상세 클릭 통계 조회 (GET)