Biome

GET/api/v1/biomes

List_biomes

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Conditions as filter[][]=. Conditions on different fields all apply. in (any of) and all (every one of, on fields holding several values) take a comma-separated list (\, for a literal comma). exists takes true or false. Datetimes are RFC 3339, now, or a time before now such as -30m, -6h or -7d.

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: name, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes"

{  "biomes": [    {      "biome_id": "string",      "checkpoint_interval_virtual_hours": 0.1,      "created_at": "2019-08-24T14:15:22Z",      "created_by": "string",      "integrator": {        "max_step_virtual_hours": 0.1,        "method": "rk4"      },      "metadata": null,      "name": "string",      "regions": {        "geo_index": "string",        "migration_enabled": true,        "migration_rate": 0.1      },      "time_base": {        "use_virtual_time": true,        "world_id": "string"      },      "updated_at": "2019-08-24T14:15:22Z"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

POST/api/v1/biomes

Create_biome

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

checkpoint_interval_virtual_hours?|

Virtual-hour interval at which checkpoints are advanced

Formatdouble

integrator?null|

metadata?unknown

Optional free-form metadata

name*string

Human-readable name of the biome

regions?null|

time_base?null|

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "biome_id": "string",  "checkpoint_interval_virtual_hours": 0.1,  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "integrator": {    "max_step_virtual_hours": 0.1,    "method": "rk4"  },  "metadata": null,  "name": "string",  "regions": {    "geo_index": "string",    "migration_enabled": true,    "migration_rate": 0.1  },  "time_base": {    "use_virtual_time": true,    "world_id": "string"  },  "updated_at": "2019-08-24T14:15:22Z"}

POST/api/v1/biomes/checkpoint/internal

Advance_checkpoint_internal

Request Body

application/json

Signed webhook delivery envelope carrying the checkpoint tick. Authenticated solely by the Snug-Signature HMAC header; no bearer token.

TypeScript Definitions

Use the request body type in TypeScript.

body*unknown

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes/checkpoint/internal"

{  "alerts": [    {      "above": 0,      "at_virtual": 0.1,      "band": "string",      "below": 0,      "direction": "entered",      "hook": "string",      "population_id": "string",      "size": 0.1,      "slug": "string"    }  ],  "at_virtual": 0.1,  "biome_id": "string",  "populations_advanced": 0}

GET/api/v1/biomes/{biome_id}

Get_biome

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes/string"

{  "biome_id": "string",  "checkpoint_interval_virtual_hours": 0.1,  "created_at": "2019-08-24T14:15:22Z",  "created_by": "string",  "integrator": {    "max_step_virtual_hours": 0.1,    "method": "rk4"  },  "metadata": null,  "name": "string",  "regions": {    "geo_index": "string",    "migration_enabled": true,    "migration_rate": 0.1  },  "time_base": {    "use_virtual_time": true,    "world_id": "string"  },  "updated_at": "2019-08-24T14:15:22Z"}

DELETE/api/v1/biomes/{biome_id}

Delete_biome

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/biomes/string"

{  "biome_id": "string",  "message": "string"}

POST/api/v1/biomes/{biome_id}/checkpoint

Advance_checkpoint

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

at_virtual?|

Virtual time to fold the state forward to. Defaults to the resolved "now".

Formatdouble

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes/string/checkpoint" \  -H "Content-Type: application/json" \  -d '{}'

{  "alerts": [    {      "above": 0,      "at_virtual": 0.1,      "band": "string",      "below": 0,      "direction": "entered",      "hook": "string",      "population_id": "string",      "size": 0.1,      "slug": "string"    }  ],  "at_virtual": 0.1,  "biome_id": "string",  "populations_advanced": 0}

POST/api/v1/biomes/{biome_id}/harvest

Report_harvest

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

events*array<>

One or more harvest/spawn pressure events

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes/string/harvest" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "at_virtual": 0.1,        "delta": 0.1,        "population_id": "string"      }    ]  }'

{  "accepted": 0,  "duplicates": 0}

GET/api/v1/biomes/{biome_id}/interactions

List_interactions

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Query Parameters

filter?

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: updated_at, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes/string/interactions"

{  "interactions": [    {      "biome_id": "string",      "coefficients": {        "property1": 0.1,        "property2": 0.1      },      "interaction_id": "string",      "interaction_type": "predator_prey",      "source_population": "string",      "target_population": "string"    }  ],  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  }}

POST/api/v1/biomes/{biome_id}/interactions

Add_interaction

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

coefficients?

Coupling coefficients (e.g. predation_rate, conversion_efficiency)

interaction_type*InteractionType

The coupling type

Value in

"predator_prey"
"competition"
"symbiosis"

source_population*string

Source population slug (predator for predator_prey)

target_population*string

Target population slug (prey for predator_prey)

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes/string/interactions" \  -H "Content-Type: application/json" \  -d '{    "interaction_type": "predator_prey",    "source_population": "string",    "target_population": "string"  }'

{  "biome_id": "string",  "coefficients": {    "property1": 0.1,    "property2": 0.1  },  "interaction_id": "string",  "interaction_type": "predator_prey",  "source_population": "string",  "target_population": "string"}

GET/api/v1/biomes/{biome_id}/interactions/{interaction_id}

Get_interaction

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

interaction_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes/string/interactions/string"

{  "biome_id": "string",  "coefficients": {    "property1": 0.1,    "property2": 0.1  },  "interaction_id": "string",  "interaction_type": "predator_prey",  "source_population": "string",  "target_population": "string"}

PATCH/api/v1/biomes/{biome_id}/interactions/{interaction_id}

Update_interaction

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

interaction_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

coefficients?|

Coupling coefficients (full replacement)

interaction_type?null|

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/biomes/string/interactions/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "biome_id": "string",  "coefficients": {    "property1": 0.1,    "property2": 0.1  },  "interaction_id": "string",  "interaction_type": "predator_prey",  "source_population": "string",  "target_population": "string"}

