REST API Reference

This reference is auto-generated from the FastAPI application's OpenAPI schema. Start the server with archetype serve (default: http://localhost:8000).

Commands

Get Command History

GET /worlds/{world_id}/commands

Read audit history for a world. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Query parameters:

Parameter	Type	Default	Description
limit	integer	100

Error codes: 422

---

Submit Command

POST /worlds/{world_id}/commands

Queue a command. Required role depends on the command type.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
type	string	No	"custom"	Type
tick	integer	No	0	Tick
payload	object	No	—	Payload
priority	integer	No	0	Priority

Response (200):

Field	Type	Required	Default	Description
command_id	string	Yes	—	Command Id
type	string	Yes	—	Type
tick	integer	Yes	—	Tick
priority	integer	Yes	—	Priority

Error codes: 422

---

Submit Batch

POST /worlds/{world_id}/commands/batch

Queue commands atomically. Required roles depend on the command types.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
commands	array[SubmitCommandRequest]	Yes	—	Commands

Response (200):

Field	Type	Required	Default	Description
command_ids	array[string]	Yes	—	Command Ids

Error codes: 422

---

Entities

Create Entity

POST /worlds/{world_id}/entities

Create an entity. Requires player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
components	array[object]	No	—	Components

Response (201):

Field	Type	Required	Default	Description
entity_id	integer	Yes	—	Entity Id

Error codes: 422

---

Remove Entity

DELETE /worlds/{world_id}/entities/{entity_id}

Remove an entity. Requires player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string
entity_id	integer

Error codes: 422

---

Update Entity

PATCH /worlds/{world_id}/entities/{entity_id}

Overlay component values on an entity. Requires player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string
entity_id	integer

Request body:

Field	Type	Required	Default	Description
components	array[object]	No	—	Components

Error codes: 422

---

Remove Components

DELETE /worlds/{world_id}/entities/{entity_id}/components

Remove component types from an entity. Requires operator or admin.

Path parameters:

Parameter	Type	Description
world_id	string
entity_id	integer

Request body:

Field	Type	Required	Default	Description
component_types	array[string]	No	—	Component Types

Error codes: 422

---

Add Components

POST /worlds/{world_id}/entities/{entity_id}/components

Extend an entity with components. Requires operator or admin.

Path parameters:

Parameter	Type	Description
world_id	string
entity_id	integer

Request body:

Field	Type	Required	Default	Description
components	array[object]	No	—	Components

Error codes: 422

---

Other

Root

GET /

---

Healthz

GET /healthz

---

Query

List Signatures

GET /signatures

List persisted archetype signatures. Requires viewer, player, operator, or admin.

Query parameters:

Parameter	Type	Default	Description
storage_uri	string | null	—
namespace	string | null	—

Error codes: 422

---

Get Components

GET /worlds/{world_id}/components

Read entities containing component types. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Query parameters:

Parameter	Type	Default	Description
types	string	""	Comma-separated component type names
tick	integer | null	—
entity_ids	string | null	—

Error codes: 422

---

Get Entity

GET /worlds/{world_id}/entities/{entity_id}

Read one entity by component filter. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string
entity_id	integer

Query parameters:

Parameter	Type	Default	Description
tick	integer | null	—
components	string	""	Comma-separated component type names to project

Error codes: 422

---

Get Audit History

GET /worlds/{world_id}/history

Read audit history. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Query parameters:

Parameter	Type	Default	Description
limit	integer	100
tick_range	string | null	—	Comma-separated inclusive start,end
actor_id	string | null	—
idempotency_key	string | null	—

Error codes: 422

---

List Hooks

GET /worlds/{world_id}/hooks

List deployment-configured hooks. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Error codes: 422

---

List Processors

GET /worlds/{world_id}/processors

List deployment-configured processors. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Error codes: 422

---

List Resources

GET /worlds/{world_id}/resources

List deployment-configured resources. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Error codes: 422

---

Get World State

GET /worlds/{world_id}/state

Read world state rows by component filter. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Query parameters:

Parameter	Type	Default	Description
tick	integer | null	—
entity_ids	string | null	—
components	string | null	—

Error codes: 422

---

Simulation

Run Episode

POST /worlds/{world_id}/episode

Run one episode. Requires operator or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
episode_id	string | string	No	—	Stable identifier for this episode.
run_config	object	No	—	Configure one bounded sequence of world ticks.
max_steps	integer	No	1000	Maximum ticks before stopping.
terminal_component	any | null	No	—	Component type used for structural or value termination.
terminal_field	string | null	No	—	Boolean field tested on the terminal component.
terminal_all	boolean	No	true	Require every matching entity when testing a field.
termination	any | null	No	—	Optional callable termination predicate.

