POST /simulations

Creates a new simulation.

Request Body

keyoptional

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

parentoptional

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

seedoptional

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

systemsoptional

An object of named systems for data import and formatting.

entitiesoptional

An object of named entities to be simulated.

Response

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

keyrequired

The unique identifier for the simulation.

parentoptional

The key of the parent simulation, if any.

seedoptional

The seed for the simulation's random number generator.

createdAtrequired

ISO 8601 timestamp when the simulation was created.

updatedAtrequired

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"
}