Framework REST API Reference

Package	Value
Distribution	archetype-ecs

This domain-free reference is generated with no world libraries installed. 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	—
show	integer | null	—	Maximum matching rows to return; requires types
count	boolean	false	Return the matching row count instead of rows; requires types
where	string | null	—	One column comparison, for example score__value > 0.5; requires types

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	—	Episode Id
run_config	object	No	—	Configure one bounded sequence of world ticks.
max_steps	integer	No	1000	Max Steps
terminal_field	string | null	No	—	Terminal Field
terminal_all	boolean	No	true	Terminal All

Response (200):

Field	Type	Required	Default	Description
episode_id	string | string	Yes	—	Episode Id
world_id	string | string	Yes	—	World Id
run_id	string | string	Yes	—	Run Id
start_tick	integer	No	0	Start Tick
final_tick	integer	No	0	Final Tick
terminated	boolean	No	false	Terminated
duration_steps	integer	No	0	Duration Steps

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	—	Rollout Id
episode_config	object	No	—	Configure a bounded episode on one live world.
num_episodes	integer	No	1	Num Episodes
parallel	boolean	No	false	Parallel
name_prefix	string	No	"ep"	Name Prefix
destroy_forks_on_complete	boolean	No	false	Destroy Forks On Complete

Response (200):

Field	Type	Required	Default	Description
rollout_id	string | string	Yes	—	Rollout Id
base_world_id	string | string	Yes	—	Base World Id
episodes	array[EpisodeResult]	No	[]	Episodes
num_episodes	integer	No	0	Num Episodes
total_duration_steps	integer	No	0	Total Duration Steps

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	—	World Id
name	string | null	No	—	Name
tick	integer	No	0	Tick
run_id	string | string	Yes	—	Run Id

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; an unparsable world id is rejected as a client error.

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	—	World Id
name	string | null	No	—	Name
tick	integer	No	0	Tick
run_id	string | string	Yes	—	Run Id

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	—	World Id
name	string | null	No	—	Name
tick	integer	No	0	Tick
run_id	string | string	Yes	—	Run Id

Error codes: 422

---