---
title: "Create a simulation"
method: POST
path: "/v1/simulations"
tags: ["Simulations"]
---

# Create a simulation

`POST /v1/simulations`

## Request

- Base URL: `https://api.semilattice.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.semilattice.ai/v1/simulations`
- Auth: none declared

Create a simulation from mode + goal + inputs + user_model_ids.

Returns immediately in status `planning`; the plan is generated in the
background. Poll GET /{id} until status is `planned`.

With project_id it joins round_id, or the project's latest round. Refused
with 409 while the in-app planner is mid-turn on that project.

## Headers

- `authorization` string

## Request body

- CreateSimulationBody
  - `mode` string, required: 'research' or 'journey'
  - `goal` string, required: Goal id within the mode (from /v1/simulation-schema)
  - `inputs` object: Answers keyed by the goal's input ids (from /v1/simulation-schema)
  - `user_model_ids` string[], required: One or more user-model ids to simulate against
  - `title` string, nullable
  - `project_id` string, uuid, nullable: Optional project to add this simulation to; it joins the project's latest round (round 1 is created if none exists)
  - `survey_design` SurveyDesign
    - `stimulus` string, nullable: What is being tested: a concept, a message, a price. The question writer states it in every item set question. Custom questions are used as written and do not get it added.
    - `item_sets` DesignItemSet[]: Groups of items that each get their own question on one shared scale, so the items can be compared with each other.
      - `ask` string, required: What is asked about every item in the set, e.g. 'How valuable would this feature be to you?'
      - `items` string[], required: The things being compared. Each one gets its own question.
      - `scale` string[], nullable: Answer labels every question in the set uses, ordered from least to most favourable. Leave out to let the question writer pick one scale for the whole set.
    - `custom_questions` DesignCustomQuestion[]: Individual questions asked as written.
      - `question_text` string, required: The question, asked exactly as written. Respondents see only this text, so name what it asks about: 'Would you pay £45 a week for this meal kit?', not 'Would you buy this?'.
      - `answer_options` string[], nullable: Answer options, used exactly as given. Leave out to let the question writer supply them.
  - `context_id` string, uuid, nullable: Context to plan against (from /v1/contexts). Defaults to your most recently updated context, else your organisation's. A simulation in a project plans against the project's context, so leave this out when passing project_id unless it names that same context.
  - `round_id` string, uuid, nullable: Round of project_id to put this simulation in. Defaults to the project's latest round.

## Response `201`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/semilattice/apis/semilattice-api.md) · [All operations](https://skmtc.dev/semilattice/apis/semilattice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/semilattice/apis/semilattice-api/revisions/ed277716da4f?raw)