PUT /simulations/{key}

Creates a new simulation or updates an existing one. If a simulation with the specified key exists, it will be updated. Otherwise, a new simulation will be created.

Path Parameters

The unique key of the simulation to create or update.

Request

The key of the parent simulation. Only used when creating a new simulation. 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 to be used by the simulation. Systems define how to import data.

An object of named entities to be simulated.

Success

When updating an existing simulation, responds with a 200 OK.

When creating a new simulation, responds with a 201 Created.

Both responses include a simulation body.

A unique identifier.

The key of the parent simulation, if any.

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

The timestamp when the simulation was created.

The timestamp when the simulation was last updated.

Failure

Responds with a 400 Bad Request if the request body is invalid or contains validation errors, or if the parent simulation does not exist.

Example

Create a new simulation with a specific parent and seed:

PUT /simulations/my-simulation
Content-Type: application/json

{
  "parent": "default",
  "seed": 42,
  "entities": {
    "users": {
      "schema": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" }
        }
      }
    }
  }
}

Response:

{
  "key": "my-simulation",
  "parent": "default",
  "seed": 42,
  "createdAt": "2025-04-16T14:22:15.123Z",
  "updatedAt": "2025-04-16T14:22:15.123Z"
}