메인 콘텐츠로 건너뛰기
이 API는 Client SDK 키(osk_ 접두사)로 인증합니다. 모든 요청에 Authorization: Bearer {CLIENT_SDK_KEY} 헤더가 필요합니다.

​
페르소나 등록

POST /v1/persona
AI 개인화를 위한 페르소나를 등록합니다.

​
요청

자유 형식 JSON — 테넌트의 서비스에 맞는 어떤 필드든 포함할 수 있습니다. 
{
  "name": "홍길동",
  "age": 40,
  "gender": "M",
  "locale": "ko",
  "preference": "카레",
  "store_id": "S001"
}
요청 본문은 스키마 제한이 없습니다. 전달된 데이터는 그대로 저장되며, 채팅 시 모델 컨텍스트로 활용됩니다.

​
응답

{
  "success": true,
  "data": {
    "persona_id": "d28fd898-bfa0-4444-be38-c0655f5f8307"
  }
}

​
페르소나 조회

GET /v1/persona/{persona_id}

​
응답

{
  "success": true,
  "data": {
    "persona_id": "d28fd898-bfa0-4444-be38-c0655f5f8307",
    "data": {
      "name": "홍길동",
      "age": 40,
      "gender": "M",
      "locale": "ko",
      "preference": "카레",
      "store_id": "S001"
    }
  }
}

​
페르소나 수정

PUT /v1/persona/{persona_id}
전달된 필드가 기존 데이터에 머지됩니다. 최소 1개 이상의 필드를 포함해야 합니다.

​
요청

{
  "locale": "ja",
  "preference": "와인"
}

​
응답

조회 응답과 동일한 형식으로, 머지된 전체 데이터가 반환됩니다.

​
페르소나 삭제

DELETE /v1/persona/{persona_id}
소프트 삭제됩니다. 삭제된 페르소나의 정보가 응답으로 반환됩니다.

​
응답

{
  "success": true,
  "data": {
    "persona_id": "d28fd898-bfa0-4444-be38-c0655f5f8307",
    "data": {
      "name": "홍길동",
      "age": 40,
      "gender": "M",
      "locale": "ja",
      "preference": "와인",
      "store_id": "S001"
    }
  }
}

​
페르소나 상태 조회

GET /v1/persona/{persona_id}/status
페르소나의 현재 상태를 조회합니다. CHAT 상태이면 진행 중인 스레드 ID가 포함됩니다.

​
응답

{
  "success": true,
  "data": {
    "persona_id": "d28fd898-bfa0-4444-be38-c0655f5f8307",
    "status": "CHAT",
    "current_thread_id": "thr_a1b2c3d4e5f6",
    "last_active_at": "2026-04-16T10:30:00Z"
  }
}

​
상태 종류

상태설명
READY대기 중 (채팅 가능)
CHAT채팅 진행 중
SHOPPING쇼핑 중
PAYMENT결제 진행 중
COMPLETE완료

​
코드 예제

​
Swift (iOS)

// 페르소나 등록 — 자유 형식 JSON
let url = URL(string: "https://api.ones1ght.com/v1/persona")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.setValue("Bearer \(sdkKey)", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")

let body: [String: Any] = [
    "name": "홍길동",
    "age": 40,
    "locale": "ko",
    "store_id": "S001",
    "preference": "카레"
]
request.httpBody = try JSONSerialization.data(withJSONObject: body)

let (data, _) = try await URLSession.shared.data(for: request)
let result = try JSONDecoder().decode(PersonaResponse.self, from: data)
let personaId = result.data.persona_id

​
curl

# 등록 (자유 형식)
curl -X POST https://api.ones1ght.com/v1/persona \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "홍길동", "age": 40, "store_id": "S001", "preference": "카레"}'

# 수정 (기존 데이터에 머지)
curl -X PUT https://api.ones1ght.com/v1/persona/$PERSONA_ID \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preference": "와인", "vip": true}'

# 상태 조회
curl https://api.ones1ght.com/v1/persona/$PERSONA_ID/status \
  -H "Authorization: Bearer $SDK_KEY"