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

keyrequired

The unique key of the simulation to create or update.

Request

parentoptional

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

entitiesoptional

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.

keyrequired

A unique identifier.

parentoptional

The key of the parent simulation, if any.

seedoptional

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

createdAtrequired

The timestamp when the simulation was created.

updatedAtrequired

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