World generation examples

curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -d '{
    "name": "Coastal Castle",
    "premise": "A grand, ivy-covered castle rises from the shoreline at sunset"
  }'

const res = await fetch("https://api.alakazam.gg/v1/worlds", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Coastal Castle",
    premise: "A grand, ivy-covered castle rises from the shoreline at sunset",
  }),
});
console.log(await res.json());

import requests

res = requests.post(
    "https://api.alakazam.gg/v1/worlds",
    headers={"Authorization": "Bearer YOUR_SECRET_KEY"},
    json={
        "name": "Coastal Castle",
        "premise": "A grand, ivy-covered castle rises from the shoreline at sunset",
    },
)
print(res.text)

curl -X POST 'https://api.alakazam.gg/v1/worlds' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Chapter One",
    "text": "The lamplighter turned up the last wick on Vellum Street just as the fog rolled in off the river… (paste the full chapter here)",
    "async": true
  }'
# → 202 { "jobId": "…", "status": "queued" }

const chapter = await fs.readFile("chapter-01.txt", "utf8");

const res = await fetch("https://api.alakazam.gg/v1/worlds", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Chapter One", text: chapter, async: true }),
});
const { jobId } = await res.json(); // poll GET /v1/jobs/:jobId until succeeded

# 1. Kick off the campaign (async)
curl -X POST 'https://api.alakazam.gg/v1/campaigns' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "The Lamplighter Cycle",
    "text": "The lamplighter turned up the last wick on Vellum Street just as the fog rolled in off the river… (paste the whole book here)",
    "fidelity": "faithful",
    "subject_ref": { "image_url": "https://example.com/protagonist.png" }
  }'
# → 202 { "jobId": "…", "campaignId": "…" }

# 2. Poll the job until it's done (actsDone / actsTotal advance per chapter)
curl 'https://api.alakazam.gg/v1/jobs/JOB_ID' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'
# → { "status": "running", "actsDone": 3, "actsTotal": 8, "campaignId": "…" }

# 3. Read the campaign's chapter worlds
curl 'https://api.alakazam.gg/v1/campaigns/CAMPAIGN_ID' \
  -H 'Authorization: Bearer YOUR_SECRET_KEY'
# → { "id": "…", "title": "…", "actCount": 8,
#     "worlds": [ { "worldId": "…", "actIndex": 0, "title": "…", "slug": "…" }, … ] }

const book = await fs.readFile("the-lamplighter-cycle.txt", "utf8");

// 1. Kick off the campaign (always async)
const start = await fetch("https://api.alakazam.gg/v1/campaigns", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_SECRET_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "The Lamplighter Cycle",
    text: book,
    fidelity: "faithful",
    subject_ref: { image_url: "https://example.com/protagonist.png" },
  }),
});
const { jobId, campaignId } = await start.json();

// 2. Poll the job until it finishes
let job;
do {
  await new Promise((r) => setTimeout(r, 5000));
  job = await (
    await fetch(`https://api.alakazam.gg/v1/jobs/${jobId}`, {
      headers: { Authorization: "Bearer YOUR_SECRET_KEY" },
    })
  ).json();
  console.log(`chapters ${job.actsDone ?? 0}/${job.actsTotal ?? "?"}`);
} while (job.status === "queued" || job.status === "running");

// 3. Fetch the chapter worlds, each is an ordinary world you run via /v1/sessions/token
const campaign = await (
  await fetch(`https://api.alakazam.gg/v1/campaigns/${campaignId}`, {
    headers: { Authorization: "Bearer YOUR_SECRET_KEY" },
  })
).json();
for (const chapter of campaign.worlds) {
  console.log(chapter.actIndex, chapter.title, chapter.worldId);
}