Skip to main content
A simulation is a research study run against a persona group. Boses supports six simulation types — concept tests, surveys, focus groups, AI-moderated interviews, manual interviews, and conjoint analyses. All simulations run as background tasks; you poll for status and fetch results when they are ready. All simulation endpoints are nested under a project: /api/v1/projects/{project_id}/simulations

​
Simulation types

simulation_typeDescription
concept_testEach persona reads your prompt and briefing, then responds with a reaction, sentiment, key themes, and a notable quote. An aggregate result summarizes the group.
surveyEach persona answers a structured questionnaire. Good for quantifiable preference and attitude data.
focus_groupPersonas interact as a group across multiple rounds. Captures emergent consensus and social dynamics.
idi_aiAI-moderated one-on-one interview. The AI moderator probes for depth using your uploaded script.
idi_manualYou drive a live conversation with a single AI persona. The session stays active until you call /end.
conjointChoice-based conjoint analysis. Personas choose between product attribute profiles, revealing which features drive preference and at what price point.

​
Simulation status values

Simulations move through the following statuses: 
pending → running → generating_report → complete
                                      → failed
                                      → aborted
active is used exclusively by idi_manual sessions while the interview is in progress.

​
Endpoints

​
Core endpoints

MethodPathDescription
GET.../simulationsList all simulations in a project
POST.../simulationsCreate and start a simulation
GET.../simulations/{simulation_id}Get simulation status and progress
POST.../simulations/{simulation_id}/abortAbort a running simulation
DELETE.../simulations/{simulation_id}Delete a simulation
GET.../simulations/{simulation_id}/resultsFetch results
GET.../simulations/convergenceCross-simulation convergence scores
POST.../simulations/{simulation_id}/reliability-checkStart a reliability study
GET.../simulations/{simulation_id}/reliability-checkGet the latest reliability study results

​
Survey-specific

MethodPathDescription
POST.../simulations/{simulation_id}/surveyUpload and parse a survey file
POST.../simulations/{simulation_id}/runConfirm parsed questions and start the survey run

​
IDI-specific

MethodPathDescription
POST.../simulations/{simulation_id}/scriptUpload an IDI script (.txt or .docx)
GET.../simulations/{simulation_id}/messagesGet the conversation transcript
POST.../simulations/{simulation_id}/messagesSend a message in a manual IDI session
POST.../simulations/{simulation_id}/endEnd a manual IDI session

​
Conjoint-specific

MethodPathDescription
POST.../simulations/{simulation_id}/conjoint-designSubmit attribute/level design and start the conjoint run

​
GET /simulations

List all simulations in a project, ordered by creation date.

​
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/simulations \
  -H "Authorization: Bearer <access_token>"

​
POST /simulations

Create and immediately start a simulation. Returns 201 Created with the new simulation object. The simulation runs in the background.

​
Path parameters

​
project_id
string
required
UUID of the parent project.

​
Request body

​
persona_group_id
string
required
UUID of the persona group to run the simulation against. The group must have a generation_status of complete.
​
simulation_type
string
required
One of concept_test, survey, focus_group, idi_ai, idi_manual, or conjoint.
​
prompt_question
string
The research question or moderator prompt. Required for concept_test and focus_group. For surveys and conjoint, this field is optional context.
​
briefing_ids
string[]
Array of briefing UUIDs to attach to the simulation. Personas will read these before responding.

​
Response

​
id
string
UUID of the new simulation.
​
simulation_type
string
The type you specified.
​
status
string
Initial status, always "pending" or "running" immediately after creation.
​
persona_group_id
string
UUID of the persona group.
​
briefing_ids
string[]
Array of attached briefing UUIDs.
​
created_at
string
ISO 8601 UTC timestamp.

​
Examples

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_group_id": "b2c3d4e5-0000-0000-0000-000000000010",
    "simulation_type": "concept_test",
    "prompt_question": "We are launching a chili-lime flavoured corn chip at PHP 35 per pack. The packaging is biodegradable. How do you feel about this product?",
    "briefing_ids": ["d4e5f6a7-0000-0000-0000-000000000030"]
  }'
Response (201 Created)
{
  "id": "e5f6a7b8-0000-0000-0000-000000000040",
  "simulation_type": "concept_test",
  "status": "running",
  "prompt_question": "We are launching a chili-lime flavoured corn chip at PHP 35 per pack...",
  "persona_group_id": "b2c3d4e5-0000-0000-0000-000000000010",
  "briefing_ids": ["d4e5f6a7-0000-0000-0000-000000000030"],
  "created_at": "2026-04-07T10:00:00"
}

