# 한국형 문서보안 필터 API 한국 사내 문서의 보안 등급과 유형을 분류하는 API. - **모델 ID**: `dlp` - **Base URL**: `https://api.corepin.ai` ## 1. 엔드포인트 | Method | Path | 인증 | 설명 | |---|---|:-:|---| | GET | `/v1/dlp/version` | – | 모델 버전 | | GET | `/v1/dlp/grades` | – | 6단계 등급 카탈로그 | | GET | `/v1/dlp/types` | – | 11종 유형 카탈로그 | | POST | `/v1/dlp/classify` | ✓ | 단건 등급·유형 분류 | | POST | `/v1/dlp/batch` | ✓ | 1 ~ 100 문서 일괄 분류 | | GET | `/v1/dlp/history` | ✓ | 분류 이력 (본문 미저장) | | GET | `/v1/dlp/audit` | ✓ | 감사 로그 (대시보드 설정 활성화 후 적재) | ## 2. POST `/v1/dlp/classify` **Request**: ```json { "text": "분류할 문서 텍스트 (1 ~ 32,768자)", "force_t3": false, "allow_escalate": true, "return_text": false, "apply_policy": false } ``` | 필드 | 타입 | 기본 | 설명 | |---|---|---|---| | `text` | string | (필수) | 1 ~ 32,768자 | | `force_t3` | bool | `false` | 신뢰도와 무관하게 깊은 추론기를 강제 호출. 정확도 우선일 때. | | `allow_escalate` | bool | `true` | `false`면 빠른 분류기 결과만 사용. 응답 시간 우선일 때. | | `return_text` | bool | `false` | 응답에 입력 본문 echo 여부. 운영 트래픽에서는 `false` 권장. | | `apply_policy` | bool | `false` | 조직·앱·프로젝트의 DLP 차단 정책 적용. 응답 `meta.policy_applied`/`meta.policy_decision`에 결과. | ## 3. POST `/v1/dlp/batch` ```json { "texts": ["문서1", "문서2", "..."], "force_t3": false, "allow_escalate": true, "return_text": false, "apply_policy": false } ``` - 1 ~ 100 문서. - 각 항목당 호출 1건 차감 (분당·월 한도 모두). - 응답은 `results` 배열 + 공통 `meta`. 각 항목은 단건 `classify` 응답과 같은 구조예요. - `apply_policy=true`면 정책을 한 번만 resolve 해서 항목마다 판정만 적용해요. ## 4. 응답 ```json { "grade": "TRADE_SECRET", "grade_ko": "영업비밀", "types": ["M_AND_A"], "types_ko": ["인수·합병"], "tier_used": "t2_1", "escalated": false, "confidence": 0.973, "grade_probs": {"PUBLIC": 0.001, "INTERNAL": 0.005, "…": 0.0}, "meta": { "model_id": "dlp", "model_version": "dlp-2026.05", "processing_time_ms": 12.4, "request_id": "...", "quota_remaining": 99997, "policy_applied": false } } ``` | 필드 | 타입 | 설명 | |---|---|---| | `grade` | string | 6 등급 라벨 중 하나 (`PUBLIC` ~ `CLASSIFIED`). | | `grade_ko` | string | 한글 등급명. | | `types` | string[] | 검출된 유형 라벨 (0 ~ N 개). | | `types_ko` | string[] | 한글 유형명. | | `tier_used` | string | `"t2_1"` (빠른 분류기) 또는 `"t3"` (깊은 추론기). | | `escalated` | bool | 깊은 추론기까지 갔는지. | | `confidence` | float | 최종 등급 신뢰도 [0, 1]. | | `grade_probs` | object \| null | 등급별 확률 분포 (빠른 분류기 기준). | | `t2_1_grade` | string \| null | 보강된 경우 빠른 분류기가 매겼던 원래 등급. | | `marking_grade` | string \| null | 문서에 「대외비」·「Confidential」 같은 표기가 있어 등급 하한이 걸린 경우 그 하한. | | `model_grade` | string \| null | 표기 하한이 걸리기 전 모델이 매긴 등급 (하한이 적용됐을 때만). | | `text` | string \| null | `return_text=false`면 null. | | `meta.policy_applied` | bool | 요청에 `apply_policy=true`를 보냈는지. | | `meta.policy_decision` | string \| null | `"block"` 또는 `"allow"` (`apply_policy=true`일 때만). | ## 5. 6단계 등급 아래로 갈수록 높은 등급이에요. 한글명은 응답의 `grade_ko` · `GET /v1/dlp/grades`의 `ko` 와 같은 값이에요. | 라벨 | 한글명 | 설명 | |---|---|---| | `PUBLIC` | 공개 | 공시·뉴스·홍보. 외부 공개 가능. | | `INTERNAL` | 내부 | 사내 일반 문서. 외부 공유 부적절. | | `CONFIDENTIAL` | 기밀 | 특정 부서·직급만 접근. NDA 권장. | | `RESTRICTED` | 제한 | 임원·법무·감사 등 제한 인가자만. | | `TRADE_SECRET` | 영업비밀 | 기술·노하우·고객 리스트. 누설 시 영업비밀보호법. | | `CLASSIFIED` | 특급 | 법령·규제 보호 대상. 유출 시 형사 책임. | ## 6. 11종 유형 | 라벨 | 한글명 | |---|---| | `CONTRACT` | 계약·합의 | | `FINANCIAL` | 재무·실적 | | `M_AND_A` | 인수·합병 | | `HR` | 인사·평가 | | `LEGAL` | 법무·소송 | | `RND_IP` | R&D·지식재산 | | `STRATEGY` | 전략·기획 | | `CUSTOMER` | 고객 정보 | | `SECURITY` | 보안·인증 | | `PROCUREMENT` | 구매·조달 | | `PUBLIC_CLASSIFIED` | 공시 분류물 | 한 문서에 0 ~ N 개 유형이 부착될 수 있어요. 한글명은 응답의 `types_ko` 와 같고, `GET /v1/dlp/types`에서 유형별 설명까지 받을 수 있어요. ## 7. 자동 보강 (escalation) 문서가 들어오면 빠른 분류기가 먼저 등급을 매기고, 신뢰도가 임계값 미만이면 깊은 추론기가 자동으로 한 번 더 봐요. 추가 요금은 없어요. | 조건 | 동작 | |---|---| | `confidence ≥ 0.85` (기본 임계값) | 빠른 분류기 결과 그대로. `tier_used="t2_1"` · `escalated=false` | | `confidence < 0.85` | 깊은 추론기 호출. `tier_used="t3"` · `escalated=true` · `t2_1_grade`에 원래 등급 보존 | | `force_t3=true` | 신뢰도와 무관하게 깊은 추론기 호출 | | `allow_escalate=false` | 빠른 분류기 결과 강제 사용 (응답 시간 우선) | 문서에 「대외비」·「영업비밀」·「Confidential」 같은 등급 표기가 박혀 있으면 모델 등급이 그보다 낮게 나와도 표기 수준까지 올려요. 이때 `marking_grade`(표기 하한)와 `model_grade`(올리기 전 등급)가 함께 와요. ## 8. N2SF 등급 매핑 N2SF(국가 망 보안체계)의 C·S·O 3등급에 6단계 등급이 그대로 매핑돼요. 매핑 기준은 도입 시 운영팀이 조정할 수 있어요. | N2SF 등급 | Corepin `grade` | |---|---| | O · Open (공개) | `PUBLIC` | | S · Sensitive (민감) | `INTERNAL` · `CONFIDENTIAL` · `RESTRICTED` | | C · Classified (기밀) | `TRADE_SECRET` · `CLASSIFIED` | 외부 기준과 맞출 때는 한글 등급명이 아니라 **영문 `grade` 라벨로 매핑**해주세요. 기관마다 「기밀」·「대외비」가 가리키는 수준이 달라서, 한글명끼리 맞추면 어긋나요. ## 9. GET `/v1/dlp/history` · `/v1/dlp/audit` **`/v1/dlp/history`** — 본문 미저장 분류 이력. 등급·유형·길이만 반환. 쿼리: `from_ts` / `to_ts` · `limit` (1 ~ 500) · `offset`. **`/v1/dlp/audit`** — 본문 저장 감사 로그. 대시보드에서 DLP 감사 모드를 `metadata` 또는 `full`로 켠 이후의 요청만 적재. ## 10. 단가 - 무료: 분당 60회 · 월 1,000회 (카드 등록 불필요) - 유료: **20원 / 호출** (깊은 추론기로 보강돼도 추가 요금 없음, 문서 길이 무관 단일가) - 전체 비교는 [`/pricing`](/pricing) · 청구 방식은 [`/docs/billing`](/docs/billing) ## 11. 오류 응답 공통 오류 envelope·인증·rate limit 오류는 [빠른 시작 §6](/docs/quickstart) 참고. ## 12. 코드 예제 ### Python ```python import requests, os r = requests.post( "https://api.corepin.ai/v1/dlp/classify", headers={"Authorization": f"Bearer {os.environ['COREPIN_API_KEY']}"}, json={"text": "본 인수합병은 공시 전 사내 보고용 자료입니다."}, timeout=30, ) r.raise_for_status() out = r.json() print(out["grade_ko"], "/", out["types_ko"]) # 영업비밀 / ['인수·합병'] ``` ### JavaScript ```ts const r = await fetch(`${BASE}/v1/dlp/classify`, { method: "POST", headers: { "Authorization": `Bearer ${process.env.COREPIN_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ text }), }); const { grade, grade_ko, types, types_ko } = await r.json(); ```