Response (200):

Field	Type	Required	Default	Description
episode_id	string | string	Yes	—	Episode identifier.
world_id	string | string	Yes	—	Forked world used by the episode.
run_id	string | string | null	No	—	Episode run identifier.
start_tick	integer	No	0	World tick at episode start.
final_tick	integer	No	0	World tick at episode completion.
terminated	boolean	No	false	Whether a termination condition stopped the episode.
duration_steps	integer	No	0	Number of ticks executed.

Error codes: 422

---

Run Rollout

POST /worlds/{world_id}/rollout

Run a rollout. Requires operator or admin; emits one rollout audit row.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
rollout_id	string | string	No	—	Stable identifier for this rollout.
episode_config	object	No	—	Configure a bounded simulation episode. An episode stops at max_steps, when termination returns true, or when its terminal component condition is satisfied. Supplying only terminal_component stops on component presence. Adding terminal_field instead tests that boolean field; terminal_all chooses whether every or any matching entity must satisfy it.
num_episodes	integer	No	1	Number of episode forks to run.
parallel	boolean	No	false	Run episode forks concurrently.
name_prefix	string	No	"ep"	Name prefix for episode worlds.
destroy_forks_on_complete	boolean	No	false	Destroy live episode worlds after collecting results.

Response (200):

Field	Type	Required	Default	Description
rollout_id	string | string	Yes	—	Rollout identifier.
base_world_id	string | string	Yes	—	World forked for each episode.
episodes	array[EpisodeResult]	No	—	Results in episode order.
num_episodes	integer	No	0	Number of completed episodes.
total_duration_steps	integer	No	0	Total ticks executed across all episodes.

Error codes: 422

---

Run World

POST /worlds/{world_id}/run

Run a bounded simulation. Requires operator or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
run_config	RunConfig | null	No	—
num_steps	integer	No	1	Num Steps
debug	boolean	No	false	Debug

Response (200):

Field	Type	Required	Default	Description
run_id	string	Yes	—	Run Id
world_id	string	Yes	—	World Id
ticks_completed	integer	Yes	—	Ticks Completed
commands_applied	integer	Yes	—	Commands Applied
final_tick	integer	Yes	—	Final Tick

Error codes: 422

---

Step World

POST /worlds/{world_id}/step

Advance one tick. Requires operator or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
run_config	RunConfig | null	No	—
num_steps	integer	No	1	Num Steps
debug	boolean	No	false	Debug

Response (200):

Field	Type	Required	Default	Description
commands_applied	integer	Yes	—	Commands Applied

Error codes: 422

---

Worlds

List Worlds

GET /worlds

List live worlds. Requires admin.

Error codes: 422

---

Create World

POST /worlds

Create a world. Requires admin.

Request body:

Field	Type	Required	Default	Description
config	WorldConfig | null	No	—
storage_config	StorageConfig | null	No	—
cache_config	CacheConfig | null	No	—
name	string | null	No	—	Name
storage_uri	string	No	"./archetype_db"	Storage Uri
namespace	string	No	"ecs"	Namespace

Response (201):

Field	Type	Required	Default	Description
world_id	string | string	Yes	—	Durable world identifier.
name	string | null	No	—	Human-readable world name.
tick	integer	No	0	Next tick to execute.
run_id	string | string | null	No	—	Identifier of the active or most recent run.

Error codes: 422

---

Destroy World

DELETE /worlds/{world_id}

Drop the in-memory world instance. Persisted storage and audit rows are retained.

Requires operator or admin. Destroying an unknown world is a no-op.

Path parameters:

Parameter	Type	Description
world_id	string

Error codes: 422

---

Get World

GET /worlds/{world_id}

Get world metadata. Requires viewer, player, operator, or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Response (200):

Field	Type	Required	Default	Description
world_id	string | string	Yes	—	Durable world identifier.
name	string | null	No	—	Human-readable world name.
tick	integer	No	0	Next tick to execute.
run_id	string | string | null	No	—	Identifier of the active or most recent run.

Error codes: 422

---

Fork World

POST /worlds/{world_id}/fork

Fork a world. Requires operator or admin.

Path parameters:

Parameter	Type	Description
world_id	string

Request body:

Field	Type	Required	Default	Description
name	string | null	No	—	Name
storage_config	StorageConfig | null	No	—
cache_config	CacheConfig | null	No	—

Response (201):

Field	Type	Required	Default	Description
world_id	string | string	Yes	—	Durable world identifier.
name	string | null	No	—	Human-readable world name.
tick	integer	No	0	Next tick to execute.
run_id	string | string | null	No	—	Identifier of the active or most recent run.

Error codes: 422

---