DELETE/api/v1/biomes/{biome_id}/interactions/{interaction_id}

Delete_interaction

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

interaction_id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/biomes/string/interactions/string"

{  "interaction_id": "string",  "message": "string"}

POST/api/v1/biomes/{biome_id}/interventions

Apply_intervention

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

amount?|

Amount for restock/cull interventions

Formatdouble

effective_from_virtual*number

Virtual time the intervention takes effect

Formatdouble

intervention_type*InterventionType

The intervention type

Value in

"restock"
"cull"
"parameter_change"

patch?

Parameter patch for parameter_change interventions (e.g. intrinsic.birth_rate)

population_id*string

Population slug the intervention applies to

region?|

Optional region scoping

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes/string/interventions" \  -H "Content-Type: application/json" \  -d '{    "effective_from_virtual": 0.1,    "intervention_type": "restock",    "population_id": "string"  }'

{  "effective_from_virtual": 0.1,  "intervention_id": "string",  "population_id": "string"}

GET/api/v1/biomes/{biome_id}/populations

List_populations

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Query Parameters

filter?

q?string

Full-text search over this list's searchable fields.

Length1 <= length <= 200

sort?string

Comma-separated sort keys, - for descending, at most 1. Keys: updated_at, created_at. Default: -created_at.

limit?integer

Rows per page, 1 to 100 (default 25).

Range1 <= value <= 100

cursor?string

The page.next_cursor of the previous page. Cannot be combined with page.

page?integer

A 1-based page number, for jumping. Cannot be combined with cursor.

Range1 <= value

total?boolean

Set to true to include the number of matching rows in page.total.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes/string/populations"

{  "page": {    "has_more": true,    "next_cursor": "string",    "page": 0,    "total": 0  },  "populations": [    {      "alert_bands": [        {          "above": 0,          "below": 0,          "hook": "string",          "name": "string"        }      ],      "biome_id": "string",      "birth_rate": 0.1,      "carrying_capacity": 0.1,      "checkpoint_at_virtual": 0.1,      "checkpoint_size": 0.1,      "death_rate": 0.1,      "kind": "species",      "name": "string",      "population_id": "string",      "slug": "string"    }  ]}

POST/api/v1/biomes/{biome_id}/populations

Add_population

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

alert_bands?array<>

Alert bands that fire when crossed

at_virtual?|

Virtual time of the seed checkpoint

Formatdouble

birth_rate*number

Intrinsic birth rate (per virtual hour)

Formatdouble

by_region?|

Optional per-region breakdown of the initial size

carrying_capacity*number

Carrying capacity (logistic ceiling)

Formatdouble

death_rate*number

Intrinsic death rate (per virtual hour)

Formatdouble

growth_model?null|

initial_size*number

Initial population size at the seed checkpoint

Formatdouble

kind?null|

name*string

Human-readable population name

slug*string

Stable slug used to reference this population in interactions and events

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes/string/populations" \  -H "Content-Type: application/json" \  -d '{    "birth_rate": 0.1,    "carrying_capacity": 0.1,    "death_rate": 0.1,    "initial_size": 0.1,    "name": "string",    "slug": "string"  }'

