표절 검사 API REST 및 SDK 지원
표절 및 AI 감지를 위한 REST 엔드포인트. OpenAPI 3.0 명세, Python 및 Node SDK, Apache 2.0 참고 구현. 처음 curl부터 웹훅 기반 대량 처리까지 — noplag.com에서 구동 중인 동일 엔진 사용.
REST · OpenAPI 3.0Python 및 Node SDKApache 2.0 참고 구현
첫 호출
curl 한 줄로 유사도 점수 얻기.
POST로 텍스트 제출, 유사도 구간 반환. SDK 불필요, 컴파일 필요 없음, 독점적 wire format 없음.
요청 · bash복사
$ curl https://engine.noplag.app/v1/checks \ -H "Authorization: Bearer $NOPLAG_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{ "text": "The rain in Spain falls...", "corpora": ["web", "academic"], "ai_detection": true, "webhook_url": "https://you.example/hook" }'응답 · 200 OK · application/json복사
{ "check_id": "chk_01HX9R2Y4...", "status": "complete", "similarity_pct": 23.4, "ai_score": 0.08, "engine_commit": "v0.4.2", "sources": [ { "url": "https://en.wikipedia...", "matched_chars": 142, "similarity_pct": 100.0 } ]}엔드포인트
4개 엔드포인트. 하나의 약속. URL 버전 관리.
동일한 OpenAPI 3.0 명세가 오픈 소스 저장소와 engine.noplag.app에 존재합니다. SDK는 태그된 릴리스마다 이 명세로부터 재생성됩니다.
POST/v1/checks표절 검사 제출최대 8초까지 동기 처리; 초과시 웹훅 콜백. Idempotency-Key 필수.
GET/v1/checks/{id}검사 결과 조회가장 최신 보고서 상태 반환. Accept: text/event-stream으로 구간 스트림 사용 가능.
GET/v1/sources/{id}소스 세부 정보ID로 매칭된 소스 확인 — 전체 URL, 스냅샷 일자, 캐시/실시간 구분.
POST/v1/folders폴더 관리검사 생성 / 조회 / 이동. 폴더 단위로 사본문서 매칭 범위 지정.
POST/v1/webhooks웹훅 등록HMAC 서명 전달; 24시간 동안 지수적 재시도; 대시보드에서 재전송 가능.
전체 참조는 api./docs에서 확인할 수 있습니다.openapi.yaml
AUTH 및 RATE LIMIT
Bearer 토큰. Idempotency-Key. 정직한 Rate-Limit 헤더.
특별한 점 없음. 표준 HTTP 관례 사용 — 이미 운영 중인 retry 미들웨어 그대로 적용 가능.
인증
Bearer 토큰. 헤더 하나로 간단 처리.
1.
키 생성대시보드 → 설정 → API. 키 범위(읽기 / 쓰기 / 관리자)별 지정, 두 번 클릭으로 회전 가능.
2.
모든 호출에 키 전달Authorization: Bearer nplg_live_…. 테스트 키(nplg_test_)는 제출 내용이 저장되지 않는 테스트 샌드박스에 전송됩니다.
3.
POST 호출 시 Idempotency-Key 추가아무 UUID나 사용 가능. 동일 키 + 본문 조합은 24시간 동안 캐시된 응답 반환 — 이중과금, 중복 점검 없이 재시도 가능.
Authorization: Bearer nplg_live_a82f...Idempotency-Key: 0e8f9c44-...요율 제한
키별, 분당. 헤더로 현재 상황 명확 표기.
요금제분당 요청월간버스트
무료10100 / 월20
Pro601,000 / 월120
Premium30010,000 / 월600
Enterprise맞춤협상맞춤
X-RateLimit-Limit: 60X-RateLimit-Remaining: 41X-RateLimit-Reset: 1747920480Retry-After: 19 (only on 429)SDK
2종 SDK. 동일 OpenAPI 3.0 명세에서 생성.
Python, Node는 모든 엔진 태그 릴리즈마다 배포. 기타 언어(Go, Ruby, Java)는 openapi.yaml에서 생성 — 커뮤니티 PR 환영.
PYTHONpip install noplag
from noplag import Noplagclient = Noplag(api_key="nplg_live_…")report = client.checks.create( text="...", corpora=["web", "academic"], ai_detection=True,)print(report.similarity_pct)NODEnpm i @noplag/sdk
import Noplag from "@noplag/sdk";const client = new Noplag({ apiKey: process.env.NOPLAG_KEY,});const report = await client.checks.create({ text: "...", corpora: ["web", "academic"], aiDetection: true,});<200msp95 지연시간
99.95%업타임 SLA
3지역 (US/EU/AP)
OAPI 3명세 형식
Apache 2.0참고 구현
웹훅
장시간 검사 콜백. 반복 재시도 포함.
01
이벤트 4종. JSON 본문. HMAC-SHA256 서명 헤더.
check.completed보고서 완성 · 전체 보고서 JSON 포함
check.failed영구 오류 · 오류코드 + 재시도 조언 포함
check.progress중간 진행 정보 · 현재까지 매칭된 소스 목록
folder.shared폴더 접근 권한이 팀원 또는 외부 감사자에게 부여됨
02
24시간 지수 재시도. 대시보드에서 재전송 가능.
재시도 곡선5초, 30초, 2분, 10분, 1시간, 6시간, 24시간 — 이후 dead-letter
타임아웃연결 10초, 시도당 총 30초
성공 조건HTTP 2xx 내 응답 — 리디렉션 따라감
재전송 UI대시보드에서 전송 기록 선택, 다른 URL로 재발송
03
서명 확인. 일치하지 않으면 거부.
모든 전송에 X-Noplag-Signature: t=<unix>,v1=<hex> 포함. 타임스탬프 + 본문에 대해 웹훅 시크릿으로 HMAC-SHA256 계산, 상수 시간 비교.
h = hmac.new(secret, f"{t}.{body}".encode(), hashlib.sha256).hexdigest()assert hmac.compare_digest(h, v1)개발 원칙
HTTP를 따릅니다. API 설계서의 전부입니다.
POST는 idem. URL에 버전 포함. 오류 시 다음 조치 안내. rate-limit 창 위치를 헤더에 명확 표시. 오프셋 대신 커서 기반 페이징. 타임스탬프는 UTC ISO 8601. HATEOAS 커스텀 사용 안 함, 오류 시 200 OK 반환 없음, 서버 간 호출에 OAuth 요구하지 않음. API 설계 문서는 RFC 9110, OpenAPI 3.0 명세 — 별도의 “Noplag 방식” 학습 불필요.
설계 참고 읽기설계 제약
IDEMP동일 Idempotency-Key + 본문이면 24시간 내 캐시 응답 반환. 네트워크 장애 시 동일 키로 재시도 — 이중 과금, 중복 점검 없음.
VER주버전은 URL 경로에 표시(/v1, /v2). 하위 호환 안 되는 변경은 별도 버전 경로로 — 기존 버전은 공지 후 12개월 지원.
ERR모든 4xx/5xx 오류는 RFC 9457 problem-details JSON(type, title, detail, instance, noplag.retry_strategy 포함)
PAG모든 목록 엔드포인트는 커서 기반. ?limit=100&cursor=… 사용, 응답은 next_cursor 반환. 중간에 새 행 추가돼도 오프셋 혼돈 없음.
OBS응답에 X-Engine-Commit, X-Request-Id, 단계별 Server-Timing 포함. 검사 ID로 언제든 재실행, 보고서는 사용한 엔진 릴리즈 링크 포함.
OPENgithub.com/NoplagLabs/noplag-engine에서 Apache 2.0 기준 구현을 제공합니다. 데이터가 네트워크를 벗어날 수 없다면 직접 self-host하여 호출할 수 있습니다. API 인터페이스는 동일합니다.
FAQ
실제 통합 엔지니어들이 묻는 질문.
- 일반 문서 검사시 호출 지연은 어느 정도인가요?
- 색인된 코퍼스 기준 500단어 검사 시 p50 약 600ms, p95 약 1.8초입니다. Layer W(실시간 웹 검증) 활성화 시 약 2초가 추가됩니다. 이 과정은 Google과 Brave를 통해 왕복 요청이 발생합니다. 긴 문서(예상 처리 시간 8초 초과)는 즉시 check_id를 반환하고, 웹훅으로 결과를 전달합니다.
- API로 과금이 측정되는 방식은?
- /v1/checks 1건 제출당 1회 청구, 문서 길이는 요금제별 상한(프로 1,500단어, 프리미엄 50,000, 엔터프라이즈 맞춤). Idempotency-Key + 본문 동일 재시도(24시간 이내)는 중복 청구 없음. /v1/checks/{id} 및 SDK 보조 호출은 무료.
- 셀프호스팅 가능한가요?
- 네, github.com/NoplagLabs/noplag-engine은 engine.noplag.app에서 사용하는 것과 동일한 Apache 2.0 기준 구현체입니다. docker compose up 명령으로 로컬 /v1/checks 엔드포인트를 바로 사용할 수 있습니다. 클라우드 버전은 관리되는 코퍼스와 Google/Brave API 키를 추가로 제공합니다. 완전한 셀프호스팅을 원할 경우 직접 API 키를 준비해야 합니다.
- 신뢰할만한 rate-limit 재시도 헤더가 있나요?
- 429 발생시 Retry-After(초 단위) 반환. X-RateLimit-* 헤더는 모든 응답에 포함 — 429 기다릴 필요 없이 X-RateLimit-Remaining 값으로 자체 pre-throttle 가능. 둘 다 배포 간 안정, 정확성 보장.
- SDK 릴리즈 주기는 어떻게 되나요?
- Python, Node SDK는 openapi.yaml에서 엔진 태그마다 자동 생성. 엔진 주요 릴리즈(v0.x → v0.y)는 SDK도 당일 배포. 패치 수정은 1주 이내 제공. 두 SDK 모두 semver 따름; API 표면은 /v1 → /v2에서만 깨짐.
- 코퍼스가 월중 변경되면 어떻게 되나요?
- 모든 검사는 X-Engine-Commit 및 코퍼스 스냅샷 타임스탬프 각인. 예전 검사 재실행은 쿼리 파라미터 한 줄(?corpus_snapshot=…). 최초 보고서는 원본 스냅샷으로 보존 — 과거 보고서 유사도 점수는 조용히 변경되지 않음.
- 월간 할당량 소모 없이 테스트하려면?
- 테스트 키(nplg_test_…)로 샌드박스 사용 — 전체 API 표면 제공, 제출 영구 저장 없음, 할당량/요율 제한에 영향 없음. 샌드박스에서 웹훅도 정상 호출, 통합 테스트 무료.
- 대량 검사의 권장 방식은?
- 요율 제한 내에서 병렬 제출 — 설계상 batch 엔드포인트 없음(500개 일괄 처리시 312번째 오류 발생보다 500개 개별 호출이 낫다고 판단). 파이프라인 대량처리는 API+웹훅 조합 권장: 제출시 즉시 check_id 반환받고, 이후 200건 추가 제출, 결과는 도착즉시 처리.
- 내 폴더만 검사 범위로 지정 가능합니까?
- 가능 — 요청 본문에 corpora: []와 folder_id 지정시 사용자-개인 폴더만 매칭. corpora: ["academic"]과 조합시 “학술+내 폴더만” 검사 가능. 호출별 지정, 별도 요금제 불필요.
- EU 거주 및 온프레미스가 필요한 경우 변경점은?
- 엔터프라이즈 요금제에서 EU-거주별 전용 엔드포인트(api.eu.noplag.com) 제공 — OpenAPI 표면 동일, 개인정보 EEA 내 유지. 참고 구현을 자체 VPC에 완전 셀프호스팅 가능 — 동일 엔진, 동일 /v1, 데이터 외부 전송 없음. (open-core 전환 중, SOC 2 등 공식 인증은 미완료 상태 — 그 전까지는 감사 가능한 엔진을 제공합니다.)
API 키 발급, 첫 호출 시도.
프리 트라이얼, 100회 무료 호출 포함. 프로 요금제 월 $23/1,000회. 호출을 네트워크 내부에만 유지하고 싶다면 Apache 2.0 참고 구현 활용.