Skip to main content
A persona group defines the demographic and psychographic profile of a target consumer segment within a project. Once you define the group, you trigger generation to produce individual AI personas — grounded in real cultural signals from Southeast Asian markets. All persona group endpoints are nested under a project: /api/v1/projects/{project_id}/persona-groups

​
Endpoints

MethodPathAuthDescription
POST.../persona-groups/parse-promptYesConvert a natural language description into group fields
GET.../persona-groupsYesList all persona groups in a project
POST.../persona-groupsYesCreate a persona group
GET.../persona-groups/{group_id}YesGet a persona group and its generation status
PATCH.../persona-groups/{group_id}YesUpdate a persona group’s definition
DELETE.../persona-groups/{group_id}YesDelete a group and all its personas
POST.../persona-groups/{group_id}/generateYesTrigger persona generation (async, returns 202)

​
POST /persona-groups/parse-prompt

Pass a plain-language description of your target audience and get back a structured set of group fields. This is useful for building a quick “describe your audience” onboarding step before creating a group.

​
Request body

​
prompt
string
required
A natural language description of the target segment. Include demographic details like age range, location, gender, and behavioral signals for best results.

​
Response

Returns a partially or fully filled group definition object that you can review and pass directly to POST /persona-groups.
​
name
string
A suggested group name derived from the prompt.
​
age_min
number
Minimum age extracted from the prompt.
​
age_max
number
Maximum age extracted from the prompt.
​
gender
string
Gender extracted from the prompt, e.g. "Female", "Male", or "All".
​
location
string
City and country extracted from the prompt.
​
income_level
string
Inferred income bracket: "Low", "Middle", or "High".
​
occupation
string
Occupation or professional context extracted from the prompt.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups/parse-prompt \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Urban millennial women in Manila aged 25-32 who use GCash and shop on Shopee at least twice a week"
  }'

​
GET /persona-groups

List all persona groups in a project, including their current generation status.

​
Path parameters

​
project_id
string
required
UUID of the parent project.

​
Example

curl https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups \
  -H "Authorization: Bearer <access_token>"

​
POST /persona-groups

Create a new persona group. After creating a group, call /generate to produce the individual personas.

​
Path parameters

​
project_id
string
required
UUID of the parent project.

​
Request body

​
name
string
required
A label for this segment, e.g. "Metro Manila Millennials".
​
age_min
number
Minimum age of personas in the group.
​
age_max
number
Maximum age of personas in the group.
​
gender
string
Target gender. Accepts "Male", "Female", or "All".
​
location
string
City and country for the segment, e.g. "Jakarta, Indonesia". Boses uses this to ground personas in local cultural signals.
​
income_level
string
Income bracket: "Low", "Middle", or "High".
​
occupation
string
Job title or professional context, e.g. "Office worker" or "Freelancer".
​
persona_count
number
default:"5"
How many personas to generate when you call /generate. Accepts 1–10. Defaults to 5.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Metro Manila Millennials",
    "age_min": 25,
    "age_max": 35,
    "gender": "Female",
    "location": "Manila, Philippines",
    "income_level": "Middle",
    "occupation": "Office worker",
    "persona_count": 5
  }'
Creating a persona group automatically queues a background ethnography refresh for the detected market. By the time you call /generate, fresh cultural signals from Reddit, Shopee, and app store reviews are already ready to inform your personas.

​
GET /persona-groups/

Retrieve a single persona group. Use this endpoint to poll for generation status after calling /generate.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
group_id
string
required
UUID of the persona group.

​
Example

curl https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups/b2c3d4e5-0000-0000-0000-000000000010 \
  -H "Authorization: Bearer <access_token>"

​
PATCH /persona-groups/

Update the definition of an existing persona group. Only the fields you include are changed. Note that updating a group does not automatically regenerate its personas — call /generate explicitly after updating if you want fresh personas.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
group_id
string
required
UUID of the persona group.

​
Request body

All fields are optional. Include only the fields you want to change.
​
name
string
Updated group name.
​
age_min
number
Updated minimum age.
​
age_max
number
Updated maximum age.
​
gender
string
Updated gender target.
​
location
string
Updated location.
​
income_level
string
Updated income bracket.
​
occupation
string
Updated occupation.
​
persona_count
number
Updated number of personas to generate on next /generate call.

​
Example

curl -X PATCH https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups/b2c3d4e5-0000-0000-0000-000000000010 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_count": 8,
    "age_max": 40
  }'

​
DELETE /persona-groups/

Permanently delete a persona group and all the personas inside it.
Deleting a persona group removes all personas in the group. Simulation results that referenced those personas are also removed. This action cannot be undone.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
group_id
string
required
UUID of the persona group to delete.

​
Example

curl -X DELETE https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups/b2c3d4e5-0000-0000-0000-000000000010 \
  -H "Authorization: Bearer <access_token>"

​
POST /persona-groups//generate

Start persona generation for the group. This is an asynchronous operation — the endpoint returns 202 Accepted immediately and the generation runs in the background. Poll GET /persona-groups/{group_id} and check the generation_status field to track progress.
generation_statusMeaning
pendingNot yet started
generatingIn progress — check generation_progress for a human-readable status message
completeAll personas have been generated and are ready
failedGeneration failed — review your group definition and retry
Generation typically takes 20–40 seconds for a group of 5 personas. Larger groups take longer.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
group_id
string
required
UUID of the persona group to generate.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups/b2c3d4e5-0000-0000-0000-000000000010/generate \
  -H "Authorization: Bearer <access_token>"
After calling /generate, poll the group until generation_status is complete: 
curl https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/persona-groups/b2c3d4e5-0000-0000-0000-000000000010 \
  -H "Authorization: Bearer <access_token>"
Once complete, retrieve the personas at GET /persona-groups/{group_id}/personas.