POST /simulations

Creates a new simulation.

Request Body

A unique key to identify the simulation. If not provided, one will be generated.

The key of the parent simulation to inherit systems from. Defaults to default.

The seed for the simulation's random number generator. Must be an integer greater than or equal to 1.

An object of named systems for data import and formatting.

An object of named entities to be simulated.

Response

Upon success, responds with 201 Created and a simulation object:

The unique identifier for the simulation.

The key of the parent simulation, if any.

The seed for the simulation's random number generator.

ISO 8601 timestamp when the simulation was created.

ISO 8601 timestamp when the simulation was last updated.

Errors

400 Bad Request - Invalid request body or unknown parent simulation

401 Unauthorized - Authentication failure

422 Unprocessable Entity - Invalid simulation specification

Example

Request body for a simulation with a single "users" entity:

{
  "key": "my-simulation",
  "seed": 7,
  "entities": {
    "users": {
      "schema": {
        "type": "object",
        "properties": {
          "id": { "type": "id.integer" },
          "name": { "type": "person.name" }
        }
      }
    }
  }
}

Response:

{
  "key": "my-simulation",
  "seed": 7,
  "createdAt": "2025-04-16T03:15:24.362Z",
  "updatedAt": "2025-04-16T03:15:24.362Z"
}