メインコンテンツへスキップ
このAPIはClient SDKキー（osk_プレフィックス）で認証します。 すべてのリクエストにAuthorization: Bearer {CLIENT_SDK_KEY}ヘッダーが必要です。

​
ペルソナ登録

POST /v1/persona
AIパーソナライズ用のペルソナを登録します。

​
リクエスト

リクエストボディは任意のJSONオブジェクトを受け付けます。すべてのフィールドはそのまま保存され、ペルソナチャット時にモデルコンテキストとして提供されます。 
{
  "name": "田中太郎",
  "age": 40,
  "gender": "M",
  "locale": "ja",
  "store_id": "store_abc123",
  "preference": {
    "style": "casual",
    "interests": ["tech", "travel"]
  }
}
リクエストボディにスキーマ制限はありません。送信されたデータはそのまま保存され、ペルソナチャット時にモデルコンテキストとして活用されます。

​
レスポンス

{
  "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": "ja",
      "store_id": "store_abc123",
      "preference": {
        "style": "casual",
        "interests": ["tech", "travel"]
      }
    }
  }
}

​
ペルソナ情報更新

PUT /v1/persona/{persona_id}
リクエストボディは任意のJSONオブジェクトを受け付けます。新しいフィールドは既存データにマージされます。

​
リクエスト

{
  "locale": "ja",
  "preference": {
    "style": "formal"
  }
}

​
レスポンス

取得レスポンスと同じ形式で、新しいフィールドが既存データにマージされた結果が返されます。

​
ペルソナ削除

DELETE /v1/persona/{persona_id}
ソフトデリートされます。削除されたペルソナの情報がレスポンスとして返されます。

​
レスポンス

{
  "success": true,
  "data": {
    "persona_id": "d28fd898-bfa0-4444-be38-c0655f5f8307",
    "data": {
      "name": "田中太郎",
      "age": 40,
      "gender": "M",
      "locale": "ja",
      "store_id": "store_abc123",
      "preference": {
        "style": "casual",
        "interests": ["tech", "travel"]
      }
    }
  }
}

​
ステータス取得

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)

// ペルソナ登録
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,
    "gender": "M",
    "locale": "ja",
    "store_id": "store_abc123",
    "preference": [
        "style": "casual",
        "interests": ["tech", "travel"]
    ]
]
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, "locale": "ja", "store_id": "store_abc123", "preference": {"style": "casual"}}'

# ステータス取得
curl https://api.ones1ght.com/v1/persona/$PERSONA_ID/status \
  -H "Authorization: Bearer $SDK_KEY"