이벤트 API

SDK가 백그라운드로 호출하는 주 이벤트 수집 엔드포인트. 대부분의 경우 직접 호출할 필요 없이 Python SDK, TypeScript SDK의 @junyul/node 또는 @junyul/core를 사용하면 됩니다.

공통 필드 (SDK.md §3.1)

필드타입필수설명
event_idstring필수UUIDv7 또는 evt_ 접두사 포함
timestampRFC3339필수이벤트 발생 시각 (UTC)
asset_idstring필수고객 정의 자산 식별자
event_typeenum필수35종 중 하나 (아래 목록)
legal_basesstring[]선택관련 법령 (10종 중 복수)
risk_tierenum선택low | limited | high | prohibited
subject_hashSHA-256선택사용자 ID의 해시
context_hashSHA-256선택입력 컨텍스트의 해시
outcome_hashSHA-256선택출력·결정의 해시
correlation_idstring선택연관 이벤트 그룹화 ID
trace_id / span_idstring선택OpenTelemetry 연동
tagsobject선택고객 정의 태그 (최대 16개)
metadataobject선택이벤트 타입별 추가 데이터

event_type 35종

Legacy (back-compat) — 6종

  • ai_inference, objection, human_review, disclosure_shown, disclosure_acknowledged, watermark_applied

Transparency — 4종

  • transparency.notice_shown, transparency.notice_dismissed, transparency.result_labeled, transparency.policy_disclosed

Decision — 5종

  • decision.automated_decision_made, decision.explanation_provided, decision.human_review_triggered, decision.human_review_completed, decision.decision_reversed

Objection — 4종

  • objection.received, objection.acknowledged, objection.resolved, objection.escalated

Assessment — 4종

  • assessment.impact_assessment_started, assessment.impact_assessment_completed, assessment.impact_assessment_updated, assessment.risk_classification_changed

Model & Asset — 6종

  • model.model_deployed, model.model_retired, model.performance_degraded, asset.created, asset.updated, asset.archived

Incident (EU AI Act Article 73) — 3종

  • incident.detected, incident.reported_to_authority, incident.mitigated

단일 이벤트 전송

POST https://api.junyul.com/v1/events
Authorization: Bearer JUN_live_xxx
Content-Type: application/json
Idempotency-Key: my-request-id-1

{
  "event_id": "evt_019d9d64-81f5-78af-84fb-076f29a54e90",
  "timestamp": "2026-04-18T09:23:45.123Z",
  "asset_id": "credit_scoring_v3",
  "asset_version": "v3.2.1",
  "event_type": "decision.automated_decision_made",
  "legal_bases": ["ai_basic_law_kr", "credit_info_36_2_kr", "pipa_37_2_kr"],
  "risk_tier": "high",
  "subject_hash": "sha256:...",
  "outcome_hash": "sha256:...",
  "correlation_id": "req_abc123",
  "metadata": {
    "model": "gpt-4o",
    "duration_ms": 1234,
    "tokens_in": 256,
    "tokens_out": 512
  }
}

배치 전송 (권장, 최대 1000건)

POST https://api.junyul.com/v1/events/batch
Authorization: Bearer JUN_live_xxx
Content-Type: application/json

{
  "events": [
    { ...event1... },
    { ...event2... }
  ]
}

// 202 Accepted
{
  "data": { "accepted": 2, "rejected": 0, "errors": [] },
  "request_id": "req_01KXXX"
}

Idempotency

Idempotency-Key 헤더를 보내면 서버는 해당 키를 10분간 캐시해 중복 요청을 정확히 한 번 처리합니다. SDK는 자동으로 UUIDv5 기반 idempotency key를 생성해 멱등성을 보장합니다.

에러 응답

  • 400 — schema 검증 실패 (event_type이 enum 밖 등)
  • 401 / 403 — API key 누락 또는 스코프 부족
  • 429 — 레이트 리미트 초과 (Retry-After 헤더 포함)
  • 5xx — 서버 장애 (SDK는 자동 재시도 + outbox 저장)