{  "alert_bands": [    {      "above": 0,      "below": 0,      "hook": "string",      "name": "string"    }  ],  "biome_id": "string",  "birth_rate": 0.1,  "carrying_capacity": 0.1,  "checkpoint_at_virtual": 0.1,  "checkpoint_size": 0.1,  "death_rate": 0.1,  "kind": "species",  "name": "string",  "population_id": "string",  "slug": "string"}

GET/api/v1/biomes/{biome_id}/populations/{population_id}

Get_population

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

population_id*string

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes/string/populations/string"

{  "alert_bands": [    {      "above": 0,      "below": 0,      "hook": "string",      "name": "string"    }  ],  "biome_id": "string",  "birth_rate": 0.1,  "carrying_capacity": 0.1,  "checkpoint_at_virtual": 0.1,  "checkpoint_size": 0.1,  "death_rate": 0.1,  "kind": "species",  "name": "string",  "population_id": "string",  "slug": "string"}

PATCH/api/v1/biomes/{biome_id}/populations/{population_id}

Update_population

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

population_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

alert_bands?array<>|

Replacement alert bands

birth_rate?|

Intrinsic birth rate (per virtual hour)

Formatdouble

carrying_capacity?|

Carrying capacity (logistic ceiling)

Formatdouble

death_rate?|

Intrinsic death rate (per virtual hour)

Formatdouble

growth_model?null|

name?|

Human-readable population name

Response Body

`application/json`

curl -X PATCH "https://example.com/api/v1/biomes/string/populations/string" \  -H "Content-Type: application/json" \  -d '{}'

{  "alert_bands": [    {      "above": 0,      "below": 0,      "hook": "string",      "name": "string"    }  ],  "biome_id": "string",  "birth_rate": 0.1,  "carrying_capacity": 0.1,  "checkpoint_at_virtual": 0.1,  "checkpoint_size": 0.1,  "death_rate": 0.1,  "kind": "species",  "name": "string",  "population_id": "string",  "slug": "string"}

DELETE/api/v1/biomes/{biome_id}/populations/{population_id}

Delete_population

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

population_id*string

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/biomes/string/populations/string"

{  "message": "string",  "population_id": "string"}

GET/api/v1/biomes/{biome_id}/projections

Get_projections

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Query Parameters

horizon_virtual_hours*number

Forward horizon in virtual hours

Formatdouble

samples?integer

Number of downsampled trajectory points to return

Formatint64

Range0 <= value

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes/string/projections?horizon_virtual_hours=0.1"

{  "equilibria": {    "property1": 0.1,    "property2": 0.1  },  "trajectory": [    {      "at_virtual": 0.1,      "sizes": {        "property1": 0.1,        "property2": 0.1      }    }  ],  "warnings": [    {      "cause": "string",      "confidence": 0.1,      "eta_virtual_hours": 0,      "pair": [        "string"      ],      "population_id": "string",      "type": "EXTINCTION_RISK"    }  ]}

GET/api/v1/biomes/{biome_id}/state

Get_state

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Query Parameters

at_virtual?number

Optional as-of virtual time; defaults to "now"

Formatdouble

region?string

Optional region scoping

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/biomes/string/state"

{  "at_virtual": 0.1,  "populations": [    {      "by_region": {        "property1": 0.1,        "property2": 0.1      },      "id": "string",      "size": 0.1,      "trend": "rising"    }  ]}

POST/api/v1/biomes/{biome_id}/subscribe

Authorization

bearer_token

AuthorizationBearer <token>

In: header

Path Parameters

biome_id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

channel?|

Optional external pubsub channel to register as a durable subscriber for this biome's threshold crossings. Future crossings are published to it.

include_websocket?boolean

Optional channel suffix for the provisioned subscription

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/biomes/string/subscribe" \  -H "Content-Type: application/json" \  -d '{}'

{  "channel": "string",  "registered": true,  "websocket_topic": "string"}

Biome

200application/json

400

201application/json

400

403

200application/json

401

200application/json

404

200application/json

403

404

200application/json

400

403

404

202application/json

400

404

200application/json

400

404

201application/json

400

403

404

200application/json

404

200application/json

400

403

404

200application/json

403

404

201application/json

400

403

404

200application/json

400

404

201application/json

400

403

404

409

200application/json

404

200application/json

400

403

404

200application/json

403

404

200application/json

400

404

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`