Skip to main content
The Persona Library is a collection of reusable personas that have been promoted from individual projects and made available across all projects in your company. Personas enter the library based on their reliability score — a measure of response consistency across simulations. Those that produce coherent, non-contradictory responses are promoted automatically. Using library personas is useful for:
  • Longitudinal studies — running the same individuals across multiple campaigns over time to track attitude shifts
  • Cross-project consistency — ensuring the same consumer segment is represented identically in different research initiatives
  • Faster setup — skipping generation by pulling proven personas directly into a new project
When you generate a new persona group, Boses automatically checks the library for matching personas before creating new ones, so well-tested individuals are reused wherever possible.

​
Endpoints

MethodPathAuthDescription
GET/api/v1/library/personasYesSearch and list library personas with optional filters
GET/api/v1/library/personas/{id}YesGet a single library persona
GET/api/v1/library/personas/{id}/projectsYesFind all projects that have used this persona
POST/api/v1/library/personas/{id}/retireYesRetire a library persona so it is no longer used in new simulations

​
GET /library/personas

Search the persona library with optional filters. Returns a paginated list of library personas matching your criteria.

​
Query parameters

​
location
string
Filter by city or country, e.g. "Manila, Philippines" or "Jakarta, Indonesia". Partial matches are supported.
​
gender
string
Filter by gender: "Male", "Female", or "All".
​
income_level
string
Filter by income bracket: "Low", "Middle", or "High".
​
age_min
number
Minimum age filter (inclusive).
​
age_max
number
Maximum age filter (inclusive).
​
occupation
string
Filter by occupation keyword, e.g. "marketing" or "freelancer".
​
limit
number
default:"20"
Maximum number of results to return per page. Maximum value is 100.
​
offset
number
default:"0"
Number of results to skip. Use with limit for pagination.

​
Response

​
personas
object[]
Array of library persona objects.
​
total
number
Total number of library personas matching the filters.
​
limit
number
The limit value used for this response.
​
offset
number
The offset value used for this response.

​
Example

curl "https://api.temujintechnologies.com/api/v1/library/personas?location=Philippines&limit=20&offset=0" \
  -H "Authorization: Bearer <access_token>"
Response
{
  "personas": [
    {
      "id": "lib-a1b2c3d4-0000-0000-0000-000000000001",
      "full_name": "Maria Santos",
      "age": 28,
      "gender": "Female",
      "location": "Quezon City, Philippines",
      "occupation": "Marketing coordinator",
      "income_level": "Middle",
      "avatar_url": "https://api.temujintechnologies.com/avatars/lib-a1b2c3d4.png",
      "times_used": 7,
      "last_used_at": "2026-03-15T10:00:00",
      "retired": false
    },
    {
      "id": "lib-b2c3d4e5-0000-0000-0000-000000000002",
      "full_name": "Ana Reyes",
      "age": 31,
      "gender": "Female",
      "location": "Makati, Philippines",
      "occupation": "Brand manager",
      "income_level": "Middle",
      "avatar_url": "https://api.temujintechnologies.com/avatars/lib-b2c3d4e5.png",
      "times_used": 4,
      "last_used_at": "2026-02-28T14:30:00",
      "retired": false
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

​
GET /library/personas/

Retrieve the full profile of a single library persona, including all demographic and psychographic fields.

​
Path parameters

​
id
string
required
UUID of the library persona.

​
Example

curl https://api.temujintechnologies.com/api/v1/library/personas/lib-a1b2c3d4-0000-0000-0000-000000000001 \
  -H "Authorization: Bearer <access_token>"

​
GET /library/personas//projects

Find all projects across your company that have used this library persona. Useful for understanding the longitudinal history of a persona and tracing results across campaigns.

​
Path parameters

​
id
string
required
UUID of the library persona.

​
Example

curl https://api.temujintechnologies.com/api/v1/library/personas/lib-a1b2c3d4-0000-0000-0000-000000000001/projects \
  -H "Authorization: Bearer <access_token>"

​
POST /library/personas//retire

Mark a library persona as retired. Retired personas are excluded from automatic matching during new persona group generation and cannot be added to new simulations. Existing simulation results that reference a retired persona are not affected.
Retiring a persona is useful when a persona has become stale — for example, if its profile reflects consumer attitudes that are no longer current. Retiring does not delete the persona; you can view it and its history but it will not appear in new projects.

​
Path parameters

​
id
string
required
UUID of the library persona to retire.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/library/personas/lib-a1b2c3d4-0000-0000-0000-000000000001/retire \
  -H "Authorization: Bearer <access_token>"

​
How personas enter the library

Boses evaluates personas for library promotion based on their reliability score — measured by running consistency checks across multiple simulations. Personas that give coherent, non-contradictory responses are promoted automatically. You can also trigger a manual reliability check via the Simulations API. Once in the library, a persona retains its full profile and is available when generating new persona groups. If a new group’s demographic definition closely matches a library persona, Boses reuses that persona instead of generating a new one, ensuring you build up a consistent panel over time.
Library personas are automatically matched and reused during generation. You do not need to explicitly select them — Boses handles this in the background. You can confirm which library personas were used by checking the library_persona_id field on each persona after generation completes.