API REFERENCE

연동 문서

우리 회사 필터를 시스템에서 호출하는 방법이에요. 필터는 두 가지고, API 키 하나로 둘 다 쓸 수 있어요.

	문서 보안 필터	커스텀 정책 필터
하는 일	문서·긴 글의 보안 등급(공개~특급) 판별	대화 메시지의 정책 위반(차단/통과) 판정
엔드포인트	POST /v1/dlp/classify	POST /v1/moderation/check
언제 부르나	문서를 저장·공유·외부 AI로 보내기 전	챗봇·업무 도구가 메시지를 전송하기 전

인증 — 두 필터 공통

Authorization: Bearer sk_bsp_<발급받은 키>

키는 콘솔의 API 키에서 발급해요. 분당 300회까지 호출할 수 있어요.

제품 1 · 문서 보안 필터 API

코어핀 DLP API와 같은 스키마라 base URL과 키만 바꾸면 그대로 동작해요. 기존 연동 코드가 있다면 수정할 것이 거의 없어요.

POST /v1/dlp/classify — 문서 1건 판별

curl -X POST https://tunia.ai/v1/dlp/classify \
  -H "Authorization: Bearer sk_bsp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "판별할 문서 내용 (1~32,768자)",
    "model": "v2",            // 생략하면 기본 버전, "baseline" 이면 기본 모델
    "force_t3": false,         // 심층 추론 강제
    "allow_escalate": true,    // 확신이 낮을 때 심층 추론 자동 사용
    "return_text": false
  }'

응답

{
  "grade": "TRADE_SECRET",         // 6등급 중 하나
  "grade_ko": "영업비밀",
  "types": ["M_AND_A"],            // 0~N개 민감 유형
  "types_ko": ["인수·합병"],
  "tier_used": "t2_1",             // t1 | t2_1 | t3_baseline
  "escalated": false,
  "confidence": 0.973,
  "grade_probs": { ... },
  "marking_grade": null,           // 문서 표기("대외비" 등) 기반 하한
  "model": "acme/dlp@v2",          // 어떤 버전이 판별했는지
  "keyword_hits": [                 // 회사 키워드 감지 결과
    {"pattern": "프로젝트 아틀라스", "grade": "CONFIDENTIAL"}
  ],
  "floor_source": "keyword",       // 등급 하한의 출처: keyword | marking | null
  "n2sf": "C",                     // N2SF 등급 C|S|O (항상 포함)
  "n2sf_ko": "기밀",
  "meta": { "model_id": "dlp", "model_version": "acme/dlp@v2",
            "processing_time_ms": 14.2, "request_id": "..." }
}

POST /v1/dlp/batch — 최대 100건 일괄 판별

{ "texts": ["문서1", "문서2", ...], "model": "v2" }
→ { "results": [ {classify 응답과 동일}, ... ] }

모델이 잠들어 있을 때

비용 절약을 위해 호출이 없으면 모델이 잠들어요. 잠든 상태에서 호출하면 아래처럼 응답하니, retry_after 만큼 기다렸다 다시 호출해 주세요. 설정에서 업무 시간에 미리 깨워 둘 수도 있어요.

HTTP 202
{ "error": { "code": "model_warming",
             "message": "모델을 깨우는 중이에요. 잠시 후 다시 시도해 주세요.",
             "retry_after": 180 } }

기타 엔드포인트

GET /v1/dlp/grades	6등급 카탈로그 (인증 불필요)
GET /v1/dlp/types	11개 민감 유형 카탈로그 (인증 불필요)
GET /v1/dlp/versions	우리 회사 모델 버전 목록

등급 체계

등급	이름
공개	PUBLIC
내부	INTERNAL
기밀	CONFIDENTIAL
제한	RESTRICTED
영업비밀	TRADE_SECRET
특급	CLASSIFIED

유형: 계약·합의재무·실적인수·합병인사·평가법무·소송R&D·지식재산전략·기획고객 정보보안·인증구매·조달공시 분류물

공공기관(N2SF)

모든 판정 응답에 국가 망 보안체계(N2SF)의 n2sf 등급(C·S·O)이 포함돼요. 망 정책과 연동할 때는 이 필드만 보고 C=차단, S=제한, O=허용으로 배선하면 돼요. 설정에서 공공기관 모드를 켜면 다음 학습부터 공공 분류 기준이 라벨에 반영돼요.

N2SF	의미	대응 등급
O	공개 — 활용 우선	공개
S	민감 — 제한 접근	내부 기밀 제한
C	기밀 — 엄격 통제	영업비밀 특급

제품 2 · 커스텀 정책 필터 API

콘솔의 정책 등록에서 등록한 정책으로 메시지를 검사해요. 응답의 blocked 가 true 면 메시지 전송을 막거나 경고를 띄우는 쪽은 연동한 시스템이에요.

POST /v1/moderation/check — 메시지 검사

curl -X POST https://tunia.ai/v1/moderation/check \
  -H "Authorization: Bearer sk_bsp_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "검사할 메시지 (1~32,768자)"
    // 또는 "texts": ["메시지1", "메시지2", ...]  — 최대 100건 일괄 검사
  }'

응답

{
  "blocked": true,                 // 차단해야 하나 (걸린 정책이 하나라도 있으면 true)
  "max_score": 0.97,               // 가장 높은 일치도 (0~1)
  "hits": [                        // 켜진 정책마다 하나씩
    {"policy_id": "...",
     "title": "미공개 실적 언급 금지",
     "score": 0.97,                // 이 정책과의 일치도
     "blocked": true}              // 이 정책의 민감도 기준을 넘었나
  ],
  "policies_evaluated": 12         // 대조한 정책 수
}

// texts 로 여러 건을 보낸 경우
{ "results": [ {위와 동일}, ... ], "policies_evaluated": 12 }

연동 규칙

blocked == true	메시지를 전송하지 않거나 가리고, hits 의 정책 이름을 사용자에게 알려 주면 좋아요. (예: “미공개 실적 언급 금지 정책에 걸렸어요”)
blocked == false	그대로 전송해요.
HTTP 202	필터를 깨우는 중 — retry_after 뒤에 다시 호출해요(아래 참고).

GET /v1/moderation/policies — 켜진 정책 목록

{ "policies": [ {"id": "...", "title": "미공개 실적 언급 금지", "threshold": 0.5}, ... ] }

연동한 시스템이 “지금 어떤 정책이 적용 중인지”를 보여줄 때 써요.

요금·동작 방식

요금	호출당 ₩30 — texts 일괄 검사는 메시지 건수만큼이에요. 정책 수는 요금과 무관해요(정책 12개여도 호출 1번).
잠들어 있을 때	문서 보안 필터와 같아요 — 호출이 없으면 잠들고, 잠든 상태의 호출은 HTTP 202 model_warming 으로 응답해요. retry_after 만큼 기다렸다 다시 호출해 주세요.
정책 반영	콘솔에서 정책을 추가·수정·끄면 다음 호출부터 바로 반영돼요.

웍스AI 에서 쓰기

웍스AI 는 이미 같은 규격의 문서 필터를 연동하고 있어요. 관리자 정책에서 필터 주소를 https://tunia.ai, 키를 발급받은 sk_bsp_ 키로 바꾸면 우리 회사 전용 모델이 대신 판별해요. 응답 필드가 동일해서 코드 수정이 필요 없어요.