​
GET /simulations/

Get the current status and progress of a simulation. Poll this endpoint after creating a simulation to track its lifecycle.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
simulation_id
string
required
UUID of the simulation.

​
Example

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

​
POST /simulations//abort

Abort a simulation that is currently in the running status. The simulation moves to aborted and any partial results are discarded.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
simulation_id
string
required
UUID of the simulation to abort.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000040/abort \
  -H "Authorization: Bearer <access_token>"

​
DELETE /simulations/

Permanently delete a simulation and all its results.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
simulation_id
string
required
UUID of the simulation.

​
Example

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

​
GET /simulations//results

Retrieve all results for a completed simulation. Returns one record per persona (individual results) plus one aggregate record summarizing the group.

​
Path parameters

​
project_id
string
required
UUID of the parent project.
​
simulation_id
string
required
UUID of the simulation.

​
Example

curl https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000040/results \
  -H "Authorization: Bearer <access_token>"

​
Survey endpoints

​
POST /simulations//survey

Upload a survey file to a simulation. The file is parsed by an LLM into a structured survey_schema. This call does not start the simulation run — call /run after reviewing the parsed questions.
​
simulation_id
string
required
UUID of the simulation.
​
file
file
required
A .txt or .docx file containing your survey questions. Supported question formats: Likert scale, multiple choice, and open-ended.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000040/survey \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@/path/to/survey.docx"

​
POST /simulations//run

Confirm the parsed survey questions and start the survey simulation. All personas will answer every question independently.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000040/run \
  -H "Authorization: Bearer <access_token>"

​
IDI endpoints

​
POST /simulations//script

Upload a discussion guide or script for an AI-moderated IDI (idi_ai). The file is processed by an LLM to extract the interview questions, and the simulation starts automatically once the script is parsed.
​
file
file
required
A .txt or .docx file containing your discussion guide. The LLM extracts question blocks and probes.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000041/script \
  -H "Authorization: Bearer <access_token>" \
  -F "file=@/path/to/idi-guide.docx"

​
GET /simulations//messages

Retrieve the full conversation transcript for an IDI simulation. Returns an ordered list of messages.

​
Example

curl https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000041/messages \
  -H "Authorization: Bearer <access_token>"

​
POST /simulations//messages

Send a message in a live idi_manual session. The persona responds in character.
​
content
string
required
The message text to send to the persona.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000042/messages \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "If this snack were only available online, would you still buy it?"
  }'

​
POST /simulations//end

End a idi_manual session. This triggers report generation and moves the simulation to generating_report, then complete.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000042/end \
  -H "Authorization: Bearer <access_token>"

​
Conjoint endpoint

​
POST /simulations//conjoint-design

Submit the attribute and level design for a conjoint simulation. This call starts the conjoint run immediately.
​
attributes
object[]
required
An array of attribute objects, each with a name and levels array.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000043/conjoint-design \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": [
      {
        "name": "Flavour",
        "levels": ["Chili-lime", "BBQ", "Plain salted"]
      },
      {
        "name": "Price",
        "levels": ["PHP 25", "PHP 35", "PHP 45"]
      },
      {
        "name": "Pack size",
        "levels": ["30g", "55g", "100g"]
      }
    ]
  }'

​
Convergence

​
GET /simulations/convergence

Retrieve cross-simulation convergence scores — a measure of how consistently personas respond across multiple simulations for the same topic. Higher scores indicate more stable, reliable findings.

​
Query parameters

​
persona_group_id
string
required
UUID of the persona group to compute convergence for.
​
briefing_id
string
Optionally scope convergence to simulations that used a specific briefing.

​
Example

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

​
Reliability check

​
POST /simulations//reliability-check

Kick off a reliability study for a completed simulation. The API runs the same simulation N times and computes a confidence score based on response consistency.

​
Example

curl -X POST https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000040/reliability-check \
  -H "Authorization: Bearer <access_token>"

​
GET /simulations//reliability-check

Retrieve the results of the latest reliability study for a simulation.

​
Example

curl https://api.temujintechnologies.com/api/v1/projects/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulations/e5f6a7b8-0000-0000-0000-000000000040/reliability-check \
  -H "Authorization: Bearer <access_token>"