> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chronicle-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Worlds
> Compile a blueprint, launch a world, and get the twins and tasks it created.
A **world** is a simulated system of connected services and records. A
**blueprint** describes its starting state and tasks. This walkthrough models a
company's invoice triage workflow. **Compile** checks the blueprint.
**Launch** starts the twins, saves a world version, and creates the task suite.
Every launch is a new version with new twins.
Use a [configured SDK client](/api-reference/languages/overview#use-the-guide-examples).
The examples share that client and the IDs returned by earlier steps.
## Methods
| Method | HTTP | Does |
| ------------------------------------------------ | ------------------------------------- | --------------------------------------------- |
| `worlds.examples.list()` | `GET /v1/worldsmith/examples` | List built-in example blueprints. |
| `worlds.compile(blueprint)` | `POST /v1/worldsmith/compile` | Validate a blueprint without launching. |
| `worlds.create(blueprint, idempotency_key, ...)` | `POST /v1/worldsmith/worlds` | Launch a world, or a new version of one. |
| `worlds.list()` | `GET /v1/worldsmith/worlds` | List saved worlds. |
| `worlds.retrieve(world_id)` | `GET /v1/worldsmith/worlds/{worldId}` | Read a world: status, twins, tasks. |
| `worlds.wait(world_id)` | polls the above | Block until the world is `ready` or `failed`. |
| `worlds.versions.list(world_id)` | `GET .../versions` | List a world's versions, newest first. |
| `worlds.materialize(world_id)` | `POST .../materialize` | Retry task setup. |
| `worlds.activity.list(world_id)` | `GET .../activity` | Requests across the world's twins. |
| `worlds.lifecycle.list(world_id)` | `GET .../lifecycle` | Start, stop, and reset events. |
Full request and response schemas are under **Worldsmith endpoints** in the
sidebar.
## Launch a world
Export one from the dashboard, write one in the [blueprint format](#blueprint),
or load the built-in example identified by the `triage-duplicate-invoice` task key:
```python Python theme={null}
example = next((e for e in client.worlds.examples.list().items
if any(t.key == "triage-duplicate-invoice"
for t in e.blueprint.scenario.tasks)), None)
if example is None:
raise RuntimeError("The duplicate-invoice example is not available")
blueprint = example.blueprint
```
```typescript TypeScript theme={null}
const example = (await client.worlds.examples.list()).items.find((e) =>
(e.blueprint.scenario.tasks ?? []).some((t) => t.key === "triage-duplicate-invoice"));
if (!example) throw new Error("The duplicate-invoice example is not available");
const blueprint = example.blueprint;
```
```javascript JavaScript theme={null}
const example = (await client.worlds.examples.list()).items.find((e) =>
(e.blueprint.scenario.tasks ?? []).some((t) => t.key === "triage-duplicate-invoice"));
if (!example) throw new Error("The duplicate-invoice example is not available");
const blueprint = example.blueprint;
```
```go Go theme={null}
examples, err := client.Worlds.Examples.List(ctx)
if err != nil { return err }
var blueprint chronicle.WorldBlueprint
found := false
for _, example := range examples.Items {
for _, task := range example.Blueprint.Scenario.Tasks {
if task.Key == "triage-duplicate-invoice" {
blueprint, found = example.Blueprint, true
break
}
}
if found { break }
}
if !found { return fmt.Errorf("the duplicate-invoice example is not available") }
```
```rust Rust theme={null}
let example = client.worlds().examples().list().await?.items.into_iter()
.find(|e| e.blueprint.scenario.tasks.iter().any(|t| t.key == "triage-duplicate-invoice"))
.ok_or("The duplicate-invoice example is not available")?;
let blueprint = example.blueprint;
```
Compiling is fast and creates nothing. It returns `problems` (must be empty
to launch), `warnings`, and a preview of each twin's seed and each task.
```python Python theme={null}
preview = client.worlds.compile(blueprint=blueprint)
if preview.problems:
raise SystemExit(preview.problems)
print(preview.warnings)
```
```typescript TypeScript theme={null}
const preview = await client.worlds.compile({ blueprint });
if (preview.problems.length) throw new Error(preview.problems.join("\n"));
console.log(preview.warnings);
```
```javascript JavaScript theme={null}
const preview = await client.worlds.compile({ blueprint });
if (preview.problems.length) throw new Error(preview.problems.join("\n"));
console.log(preview.warnings);
```
```go Go theme={null}
preview, err := client.Worlds.Compile(ctx, chronicle.WorldCompileParams{Blueprint: blueprint})
if err != nil {
return err
}
if len(preview.Problems) > 0 {
return fmt.Errorf("blueprint problems: %v", preview.Problems)
}
fmt.Println(preview.Warnings)
```
```rust Rust theme={null}
let preview = client.worlds().compile(WorldCompileParams { blueprint: blueprint.clone() }).await?;
if !preview.problems.is_empty() {
return Err(format!("blueprint problems: {:?}", preview.problems).into());
}
println!("{:?}", preview.warnings);
```
An invalid blueprint is not an error; the problems come back in the result.
Pass an idempotency key so a retry returns the same world instead of
launching a second one. `ttl_hours` is how long the twins live (default 72,
max 720).
```python Python theme={null}
world = client.worlds.create(
blueprint=blueprint,
idempotency_key="launch-1",
ttl_hours=24,
)
world_id = world.world.id
```
```typescript TypeScript theme={null}
let world = await client.worlds.create({
blueprint,
idempotencyKey: "launch-1",
ttlHours: 24,
});
const worldId = world.world.id;
```
```javascript JavaScript theme={null}
let world = await client.worlds.create({
blueprint,
idempotencyKey: "launch-1",
ttlHours: 24,
});
const worldId = world.world.id;
```
```go Go theme={null}
world, err := client.Worlds.Create(ctx, chronicle.WorldCreateParams{
Blueprint: blueprint,
IdempotencyKey: "launch-1",
TTLHours: 24,
})
if err != nil {
return err
}
worldID := world.World.ID
```
```rust Rust theme={null}
let world = client.worlds().create(WorldCreateParams {
blueprint: blueprint.clone(),
idempotency_key: "launch-1".into(),
ttl_hours: Some(24),
..Default::default()
}).await?;
let world_id = world.world.id.clone();
```
A retry with the same key returns the existing world. The same key with a
different blueprint is a `409`.
Launching takes a minute or two. `wait` polls until the world is `ready` or
`failed`.
```python Python theme={null}
world = client.worlds.wait(world_id, timeout=180)
if world.status != "ready":
raise RuntimeError(f"World {world_id}: {world.status}; {world.launch_error}")
for twin in world.twins:
print(twin.id, twin.service, twin.status) # keep tokens in memory
if world.evaluation is not None:
print(world.evaluation.status, world.evaluation.task_suite_id)
```
```typescript TypeScript theme={null}
world = await client.worlds.wait(worldId, { timeout: 180_000 });
if (world.status !== "ready") throw new Error(`World ${worldId}: ${world.status}; ${world.launchError}`);
for (const twin of world.twins) console.log(twin.id, twin.service, twin.status);
if (world.evaluation) console.log(world.evaluation.status, world.evaluation.taskSuiteId);
```
```javascript JavaScript theme={null}
world = await client.worlds.wait(worldId, { timeout: 180_000 });
if (world.status !== "ready") throw new Error(`World ${worldId}: ${world.status}; ${world.launchError}`);
for (const twin of world.twins) console.log(twin.id, twin.service, twin.status);
if (world.evaluation) console.log(world.evaluation.status, world.evaluation.taskSuiteId);
```
```go Go theme={null}
waitCtx, cancel := context.WithTimeout(ctx, 3*time.Minute)
defer cancel()
world, err = client.Worlds.Wait(waitCtx, worldID)
if err != nil { return err }
if world.Status != "ready" {
return fmt.Errorf("world %s: %s; %v", worldID, world.Status, world.LaunchError)
}
for _, twin := range world.Twins { fmt.Println(twin.ID, twin.Service, twin.Status) }
if world.Evaluation != nil { fmt.Println(world.Evaluation.Status, world.Evaluation.TaskSuiteID) }
```
```rust Rust theme={null}
let world = client.worlds().wait(&world_id, Duration::from_secs(180)).await?;
if world.status != "ready" {
return Err(format!("world {}: {:?}; {:?}", world_id, world.status, world.launch_error).into());
}
for twin in &world.twins { println!("{} {} {}", twin.id, twin.service, twin.status); }
if let Some(evaluation) = &world.evaluation {
println!("{} {}", evaluation.status, evaluation.task_suite_id);
}
```
When `status` is `ready`, each twin's `base_url` and `token` are live. Point
your agent at them (see [Twins](/api-reference/twins)), or run the world's
task suite with an [evaluation](/api-reference/evaluations) once
`evaluation.status` is also `ready`. [Explore the example company and its connected
records](/product-explorer#company) to see how the blueprint appears in the product.
If `status` is `failed`, read `launch_error` and each twin's `error`. The
response contains live tokens, so keep it out of logs and source control.
[Open the task image](/images/product/worldsmith-task-focused.png).
[Explore the task and its connected records](/product-explorer#agent-task).
## The world object
| Field | What it is |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `world.id` | The ID of this version. Use it in every world method. |
| `version.number`, `version.root_world_id` | Which launch this is, and the ID shared by all versions of the same world. |
| `status` | `forging`, `ready`, `degraded`, `failed`, or `retired`. |
| `launch_error` | Why the launch failed, when it did. |
| `twins[]` | Each service: `id`, `service`, `status`, `base_url`, `token`, `error`. |
| `evaluation` | Task setup: `status`, `task_suite_id`, `environment_id`, `environment_version_id`, and `tasks[]` with each task's `task_id` and `title`. |
| `blueprint` | The blueprint as launched. |
`evaluation.status` is `materializing`, `ready`, or `failed`, separate from the
world's `status`. If it's `failed`, `worlds.materialize(world_id)` retries the
setup and returns the updated world. A world with no tasks has no `evaluation`.
## SDK and HTTP fields
The endpoint reference shows the HTTP JSON schema. SDKs expose the same data
with a consistent page type and the naming convention of your language:
| HTTP JSON | SDK view |
| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `examples`, `worlds`, `activities`, or `events` on list responses | `page.items` (Go: `page.Items`). |
| `hasMore`, `nextCursor` | `has_next_page()` / `get_next_page()` and language equivalents. The SDK carries the cursor; see [Pagination](/api-reference/reliability#pagination). |
| `world.blueprint` | `result.blueprint`, the blueprint used for this launch. |
| `launchError`, `version.rootWorldId`, `twins[].baseUrl` | Python/Rust: `launch_error`, `root_world_id`, `base_url`; TS/JS retain camelCase; Go uses `LaunchError`, `RootWorldID`, `BaseURL`. |
| `evaluation.taskSuiteId`, `evaluation.tasks[].taskId` | `task_suite_id`, `tasks[].task_id` in Python/Rust; camelCase in TS/JS; `TaskSuiteID`, `TaskID` in Go. |
| `activities[].activity.requestId`, `.method`, `.path`, `.status` | Each SDK item has `request_id`, `request.method`, `request.path`, and `response.status`, with the same language naming rules. |
| `activities[].twinInstanceId`, `.service`, `.mutations` | The SDK activity item keeps its twin ID, service, and mutation summary together. [Twin activity detail](/api-reference/twins#read-what-happened) adds before/after records. |
The blueprint export below writes **only the blueprint**, suitable for the
`blueprint.json` input used by the compile and launch endpoint examples.
`WORLD_ID` in those examples is `world.id`; `WORLD_LAUNCH_KEY` is your stable
idempotency key for one launch. Configure them in your process environment,
alongside `CHRONICLE_API_URL` and `CHRONICLE_API_KEY`.
## Retry task setup
Twin readiness and task setup are separate. After the world is `ready`, read
`evaluation.status` before starting an evaluation. While it is `materializing`,
retrieve the same world again later. If it is `failed`, retry setup with the
same world ID:
```python Python theme={null}
world = client.worlds.materialize(world_id)
if world.evaluation is None or world.evaluation.status != "ready":
raise RuntimeError(f"Task setup is not ready for world {world_id}; inspect its evaluation details")
suite_id = world.evaluation.task_suite_id
```
```typescript TypeScript theme={null}
world = await client.worlds.materialize(worldId);
if (world.evaluation?.status !== "ready") throw new Error(`Task setup is not ready for world ${worldId}`);
const suiteId = world.evaluation.taskSuiteId;
```
```javascript JavaScript theme={null}
world = await client.worlds.materialize(worldId);
if (world.evaluation?.status !== "ready") throw new Error(`Task setup is not ready for world ${worldId}`);
const suiteId = world.evaluation.taskSuiteId;
```
```go Go theme={null}
world, err = client.Worlds.Materialize(ctx, worldID)
if err != nil { return err }
if world.Evaluation == nil || world.Evaluation.Status != "ready" {
return fmt.Errorf("task setup is not ready for world %s", worldID)
}
suiteID := world.Evaluation.TaskSuiteID
fmt.Println(suiteID)
```
```rust Rust theme={null}
let world = client.worlds().materialize(&world_id).await?;
let evaluation = world.evaluation.as_ref().filter(|e| e.status == "ready")
.ok_or("Task setup is not ready; inspect the world's evaluation details")?;
let suite_id = evaluation.task_suite_id.clone();
```
A world without tasks has no evaluation setup to retry. Once setup is ready,
[inspect the generated task and scorers](/product-explorer#agent-task) or use
[Evaluations](/api-reference/evaluations) with the returned suite ID.
## Blueprint
A blueprint is an object with these top-level fields:
| Field | Contents |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`, `summary` | Display name and the situation in a sentence. |
| `clock` | The story's "now", as UTC, e.g. `2026-09-03T17:00:00Z`. |
| `organization` | Name, workspace slug, email domain, industry, description. |
| `identities` | People shared across services: handle, name, role, department, time zone. |
| `twins` | One section per service you want: `slack`, `linear`, `salesforce`, `sapS4hana`. Each holds that service's seed records. A present section creates a twin. |
| `scenario` | Background story, cross-service threads, and `tasks[]`, each with an instruction, steps, expected outcome, and `scorers[]`. |
Use readable keys for records and reference them by key; the compiler assigns
vendor-style IDs and resolves the links. The complete schema is on the
**POST /v1/worldsmith/compile** page under Worldsmith endpoints. The SDKs type
it as `WorldBlueprint`. Export the selected blueprint for the endpoint examples:
```python Python theme={null}
import json
from pathlib import Path
Path("blueprint.json").write_text(json.dumps(blueprint.model_dump(mode="json"), indent=2))
```
```typescript TypeScript theme={null}
import { writeFile } from "node:fs/promises";
await writeFile("blueprint.json", JSON.stringify(blueprint, null, 2));
```
```javascript JavaScript theme={null}
import { writeFile } from "node:fs/promises";
await writeFile("blueprint.json", JSON.stringify(blueprint, null, 2));
```
```go Go theme={null}
data, err := json.MarshalIndent(blueprint, "", " ")
if err != nil { return err }
if err := os.WriteFile("blueprint.json", data, 0600); err != nil { return err }
```
```rust Rust theme={null}
// Add serde_json to your Cargo dependencies for file import/export.
std::fs::write("blueprint.json", serde_json::to_vec_pretty(&blueprint)?)?;
```
The file contains only the blueprint, without a surrounding `blueprint` key.
Keep live twin tokens out of exported configuration.
## Launch a new version
Send the updated blueprint with `source_world_id` set to the current version's
`world.id` and a new idempotency key. The old version keeps its twins and
history.
```python Python theme={null}
v2 = client.worlds.create(
blueprint=blueprint,
source_world_id=world_id,
idempotency_key="launch-2",
)
print(v2.world.id, v2.status)
```
```typescript TypeScript theme={null}
const v2 = await client.worlds.create({
blueprint,
sourceWorldId: worldId,
idempotencyKey: "launch-2",
});
console.log(v2.world.id, v2.status);
```
```javascript JavaScript theme={null}
const v2 = await client.worlds.create({
blueprint,
sourceWorldId: worldId,
idempotencyKey: "launch-2",
});
console.log(v2.world.id, v2.status);
```
```go Go theme={null}
v2, err := client.Worlds.Create(ctx, chronicle.WorldCreateParams{
Blueprint: blueprint,
SourceWorldID: worldID,
IdempotencyKey: "launch-2",
})
if err != nil {
return err
}
fmt.Println(v2.World.ID, v2.Status)
```
```rust Rust theme={null}
let v2 = client.worlds().create(WorldCreateParams {
blueprint: blueprint.clone(),
source_world_id: Some(world_id.clone()),
idempotency_key: "launch-2".into(),
..Default::default()
}).await?;
println!("{} {}", v2.world.id, v2.status);
```
`worlds.versions.list(world_id)` returns every version in the same lineage.
Without `source_world_id`, you get a separate new world.
## Activity and lifecycle
`worlds.activity.list` returns every request made to any of the world's twins,
newest first. `worlds.lifecycle.list` returns start, stop, and reset events.
Both are pages: `items`, `has_next_page()`, `get_next_page()`.
```python Python theme={null}
page = client.worlds.activity.list(world_id, limit=50)
for activity in page.auto_paging_iter():
print(activity.service, activity.request.method, activity.request.path, activity.mutations)
```
```typescript TypeScript theme={null}
const page = await client.worlds.activity.list(worldId, { limit: 50 });
for await (const a of page) console.log(a.service, a.request.method, a.request.path, a.mutations);
```
```javascript JavaScript theme={null}
const page = await client.worlds.activity.list(worldId, { limit: 50 });
for await (const a of page) console.log(a.service, a.request.method, a.request.path, a.mutations);
```
```go Go theme={null}
page, err := client.Worlds.Activity.List(ctx, worldID, chronicle.PageParams{Limit: 50})
if err != nil {
return err
}
for {
for _, a := range page.Items {
fmt.Println(a.Service, a.Request.Method, a.Request.Path, a.Mutations)
}
if !page.HasNextPage() { break }
page, err = page.GetNextPage(ctx)
if err != nil { return err }
}
```
```rust Rust theme={null}
let mut page = client.worlds().activity().list(&world_id, PageParams { limit: Some(50), ..Default::default() }).await?;
loop {
for a in &page.items {
println!("{:?} {} {} {:?}", a.service, a.request.method, a.request.path, a.mutations);
}
if !page.has_next_page() { break; }
page = page.get_next_page().await?;
}
```
Each activity names the twin, summarizes the request, and lists the records it
changed. For the full request, response, and before/after values, use
[twin activity detail](/api-reference/twins#read-what-happened).
## Errors
| Result | Meaning |
| ------------------------------- | ---------------------------------------------------------------------- |
| Compile returns `problems` | Fix the blueprint and compile again. |
| World `status` is `failed` | Read `launch_error` and twin errors, then launch again with a new key. |
| `400` | Bad blueprint or key format. |
| `403` | Not enough twin capacity in your organization. |
| `404` | Unknown `world_id` or `source_world_id`. |
| `409` | Idempotency key reused with different inputs. |
| `503` while retrying task setup | Evaluation services aren't enabled on this deployment. |