Python
from chronicle import Chronicle
import os
import json
from pathlib import Path
blueprint = json.loads(Path("blueprint.json").read_text())
with Chronicle(timeout=120.0) as client:
result = client.worlds.create(
blueprint=blueprint, ttl_hours=24,
idempotency_key=os.environ["WORLD_LAUNCH_KEY"],
)
print(result.world.id, result.status, result.evaluation)
print(result.launch_error)import { Chronicle } from "@chroniclelabs/sdk";
import { readFile } from "node:fs/promises";
const client = new Chronicle({ timeout: 120000 });
const blueprint = JSON.parse(await readFile("blueprint.json", "utf8"));
const idempotencyKey = process.env.WORLD_LAUNCH_KEY;
if (!idempotencyKey) throw new Error("Set WORLD_LAUNCH_KEY");
const result = await client.worlds.create({ blueprint, idempotencyKey, ttlHours: 24 });
console.log(result.world.id, result.status, result.evaluation);
console.log(result.launchError);import { Chronicle } from "@chroniclelabs/sdk";
import { readFile } from "node:fs/promises";
const client = new Chronicle({ timeout: 120000 });
const blueprint = JSON.parse(await readFile("blueprint.json", "utf8"));
const idempotencyKey = process.env.WORLD_LAUNCH_KEY;
if (!idempotencyKey) throw new Error("Set WORLD_LAUNCH_KEY");
const result = await client.worlds.create({ blueprint, idempotencyKey, ttlHours: 24 });
console.log(result.world.id, result.status, result.evaluation);
console.log(result.launchError);package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
"time"
chronicle "github.com/chronicle-labs/chronicle-go"
)
func main() {
if err := example(); err != nil { log.Fatal(err) }
}
func example() error {
ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
defer cancel()
client := chronicle.NewClient(chronicle.WithTimeout(120 * time.Second))
data, err := os.ReadFile("blueprint.json")
if err != nil {
return err
}
var params chronicle.WorldCreateParams
if err := json.Unmarshal(data, ¶ms.Blueprint); err != nil {
return err
}
params.IdempotencyKey = os.Getenv("WORLD_LAUNCH_KEY")
if params.IdempotencyKey == "" { return fmt.Errorf("set WORLD_LAUNCH_KEY") }
params.TTLHours = 24
result, err := client.Worlds.Create(ctx, params)
if err != nil {
return err
}
fmt.Println(result.World.ID, result.Status, result.Evaluation)
fmt.Println(result.LaunchError)
return nil
}use chronicle_sdk::Chronicle;
use chronicle_sdk::types::WorldCreateParams;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Chronicle::builder()
.api_key(std::env::var("CHRONICLE_API_KEY")?)
.base_url(std::env::var("CHRONICLE_API_URL")?)
.timeout(std::time::Duration::from_secs(120))
.build()?;
let blueprint = serde_json::from_slice(&std::fs::read("blueprint.json")?)?;
let result = client.worlds().create(WorldCreateParams {
blueprint,
idempotency_key: std::env::var("WORLD_LAUNCH_KEY")?,
ttl_hours: Some(24),
..Default::default()
}).await?;
println!("{} {:?} {:?}", result.world.id, result.status, result.evaluation);
println!("{:?}", result.launch_error);
Ok(())
}{
"status": "forging",
"twins": [
{
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"image": "<string>",
"service": "<string>",
"status": "running",
"tenantId": "<string>",
"token": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"baseUrl": "<string>",
"datasetVersionId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"flyAppName": "<string>",
"flyMachineId": "<string>",
"region": "<string>",
"scenarioId": "<string>"
}
],
"version": {
"number": 123,
"rootWorldId": "<string>",
"parentWorldId": "<string>"
},
"world": {
"blueprint": {
"clock": "<string>",
"identities": [
{
"department": "leadership",
"firstName": "<string>",
"handle": "<string>",
"lastName": "<string>",
"timezone": "<string>",
"title": "<string>",
"emailLocalPart": null,
"isApiOwner": false
}
],
"name": "<string>",
"organization": {
"description": "<string>",
"emailDomain": "<string>",
"industry": "<string>",
"name": "<string>",
"slug": "<string>",
"headquarters": null
},
"scenario": {
"narrative": "<string>",
"threads": [
{
"summary": "<string>",
"title": "<string>",
"touchpoints": [
{
"key": "<string>",
"role": "<string>",
"service": "slack"
}
]
}
],
"title": "<string>",
"suggestedTasks": [],
"tasks": []
},
"summary": "<string>",
"twins": {
"linear": null,
"salesforce": null,
"sapS4hana": null,
"slack": null
}
},
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"name": "<string>",
"summary": "<string>",
"tenantId": "<string>",
"twins": [
{
"entityCount": 123,
"seedSha256": "<string>",
"service": "<string>",
"twinInstanceId": "<string>"
}
],
"updatedAt": "2023-11-07T05:31:56Z"
},
"evaluation": {
"status": "materializing",
"version": 1,
"environmentId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"taskSuiteId": "<string>",
"taskSuiteVersionId": "<string>",
"tasks": []
},
"launchError": "<string>",
"warnings": []
}{
"status": "forging",
"twins": [
{
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"image": "<string>",
"service": "<string>",
"status": "running",
"tenantId": "<string>",
"token": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"baseUrl": "<string>",
"datasetVersionId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"flyAppName": "<string>",
"flyMachineId": "<string>",
"region": "<string>",
"scenarioId": "<string>"
}
],
"version": {
"number": 123,
"rootWorldId": "<string>",
"parentWorldId": "<string>"
},
"world": {
"blueprint": {
"clock": "<string>",
"identities": [
{
"department": "leadership",
"firstName": "<string>",
"handle": "<string>",
"lastName": "<string>",
"timezone": "<string>",
"title": "<string>",
"emailLocalPart": null,
"isApiOwner": false
}
],
"name": "<string>",
"organization": {
"description": "<string>",
"emailDomain": "<string>",
"industry": "<string>",
"name": "<string>",
"slug": "<string>",
"headquarters": null
},
"scenario": {
"narrative": "<string>",
"threads": [
{
"summary": "<string>",
"title": "<string>",
"touchpoints": [
{
"key": "<string>",
"role": "<string>",
"service": "slack"
}
]
}
],
"title": "<string>",
"suggestedTasks": [],
"tasks": []
},
"summary": "<string>",
"twins": {
"linear": null,
"salesforce": null,
"sapS4hana": null,
"slack": null
}
},
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"name": "<string>",
"summary": "<string>",
"tenantId": "<string>",
"twins": [
{
"entityCount": 123,
"seedSha256": "<string>",
"service": "<string>",
"twinInstanceId": "<string>"
}
],
"updatedAt": "2023-11-07T05:31:56Z"
},
"evaluation": {
"status": "materializing",
"version": 1,
"environmentId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"taskSuiteId": "<string>",
"taskSuiteVersionId": "<string>",
"tasks": []
},
"launchError": "<string>",
"warnings": []
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}Worldsmith endpoints
Launch a world version
Compile the blueprint, save a world version, and start one twin per service in the blueprint. Pass sourceWorldId to create a new version of an existing world. Reuse the same idempotencyKey to retry safely. Check status when the response arrives: failed comes with launchError. Worlds with tasks also get a task suite; its setup status is in evaluation.
Use the SDK setup with CHRONICLE_API_KEY and CHRONICLE_API_URL. The Go and Rust samples are complete entry points; Rust also needs Tokio (see Rust setup). Save the blueprint itself as blueprint.json using the blueprint export example. Do not wrap the file in a blueprint property. Set WORLD_LAUNCH_KEY to a stable key for this launch. Check world status and task setup separately before evaluating; follow Launch a world.
The schema below is the HTTP representation. SDKs normalize field names and list wrappers; see SDK and HTTP fields.
POST
/
v1
/
worldsmith
/
worlds
Python
from chronicle import Chronicle
import os
import json
from pathlib import Path
blueprint = json.loads(Path("blueprint.json").read_text())
with Chronicle(timeout=120.0) as client:
result = client.worlds.create(
blueprint=blueprint, ttl_hours=24,
idempotency_key=os.environ["WORLD_LAUNCH_KEY"],
)
print(result.world.id, result.status, result.evaluation)
print(result.launch_error)import { Chronicle } from "@chroniclelabs/sdk";
import { readFile } from "node:fs/promises";
const client = new Chronicle({ timeout: 120000 });
const blueprint = JSON.parse(await readFile("blueprint.json", "utf8"));
const idempotencyKey = process.env.WORLD_LAUNCH_KEY;
if (!idempotencyKey) throw new Error("Set WORLD_LAUNCH_KEY");
const result = await client.worlds.create({ blueprint, idempotencyKey, ttlHours: 24 });
console.log(result.world.id, result.status, result.evaluation);
console.log(result.launchError);import { Chronicle } from "@chroniclelabs/sdk";
import { readFile } from "node:fs/promises";
const client = new Chronicle({ timeout: 120000 });
const blueprint = JSON.parse(await readFile("blueprint.json", "utf8"));
const idempotencyKey = process.env.WORLD_LAUNCH_KEY;
if (!idempotencyKey) throw new Error("Set WORLD_LAUNCH_KEY");
const result = await client.worlds.create({ blueprint, idempotencyKey, ttlHours: 24 });
console.log(result.world.id, result.status, result.evaluation);
console.log(result.launchError);package main
import (
"context"
"encoding/json"
"fmt"
"log"
"os"
"time"
chronicle "github.com/chronicle-labs/chronicle-go"
)
func main() {
if err := example(); err != nil { log.Fatal(err) }
}
func example() error {
ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
defer cancel()
client := chronicle.NewClient(chronicle.WithTimeout(120 * time.Second))
data, err := os.ReadFile("blueprint.json")
if err != nil {
return err
}
var params chronicle.WorldCreateParams
if err := json.Unmarshal(data, ¶ms.Blueprint); err != nil {
return err
}
params.IdempotencyKey = os.Getenv("WORLD_LAUNCH_KEY")
if params.IdempotencyKey == "" { return fmt.Errorf("set WORLD_LAUNCH_KEY") }
params.TTLHours = 24
result, err := client.Worlds.Create(ctx, params)
if err != nil {
return err
}
fmt.Println(result.World.ID, result.Status, result.Evaluation)
fmt.Println(result.LaunchError)
return nil
}use chronicle_sdk::Chronicle;
use chronicle_sdk::types::WorldCreateParams;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Chronicle::builder()
.api_key(std::env::var("CHRONICLE_API_KEY")?)
.base_url(std::env::var("CHRONICLE_API_URL")?)
.timeout(std::time::Duration::from_secs(120))
.build()?;
let blueprint = serde_json::from_slice(&std::fs::read("blueprint.json")?)?;
let result = client.worlds().create(WorldCreateParams {
blueprint,
idempotency_key: std::env::var("WORLD_LAUNCH_KEY")?,
ttl_hours: Some(24),
..Default::default()
}).await?;
println!("{} {:?} {:?}", result.world.id, result.status, result.evaluation);
println!("{:?}", result.launch_error);
Ok(())
}{
"status": "forging",
"twins": [
{
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"image": "<string>",
"service": "<string>",
"status": "running",
"tenantId": "<string>",
"token": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"baseUrl": "<string>",
"datasetVersionId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"flyAppName": "<string>",
"flyMachineId": "<string>",
"region": "<string>",
"scenarioId": "<string>"
}
],
"version": {
"number": 123,
"rootWorldId": "<string>",
"parentWorldId": "<string>"
},
"world": {
"blueprint": {
"clock": "<string>",
"identities": [
{
"department": "leadership",
"firstName": "<string>",
"handle": "<string>",
"lastName": "<string>",
"timezone": "<string>",
"title": "<string>",
"emailLocalPart": null,
"isApiOwner": false
}
],
"name": "<string>",
"organization": {
"description": "<string>",
"emailDomain": "<string>",
"industry": "<string>",
"name": "<string>",
"slug": "<string>",
"headquarters": null
},
"scenario": {
"narrative": "<string>",
"threads": [
{
"summary": "<string>",
"title": "<string>",
"touchpoints": [
{
"key": "<string>",
"role": "<string>",
"service": "slack"
}
]
}
],
"title": "<string>",
"suggestedTasks": [],
"tasks": []
},
"summary": "<string>",
"twins": {
"linear": null,
"salesforce": null,
"sapS4hana": null,
"slack": null
}
},
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"name": "<string>",
"summary": "<string>",
"tenantId": "<string>",
"twins": [
{
"entityCount": 123,
"seedSha256": "<string>",
"service": "<string>",
"twinInstanceId": "<string>"
}
],
"updatedAt": "2023-11-07T05:31:56Z"
},
"evaluation": {
"status": "materializing",
"version": 1,
"environmentId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"taskSuiteId": "<string>",
"taskSuiteVersionId": "<string>",
"tasks": []
},
"launchError": "<string>",
"warnings": []
}{
"status": "forging",
"twins": [
{
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"image": "<string>",
"service": "<string>",
"status": "running",
"tenantId": "<string>",
"token": "<string>",
"updatedAt": "2023-11-07T05:31:56Z",
"baseUrl": "<string>",
"datasetVersionId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"expiresAt": "2023-11-07T05:31:56Z",
"flyAppName": "<string>",
"flyMachineId": "<string>",
"region": "<string>",
"scenarioId": "<string>"
}
],
"version": {
"number": 123,
"rootWorldId": "<string>",
"parentWorldId": "<string>"
},
"world": {
"blueprint": {
"clock": "<string>",
"identities": [
{
"department": "leadership",
"firstName": "<string>",
"handle": "<string>",
"lastName": "<string>",
"timezone": "<string>",
"title": "<string>",
"emailLocalPart": null,
"isApiOwner": false
}
],
"name": "<string>",
"organization": {
"description": "<string>",
"emailDomain": "<string>",
"industry": "<string>",
"name": "<string>",
"slug": "<string>",
"headquarters": null
},
"scenario": {
"narrative": "<string>",
"threads": [
{
"summary": "<string>",
"title": "<string>",
"touchpoints": [
{
"key": "<string>",
"role": "<string>",
"service": "slack"
}
]
}
],
"title": "<string>",
"suggestedTasks": [],
"tasks": []
},
"summary": "<string>",
"twins": {
"linear": null,
"salesforce": null,
"sapS4hana": null,
"slack": null
}
},
"createdAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"id": "<string>",
"name": "<string>",
"summary": "<string>",
"tenantId": "<string>",
"twins": [
{
"entityCount": 123,
"seedSha256": "<string>",
"service": "<string>",
"twinInstanceId": "<string>"
}
],
"updatedAt": "2023-11-07T05:31:56Z"
},
"evaluation": {
"status": "materializing",
"version": 1,
"environmentId": "<string>",
"environmentVersionId": "<string>",
"error": "<string>",
"taskSuiteId": "<string>",
"taskSuiteVersionId": "<string>",
"tasks": []
},
"launchError": "<string>",
"warnings": []
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}{
"error": "World not found"
}Authorizations
Your Chronicle API key (chr_...). Create one in Settings > API keys.
Body
application/json
Forge: compile the blueprint and spin up one twin instance per section, seeded with the compiled output.
A blueprint for a simulated system: connected service twins, shared identities, records, and scenario tasks. A company workflow is one example. The current blueprint format includes organization metadata and the service-specific sections below.
Show child attributes
Show child attributes
A key you choose for this launch. Retrying with the same key and the same request returns the original world. 1 to 128 characters: letters, digits, dashes, underscores, dots, or colons.
Launch a new immutable version in this existing world's lineage.
How long the twins live, in hours. 1 to 720; default 72. The saved world outlives its twins.
Required range:
x >= 0Response
This idempotency key was already used; the original launch is returned and nothing new is created.
A world with its twin instances resolved.
Aggregate of the world's twin instance statuses.
forging: At least one twin is still provisioning.
ready: Every twin is running.
degraded: Every twin is live but at least one failed its last health probe.
failed: At least one twin failed to provision.
retired: Every twin was stopped or expired.
Available options:
forging, ready, degraded, failed, retired The live records of the twins in world.twins, same order.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
A forged world as persisted: the blueprint plus the twins it spun up.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
A launch failure is retained with its physical version for inspection.
Compiler warnings from the forge; only present on the forge response, never persisted.