Skip to main content
This API authenticates with Client SDK keys (osk_ prefix). All requests require Authorization: Bearer {CLIENT_SDK_KEY} header.

​
Create Persona

POST /v1/persona
Registers a persona for AI personalization.

​
Request

The request body accepts any valid JSON object. All fields are stored as-is and provided to the model as context during persona chat. 
{
  "name": "John Doe",
  "age": 40,
  "gender": "M",
  "locale": "en",
  "store_id": "store_abc123",
  "preference": {
    "style": "casual",
    "interests": ["tech", "travel"]
  }
}
The request body has no schema restrictions. All data is stored as-is and used as model context during persona chat.

​
Response

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

​
Get Persona

GET /v1/persona/{persona_id}

​
Response

{
  "success": true,
  "data": {
    "persona_id": "d28fd898-bfa0-4444-be38-c0655f5f8307",
    "data": {
      "name": "John Doe",
      "age": 40,
      "gender": "M",
      "locale": "en",
      "store_id": "store_abc123",
      "preference": {
        "style": "casual",
        "interests": ["tech", "travel"]
      }
    }
  }
}

​
Update Persona

PUT /v1/persona/{persona_id}
The request body accepts any valid JSON object. New fields are merged into the existing data.

​
Request

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

​
Response

Returns the same format as the Get Persona response, with the new fields merged into the existing data.

​
Delete Persona

DELETE /v1/persona/{persona_id}
Performs a soft delete. The deleted persona’s information is returned in the response.

​
Response

{
  "success": true,
  "data": {
    "persona_id": "d28fd898-bfa0-4444-be38-c0655f5f8307",
    "data": {
      "name": "John Doe",
      "age": 40,
      "gender": "M",
      "locale": "en",
      "store_id": "store_abc123",
      "preference": {
        "style": "casual",
        "interests": ["tech", "travel"]
      }
    }
  }
}

​
Get Persona Status

GET /v1/persona/{persona_id}/status
Retrieves the current status of a persona. When the status is CHAT, the active thread ID is included.

​
Response

{
  "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"
  }
}

​
Status Types

StatusDescription
READYIdle (available for chat)
CHATChat in progress
SHOPPINGShopping in progress
PAYMENTPayment in progress
COMPLETECompleted

​
Code Examples

​
Swift (iOS)

// Create persona
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": "John Doe",
    "age": 40,
    "gender": "M",
    "locale": "en",
    "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

# Create
curl -X POST https://api.ones1ght.com/v1/persona \
  -H "Authorization: Bearer $SDK_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Doe", "age": 40, "locale": "en", "store_id": "store_abc123", "preference": {"style": "casual"}}'

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