The Sceneweave API

curl https://sceneweave.levships.com/api/v1/models \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY"

# Requires curl and jq.
export SCENEWEAVE_API_KEY="sw_live_…"   # shown once when the key is created

# Find the store to work in (or create one with POST /stores)
curl -sS https://sceneweave.levships.com/api/v1/stores \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" | jq '.data.items[] | {id, name}'

export STORE_ID="…"                     # one of the IDs above

FILE=vase.jpg                                      # PNG, JPEG, WebP or GIF up to 20 MB
TYPE=image/jpeg
SIZE=$(wc -c < "$FILE" | tr -d ' ')
SHA256=$(shasum -a 256 "$FILE" | cut -d ' ' -f 1)  # or: sha256sum "$FILE"

# 1. Reserve a one-time upload bound to the file's size and hash (valid for 15 minutes)
UPLOAD=$(curl -sS https://sceneweave.levships.com/api/v1/assets/upload-url \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg f "$FILE" --arg t "$TYPE" --argjson s "$SIZE" --arg h "$SHA256" --arg store "$STORE_ID" \
        '{filename: $f, contentType: $t, size: $s, sha256: $h, storeId: $store}')")
echo "$UPLOAD"

# 2. POST the raw bytes to the storage URL. Send the Content-Type header only: no API key.
STORAGE_ID=$(curl -sS -X POST "$(jq -r .data.uploadUrl <<<"$UPLOAD")" \
  -H "Content-Type: $TYPE" \
  --data-binary @"$FILE" | jq -r .storageId)

# 3. Finalize. Sceneweave re-reads the bytes and checks the hash, type and dimensions.
ASSET=$(curl -sS https://sceneweave.levships.com/api/v1/assets/complete \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg u "$(jq -r .data.uploadId <<<"$UPLOAD")" --arg s "$STORAGE_ID" \
        '{uploadId: $u, storageId: $s}')")
echo "$ASSET"
ASSET_ID=$(jq -r .data.id <<<"$ASSET")

PRODUCT=$(curl -sS https://sceneweave.levships.com/api/v1/products \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg store "$STORE_ID" --arg asset "$ASSET_ID" '{
        storeId: $store,
        externalId: "sku-1042",
        name: "Cobalt glaze studio vase",
        description: "Hand-thrown stoneware vase with a cobalt glaze.",
        url: "https://shop.example.com/products/sku-1042",
        imageAssetIds: [$asset],
        available: true
      }')")
echo "$PRODUCT"
PRODUCT_ID=$(jq -r .data.id <<<"$PRODUCT")

JOB=$(curl -sS https://sceneweave.levships.com/api/v1/jobs \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: article-sku-1042-care-guide" \
  -d "$(jq -n --arg store "$STORE_ID" --arg product "$PRODUCT_ID" '{
        kind: "article",
        storeId: $store,
        input: {
          title: "Living with studio pottery",
          brief: "A practical guide to choosing, displaying and caring for hand-thrown vases.",
          productIds: [$product],
          maxCostUsd: 6
        }
      }')")
echo "$JOB"
JOB_ID=$(jq -r .data.id <<<"$JOB")

{
  "data": {
    "id": "…",
    "workspaceId": "…",
    "storeId": "…",
    "kind": "article",
    "input": {},
    "model": "openai/gpt-5.6-terra",
    "status": "queued",
    "stage": "Queued",
    "progress": 0,
    "attempt": 0,
    "estimatedCostUsd": 6,
    "costUsd": 0,
    "createdAt": 1790000000000,
    "updatedAt": 1790000000000
  }
}

while true; do
  JOB=$(curl -sS "https://sceneweave.levships.com/api/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer $SCENEWEAVE_API_KEY")
  STATUS=$(jq -r .data.status <<<"$JOB")
  echo "$STATUS · $(jq -r .data.stage <<<"$JOB") · $(jq -r .data.progress <<<"$JOB")%"
  case "$STATUS" in succeeded|failed|cancelled|null) break ;; esac
  sleep 15
done
jq .data <<<"$JOB"

{
  "data": {
    "id": "…",
    "kind": "article",
    "model": "openai/gpt-5.6-terra",
    "status": "succeeded",
    "stage": "Complete",
    "progress": 100,
    "attempt": 1,
    "result": {
      "articleId": "…"
    },
    "completedAt": 1790000420000
  }
}

ARTICLE_ID=$(jq -r .data.result.articleId <<<"$JOB")

curl -sS "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  | jq '.data | {id, title, status, version, currentRevisionId, excerpt}'

curl -sS "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID/export?format=html" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -o article.html

// Uploads a product photo, creates a product, commissions an article and prints it.
// Run: SCENEWEAVE_API_KEY=sw_live_… SCENEWEAVE_STORE_ID=… npx tsx sceneweave-quickstart.ts ./vase.jpg
import { createHash, randomUUID } from "node:crypto";
import { readFile } from "node:fs/promises";
import { basename, extname } from "node:path";

const API = "https://sceneweave.levships.com/api/v1";
const apiKey = requireEnv("SCENEWEAVE_API_KEY");
const storeId = requireEnv("SCENEWEAVE_STORE_ID");

type JobStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled";
type Job = {
  id: string;
  status: JobStatus;
  stage: string;
  progress: number;
  model?: string;
  result?: { articleId?: string; proposalId?: string; ideaIds?: string[]; imageIds?: string[]; productId?: string };
  error?: string;
};
type Asset = { id: string; filename: string; size: number };
type Product = { id: string; name: string };
type Article = { id: string; title: string; status: string; version: number; currentRevisionId: string | null; excerpt: string };

class SceneweaveApiError extends Error {
  status: number;
  code: string;
  constructor(status: number, code: string, message: string) {
    super(`Sceneweave ${status} ${code}: ${message}`);
    this.status = status;
    this.code = code;
  }
}

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} first.`);
  return value;
}

async function sceneweave<T>(path: string, options: { method?: string; body?: unknown; headers?: Record<string, string> } = {}): Promise<T> {
  const response = await fetch(`${API}${path}`, {
    method: options.method ?? (options.body === undefined ? "GET" : "POST"),
    headers: {
      Authorization: `Bearer ${apiKey}`,
      ...(options.body === undefined ? {} : { "Content-Type": "application/json" }),
      ...options.headers,
    },
    body: options.body === undefined ? undefined : JSON.stringify(options.body),
  });
  const payload = (await response.json().catch(() => null)) as { data?: T; error?: { code: string; message: string } } | null;
  if (!response.ok || payload?.data === undefined) {
    throw new SceneweaveApiError(response.status, payload?.error?.code ?? "HTTP_ERROR", payload?.error?.message ?? response.statusText);
  }
  return payload.data;
}

const IMAGE_TYPES: Record<string, string> = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp", ".gif": "image/gif" };

async function uploadImage(path: string): Promise<Asset> {
  const contentType = IMAGE_TYPES[extname(path).toLowerCase()];
  if (!contentType) throw new Error("Use a JPEG, PNG, WebP or GIF file.");
  const bytes = new Uint8Array(await readFile(path));
  const sha256 = createHash("sha256").update(bytes).digest("hex");

  // 1. Reserve a one-time upload bound to this file's size and hash (valid for 15 minutes).
  const upload = await sceneweave<{ uploadId: string; uploadUrl: string }>("/assets/upload-url", {
    body: { filename: basename(path), contentType, size: bytes.byteLength, sha256, storeId },
  });

  // 2. POST the raw bytes to storage. Send the Content-Type header only, never your API key.
  const stored = await fetch(upload.uploadUrl, { method: "POST", headers: { "Content-Type": contentType }, body: bytes });
  if (!stored.ok) throw new Error(`Storage upload failed with HTTP ${stored.status}.`);
  const { storageId } = (await stored.json()) as { storageId: string };

  // 3. Finalize. Sceneweave re-reads the bytes and verifies the hash, type and dimensions.
  return sceneweave<Asset>("/assets/complete", { body: { uploadId: upload.uploadId, storageId } });
}

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function waitForJob(id: string): Promise<Job> {
  let delay = 5_000;
  for (;;) {
    const job = await sceneweave<Job>(`/jobs/${id}`);
    console.log(`${job.status} · ${job.stage} · ${job.progress}%`);
    if (job.status === "succeeded" || job.status === "failed" || job.status === "cancelled") return job;
    await sleep(delay);
    delay = Math.min(delay * 2, 30_000); // 5 s, 10 s, 20 s, then every 30 s
  }
}

async function main() {
  const file = process.argv[2];
  if (!file) throw new Error("Usage: npx tsx sceneweave-quickstart.ts ./product-photo.jpg");

  const asset = await uploadImage(file);
  console.log(`Uploaded ${asset.filename} as ${asset.id}`);

  // Reusing an externalId in the same store updates that product instead of duplicating it.
  const product = await sceneweave<Product>("/products", {
    body: {
      storeId,
      externalId: "sku-1042",
      name: "Cobalt glaze studio vase",
      description: "Hand-thrown stoneware vase with a cobalt glaze.",
      imageAssetIds: [asset.id],
      available: true,
    },
  });

  // Store the key with your own record and send it again on retries: a retry returns the same job.
  const idempotencyKey = randomUUID();
  const queued = await sceneweave<Job>("/jobs", {
    headers: { "Idempotency-Key": idempotencyKey },
    body: {
      kind: "article",
      storeId,
      input: {
        title: "Living with studio pottery",
        brief: "A practical guide to choosing, displaying and caring for hand-thrown vases.",
        productIds: [product.id],
        maxCostUsd: 6,
      },
    },
  });
  console.log(`Queued job ${queued.id} on ${queued.model ?? "the default model"}`);

  const job = await waitForJob(queued.id);
  if (job.status !== "succeeded" || !job.result?.articleId) throw new Error(`Job ${job.status}: ${job.error ?? "no article"}`);

  const article = await sceneweave<Article>(`/articles/${job.result.articleId}`);
  console.log(`\n${article.title} (${article.status}, version ${article.version})\n${article.excerpt}`);
}

main().catch((error: unknown) => {
  console.error(error instanceof Error ? error.message : error);
  process.exitCode = 1;
});

{
  "kind": "image",
  "input": {
    "mode": "place",
    "variants": 2,
    "model": "microsoft/mai-image-2.6",
    "maxCostUsd": 1
  },
  "ephemeral": {
    "products": [
      {
        "ref": "sku-1042",
        "name": "Celadon ribbed vase",
        "description": "Hand-thrown stoneware vase with a pale celadon glaze, 28 cm tall.",
        "url": "https://your-marketplace.example/items/sku-1042",
        "images": [
          {
            "url": "https://cdn.your-marketplace.example/sku-1042/front.jpg"
          }
        ],
        "metadata": {
          "heightCm": 28
        }
      }
    ],
    "baseImage": {
      "url": "https://cdn.your-marketplace.example/rooms/living-room.jpg"
    },
    "retentionHours": 24
  }
}

# 1. One call: the room, the products and their photos. Nothing is added to your catalog.
JOB_ID=$(curl -sS https://sceneweave.levships.com/api/v1/jobs \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: scene-sku-1042-living-room" \
  -d @scene-request.json | jq -r .data.id)

# 2. Wait. A finished ephemeral job carries its results in data.outputs.
until curl -sS "https://sceneweave.levships.com/api/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer $SCENEWEAVE_API_KEY" -o job.json &&
  jq -e '.data.status | IN("succeeded", "failed", "cancelled")' job.json >/dev/null; do
  sleep 10
done

# 3. Download every scene (the URLs need your API key)
jq -r '.data.outputs.images[] | "\(.id) \(.url)"' job.json | while read -r id url; do
  curl -sS "$url" -H "Authorization: Bearer $SCENEWEAVE_API_KEY" -o "scene-$id.png"
done

{
  "data": {
    "id": "…",
    "kind": "image",
    "status": "succeeded",
    "model": "microsoft/mai-image-2.6",
    "ephemeral": true,
    "expiresAt": 1790086400000,
    "costUsd": 0.19,
    "result": {
      "imageIds": ["…", "…"]
    },
    "outputs": {
      "images": [
        {
          "id": "…",
          "label": "Vase on the console's left third",
          "mode": "place",
          "assetId": "…",
          "url": "https://sceneweave.levships.com/api/v1/assets/…",
          "accepted": false,
          "products": [
            {
              "id": "…",
              "ref": "sku-1042",
              "name": "Celadon ribbed vase",
              "url": "https://your-marketplace.example/items/sku-1042"
            }
          ],
          "placement": "Celadon ribbed vase rests on the oak console at its left third, about 28 cm tall, roughly a quarter of the console's height…",
          "placementSource": "auto",
          "model": "microsoft/mai-image-2.6"
        }
      ]
    }
  }
}

{
  "kind": "article",
  "input": {
    "title": "Living with celadon: five quiet ways to display one vase",
    "brief": "Practical styling for small homes. 700–900 words, warm but precise.",
    "model": "openai/gpt-5.6-terra"
  },
  "ephemeral": {
    "store": {
      "name": "Kiln & Co",
      "voice": "Calm, precise and never salesy.",
      "audience": "First-time collectors of studio ceramics"
    },
    "products": [
      {
        "ref": "sku-1042",
        "name": "Celadon ribbed vase",
        "description": "Hand-thrown stoneware vase with a pale celadon glaze, 28 cm tall.",
        "url": "https://your-marketplace.example/items/sku-1042",
        "images": [
          {
            "url": "https://cdn.your-marketplace.example/sku-1042/front.jpg"
          }
        ]
      }
    ]
  }
}

{
  "article": {
    "id": "…",
    "title": "Living with celadon: five quiet ways to display one vase",
    "excerpt": "One well-placed vase can settle a room…",
    "locale": "en",
    "status": "review",
    "currentRevisionId": "…",
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "One well-placed vase can settle a room…"
            }
          ]
        }
      ]
    },
    "html": "<article><h1>Living with celadon…</h1>…</article>",
    "sources": [
      {
        "url": "https://museum.example/ceramics/celadon",
        "title": "Celadon glazes",
        "evidence": "Glaze history and care guidance."
      }
    ],
    "products": [
      {
        "id": "…",
        "ref": "sku-1042",
        "name": "Celadon ribbed vase",
        "url": "https://your-marketplace.example/items/sku-1042"
      }
    ]
  }
}

{
  "kind": "ideas",
  "input": {
    "count": 3,
    "direction": "Small-space styling for spring",
    "model": "openai/gpt-5.6-luna"
  },
  "ephemeral": {
    "store": {
      "name": "Kiln & Co",
      "voice": "Calm and precise.",
      "audience": "Urban renters who collect ceramics"
    },
    "products": [
      {
        "ref": "sku-1042",
        "name": "Celadon ribbed vase",
        "images": [
          {
            "url": "https://cdn.your-marketplace.example/sku-1042/front.jpg"
          }
        ]
      },
      {
        "ref": "sku-2210",
        "name": "Ash-glazed serving bowl",
        "description": "Wide, shallow stoneware bowl, 32 cm."
      }
    ],
    "retentionHours": 6
  }
}

{
  "ideas": [
    {
      "id": "…",
      "title": "One vase, three rooms: moving a single piece through the seasons",
      "angle": "Rotate one statement vessel instead of buying more.",
      "rationale": "Fits renters with limited surfaces.",
      "sources": [
        {
          "url": "https://museum.example/display/small-spaces",
          "title": "Displaying ceramics in small spaces",
          "evidence": "Negative space and grouping guidance."
        }
      ],
      "products": [
        {
          "id": "…",
          "ref": "sku-1042",
          "name": "Celadon ribbed vase"
        }
      ]
    }
  ]
}

// Places one product into a room photo and returns the scene download URLs.
// Run: SCENEWEAVE_API_KEY=sw_live_… npx tsx place-product.ts
const API = "https://sceneweave.levships.com/api/v1";
const apiKey = process.env.SCENEWEAVE_API_KEY;
if (!apiKey) throw new Error("Set SCENEWEAVE_API_KEY.");

type Scene = { id: string; label: string; url: string; placement: string | null };
type Job = { id: string; status: "queued" | "running" | "succeeded" | "failed" | "cancelled"; error?: string; outputs?: { images?: Scene[] } };

async function sceneweave<T>(path: string, init: { method?: string; body?: unknown; idempotencyKey?: string } = {}): Promise<T> {
  const response = await fetch(`${API}${path}`, {
    method: init.method ?? "GET",
    headers: { authorization: `Bearer ${apiKey}`, "content-type": "application/json", ...(init.idempotencyKey ? { "idempotency-key": init.idempotencyKey } : {}) },
    ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
  });
  const payload = (await response.json()) as { data?: T; error?: { code: string; message: string } };
  if (!response.ok || payload.data === undefined) throw new Error(`${response.status} ${payload.error?.code ?? "ERROR"}: ${payload.error?.message ?? "Request failed"}`);
  return payload.data;
}

export async function placeProduct(room: string, product: { sku: string; name: string; photo: string; url?: string }): Promise<Scene[]> {
  let job = await sceneweave<Job>("/jobs", {
    method: "POST",
    idempotencyKey: `scene-${product.sku}-${Date.now()}`,
    body: {
      kind: "image",
      input: { mode: "place", model: "microsoft/mai-image-2.6" },
      ephemeral: { baseImage: { url: room }, products: [{ ref: product.sku, name: product.name, url: product.url, images: [{ url: product.photo }] }], retentionHours: 24 },
    },
  });
  while (job.status === "queued" || job.status === "running") {
    await new Promise((resolve) => setTimeout(resolve, 10_000));
    job = await sceneweave<Job>(`/jobs/${job.id}`);
  }
  if (job.status !== "succeeded") throw new Error(job.error ?? `The job ended as ${job.status}.`);
  return job.outputs?.images ?? [];
}

const scenes = await placeProduct("https://cdn.your-marketplace.example/rooms/living-room.jpg", { sku: "sku-1042", name: "Celadon ribbed vase", photo: "https://cdn.your-marketplace.example/sku-1042/front.jpg" });
for (const scene of scenes) console.log(scene.label, scene.url);

curl -sS "https://sceneweave.levships.com/api/v1/jobs/$JOB_ID?expand=outputs" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" | jq '.data.outputs'

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key requires jobs:write."
  }
}

CURSOR=""
while :; do
  PAGE=$(curl -sS -G https://sceneweave.levships.com/api/v1/products \
    -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
    --data-urlencode "storeId=$STORE_ID" \
    --data-urlencode "limit=100" \
    ${CURSOR:+--data-urlencode "cursor=$CURSOR"})
  jq -c '.data.items[] | {id, name, available}' <<<"$PAGE"
  CURSOR=$(jq -r '.data.nextCursor // empty' <<<"$PAGE")
  [ -z "$CURSOR" ] && break
done

{
  "data": {
    "items": [
      {
        "id": "…",
        "workspaceId": "…",
        "storeId": "…",
        "name": "Cobalt glaze studio vase",
        "available": true,
        "createdAt": 1790000000000,
        "updatedAt": 1790000000000
      }
    ],
    "nextCursor": "…"
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "input.maxCostUsd: The spending cap cannot exceed this job's default limit of $8."
  }
}

curl -sS https://sceneweave.levships.com/api/v1/stores \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "North Kiln Ceramics",
    "externalId": "store-118",
    "url": "https://shop.example.com/north-kiln",
    "voice": "Warm and precise. Explain techniques without jargon.",
    "audience": "Collectors furnishing a first home"
  }'

curl -sS https://sceneweave.levships.com/api/v1/products/import \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg store "$STORE_ID" '{products: [
        {storeId: $store, externalId: "sku-1042", name: "Cobalt glaze studio vase",
         imageUrls: ["https://cdn.example.com/sku-1042.jpg"], metadata: {heightCm: 24}},
        {storeId: $store, externalId: "sku-1043", name: "Ash glaze tea bowl", available: false}
      ]}')"

{
  "metadataSchemaVersion": "vessels-2",
  "metadataSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["form", "dominantColors", "glaze"],
    "properties": {
      "form": {
        "type": ["string", "null"],
        "enum": ["vase", "bowl", "jar", "plate", null]
      },
      "dominantColors": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "maxItems": 5
      },
      "glaze": {
        "type": ["string", "null"],
        "description": "Only when visible or supplied by the seller"
      }
    }
  }
}

FILE=vase.jpg                                      # PNG, JPEG, WebP or GIF up to 20 MB
TYPE=image/jpeg
SIZE=$(wc -c < "$FILE" | tr -d ' ')
SHA256=$(shasum -a 256 "$FILE" | cut -d ' ' -f 1)  # or: sha256sum "$FILE"

# 1. Reserve a one-time upload bound to the file's size and hash (valid for 15 minutes)
UPLOAD=$(curl -sS https://sceneweave.levships.com/api/v1/assets/upload-url \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg f "$FILE" --arg t "$TYPE" --argjson s "$SIZE" --arg h "$SHA256" --arg store "$STORE_ID" \
        '{filename: $f, contentType: $t, size: $s, sha256: $h, storeId: $store}')")
echo "$UPLOAD"

# 2. POST the raw bytes to the storage URL. Send the Content-Type header only: no API key.
STORAGE_ID=$(curl -sS -X POST "$(jq -r .data.uploadUrl <<<"$UPLOAD")" \
  -H "Content-Type: $TYPE" \
  --data-binary @"$FILE" | jq -r .storageId)

# 3. Finalize. Sceneweave re-reads the bytes and checks the hash, type and dimensions.
ASSET=$(curl -sS https://sceneweave.levships.com/api/v1/assets/complete \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg u "$(jq -r .data.uploadId <<<"$UPLOAD")" --arg s "$STORAGE_ID" \
        '{uploadId: $u, storageId: $s}')")
echo "$ASSET"
ASSET_ID=$(jq -r .data.id <<<"$ASSET")

{
  "data": {
    "id": "…",
    "workspaceId": "…",
    "storeId": "…",
    "filename": "vase.jpg",
    "contentType": "image/jpeg",
    "size": 482113,
    "createdAt": 1790000000000,
    "url": "/api/v1/assets/…?workspaceId=…"
  }
}

curl -sS https://sceneweave.levships.com/api/v1/assets \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -F "file=@vase.jpg;type=image/jpeg" \
  -F "storeId=$STORE_ID"

curl -sS "https://sceneweave.levships.com/api/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -o vase-copy.jpg

JOB=$(curl -sS https://sceneweave.levships.com/api/v1/jobs \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: article-sku-1042-care-guide" \
  -d "$(jq -n --arg store "$STORE_ID" --arg product "$PRODUCT_ID" '{
        kind: "article",
        storeId: $store,
        input: {
          title: "Living with studio pottery",
          brief: "A practical guide to choosing, displaying and caring for hand-thrown vases.",
          productIds: [$product],
          maxCostUsd: 6
        }
      }')")
echo "$JOB"
JOB_ID=$(jq -r .data.id <<<"$JOB")

while true; do
  JOB=$(curl -sS "https://sceneweave.levships.com/api/v1/jobs/$JOB_ID" \
    -H "Authorization: Bearer $SCENEWEAVE_API_KEY")
  STATUS=$(jq -r .data.status <<<"$JOB")
  echo "$STATUS · $(jq -r .data.stage <<<"$JOB") · $(jq -r .data.progress <<<"$JOB")%"
  case "$STATUS" in succeeded|failed|cancelled|null) break ;; esac
  sleep 15
done
jq .data <<<"$JOB"

curl -sS -X POST "https://sceneweave.levships.com/api/v1/jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY"

# Omit the body to repeat the job with its pinned model, or choose another model
# that suits the job's kind: here a writing model, for an article job.
RETRY=$(curl -sS -X POST "https://sceneweave.levships.com/api/v1/jobs/$JOB_ID/retry" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: retry-$JOB_ID-1" \
  -d '{"model": "openai/gpt-5.6-luna"}')
echo "$RETRY"
JOB_ID=$(jq -r .data.id <<<"$RETRY")   # poll the new job; .data.retryOfJobId is the original

{
  "kind": "ideas",
  "storeId": "…",
  "input": {
    "count": 5,
    "direction": "Gifts for people who cook",
    "maxCostUsd": 2
  }
}

{
  "kind": "revision",
  "input": {
    "articleId": "…",
    "message": "Tighten the introduction and add a short care section.",
    "expectedRevisionId": "…",
    "expectedVersion": 7
  }
}

{
  "kind": "translation",
  "input": {
    "articleId": "…",
    "sourceRevisionId": "…",
    "glossary": {
      "glaze": "釉薬",
      "stoneware": "炻器"
    }
  }
}

{
  "kind": "image",
  "storeId": "…",
  "input": {
    "mode": "place",
    "baseAssetId": "…",
    "productIds": ["…", "…"],
    "instructions": "Place the vase on the sideboard, left of the window.",
    "variants": 2,
    "model": "openai/gpt-image-2.5-sunburst"
  }
}

{
  "kind": "metadata",
  "input": {
    "productId": "…",
    "model": "openai/gpt-6-astra"
  }
}

{
  "data": {
    "writing": [
      {
        "id": "openai/gpt-5.6-terra",
        "label": "GPT-5.6 Terra",
        "provider": "OpenAI",
        "summary": "Balanced research and writing quality at a moderate cost. The Sceneweave default.",
        "costTier": 2,
        "route": "codex-gateway",
        "available": true
      }
    ],
    "image": [
      {
        "id": "microsoft/mai-image-2.6",
        "label": "MAI-Image-2.6",
        "provider": "Microsoft",
        "summary": "Photorealistic edits from up to five references: the room and four products. Replacements follow the written description.",
        "costTier": 1,
        "route": "foundry",
        "modes": ["place", "replace", "suggest"],
        "masks": false,
        "maxProducts": 4,
        "available": true
      }
    ],
    "metadata": [
      {
        "id": "openai/gpt-6-astra",
        "label": "GPT-6 Astra",
        "provider": "OpenAI",
        "summary": "OpenAI's most capable model for demanding research and long-form writing.",
        "costTier": 3,
        "route": "codex-gateway",
        "available": true
      }
    ],
    "serviceDefaults": {
      "writing": "openai/gpt-5.6-terra",
      "image": "openai/gpt-image-2.5-sunburst",
      "metadata": "openai/gpt-6-astra"
    }
  }
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "input.model: MAI-Image-2.6 cannot follow painted masks. Use GPT Image 2.5 Sunburst for masked replacement, or remove the mask and describe the object to replace."
  }
}

curl -sS https://sceneweave.levships.com/api/v1/workspace \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  | jq '.data.workspace | {defaultArticleModel, defaultImageModel, articleModelOverride, imageModelOverride}'

{
  "defaultArticleModel": "anthropic/claude-opus-5",
  "defaultImageModel": null
}

{
  "kind": "image",
  "storeId": "…",
  "input": {
    "mode": "place",
    "baseAssetId": "…",
    "productIds": ["…"],
    "variants": 3,
    "maxCostUsd": 4.5
  }
}

curl -sS https://sceneweave.levships.com/api/v1/workspace \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" | jq .data.usage

{
  "type": "doc",
  "content": [
    {
      "type": "heading",
      "attrs": {
        "level": 2
      },
      "content": [
        {
          "type": "text",
          "text": "Caring for a glazed vase"
        }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        {
          "type": "text",
          "text": "Rinse it with lukewarm water and let it dry upside down, like the "
        },
        {
          "type": "productReference",
          "attrs": {
            "productId": "…",
            "caption": "cobalt glaze studio vase"
          }
        },
        {
          "type": "text",
          "text": ". Read more about "
        },
        {
          "type": "text",
          "text": "glaze care",
          "marks": [
            {
              "type": "link",
              "attrs": {
                "href": "https://example.com/glaze-care"
              }
            }
          ]
        },
        {
          "type": "text",
          "text": "."
        }
      ]
    },
    {
      "type": "sceneImage",
      "attrs": {
        "assetId": "…",
        "alt": "Cobalt glaze vase on an oak sideboard",
        "caption": "Product photograph"
      }
    }
  ]
}

ARTICLE=$(curl -sS "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY")

curl -sS -X PATCH "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq '{
        expectedRevisionId: .data.currentRevisionId,
        expectedVersion: .data.version,
        title: "Living with studio pottery: a care guide",
        saveVersion: true,
        reason: "Title agreed with merchandising"
      }' <<<"$ARTICLE")"

// Uses sceneweave() and SceneweaveApiError from the quickstart.
async function renameArticle(articleId: string, title: string) {
  for (let attempt = 0; attempt < 2; attempt++) {
    const article = await sceneweave<Article>(`/articles/${articleId}`);
    try {
      return await sceneweave<Article>(`/articles/${articleId}`, {
        method: "PATCH",
        body: { expectedRevisionId: article.currentRevisionId, expectedVersion: article.version, title, saveVersion: true },
      });
    } catch (error) {
      if (!(error instanceof SceneweaveApiError) || error.code !== "REVISION_CONFLICT") throw error;
      // Someone else saved first. Re-read and reapply this change once.
    }
  }
  throw new Error("The article keeps changing. Ask an editor to apply the change.");
}

ARTICLE=$(curl -sS "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY")

curl -sS -X POST "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID/approve" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq '{expectedRevisionId: .data.currentRevisionId, expectedVersion: .data.version}' <<<"$ARTICLE")"

{
  "revisionId": "…",
  "expectedRevisionId": "…",
  "expectedVersion": 9
}

PROPOSAL_ID=$(jq -r .data.result.proposalId <<<"$JOB")
ARTICLE=$(curl -sS "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY")

curl -sS -X POST "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID/proposals/$PROPOSAL_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq '{action: "accept", expectedVersion: .data.version}' <<<"$ARTICLE")"

ARTICLE=$(curl -sS "https://sceneweave.levships.com/api/v1/articles/$ARTICLE_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY")

curl -sS https://sceneweave.levships.com/api/v1/jobs \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ja-$ARTICLE_ID-$(jq -r .data.currentRevisionId <<<"$ARTICLE")" \
  -d "$(jq '{kind: "translation", input: {articleId: .data.id, sourceRevisionId: .data.currentRevisionId, glossary: {glaze: "釉薬"}}}' <<<"$ARTICLE")"

{
  "kind": "image",
  "storeId": "…",
  "input": {
    "mode": "replace",
    "baseAssetId": "…",
    "maskAssetId": "…",
    "productIds": ["…"],
    "targetDescription": "the floor lamp beside the sofa",
    "model": "openai/gpt-image-2.5-sunburst"
  }
}

{
  "kind": "image",
  "storeId": "…",
  "input": {
    "mode": "suggest",
    "baseAssetId": "…",
    "style": "Warm minimalism with natural textures",
    "model": "google/gemini-3.1-flash-image",
    "maxCostUsd": 3
  }
}

curl -sS -G https://sceneweave.levships.com/api/v1/images \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  --data-urlencode "storeId=$STORE_ID" \
  --data-urlencode "limit=20" \
  | jq --arg job "$JOB_ID" '.data.items[] | select(.jobId == $job) | {id, assetId, label, productIds, accepted}'

curl -sS -X POST "https://sceneweave.levships.com/api/v1/images/$IMAGE_ID/accept" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"accepted": true}'

{
  "type": "sceneImage",
  "attrs": {
    "assetId": "…",
    "alt": "Cobalt glaze vase on an oak sideboard beside a window",
    "caption": "Illustrative scene"
  }
}

curl -sS https://sceneweave.levships.com/api/v1/schedules \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg a "$ARTICLE_ID" --arg r "$REVISION_ID" \
        '{articleId: $a, revisionId: $r, scheduledAt: 1790557200000, timeZone: "Asia/Tokyo"}')"

curl -sS -X DELETE "https://sceneweave.levships.com/api/v1/schedules/$SCHEDULE_ID" \
  -H "Authorization: Bearer $SCENEWEAVE_API_KEY"

POST /events/sceneweave HTTP/1.1
Host: your-platform.example.com
Content-Type: application/json
User-Agent: Sceneweave-Webhooks/1.0
Sceneweave-Id: job.succeeded:…:1790000420000
Sceneweave-Signature: t=1790000421,v1=3f5c…

{
  "id": "job.succeeded:…:1790000420000",
  "event": "job.succeeded",
  "createdAt": 1790000420000,
  "data": {
    "jobId": "…",
    "kind": "article",
    "result": {
      "articleId": "…"
    }
  }
}

// Verifies and handles Sceneweave webhooks. Node.js 18+, no dependencies.
// Run: SCENEWEAVE_WEBHOOK_SECRET=whsec_… node sceneweave-webhooks.mjs
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";

const secret = process.env.SCENEWEAVE_WEBHOOK_SECRET; // shown once when the endpoint is added
if (!secret) throw new Error("Set SCENEWEAVE_WEBHOOK_SECRET first.");
const toleranceSeconds = 5 * 60;
const processed = new Set(); // use a durable store in production

function verifySignature(rawBody, header, now = Date.now()) {
  const fields = Object.fromEntries(
    String(header ?? "").split(",").map((part) => {
      const index = part.indexOf("=");
      return [part.slice(0, index).trim(), part.slice(index + 1).trim()];
    }),
  );
  const timestamp = Number(fields.t);
  if (!Number.isInteger(timestamp) || !/^[a-f0-9]{64}$/.test(fields.v1 ?? "")) return false;
  if (Math.abs(now / 1000 - timestamp) > toleranceSeconds) return false;
  // HMAC-SHA256 over "<t>.<raw body>", keyed with the whole secret, including "whsec_".
  const expected = createHmac("sha256", secret).update(`${fields.t}.`).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(fields.v1, "hex"));
}

function handleEvent(event) {
  if (event.event === "job.succeeded") console.log(`Job ${event.data.jobId} (${event.data.kind}) succeeded`, event.data.result);
  if (event.event === "job.failed") console.log(`Job ${event.data.jobId} (${event.data.kind}) failed: ${event.data.error}`);
  if (event.event === "article.approved") console.log(`Article ${event.data.articleId} approved (${event.data.locale}, revision ${event.data.revisionId})`);
}

const server = createServer((request, response) => {
  if (request.method !== "POST") return void response.writeHead(405).end();
  const chunks = [];
  request.on("data", (chunk) => chunks.push(chunk));
  request.on("end", () => {
    const rawBody = Buffer.concat(chunks); // verify the exact bytes before parsing them
    if (!verifySignature(rawBody, request.headers["sceneweave-signature"])) return void response.writeHead(401).end();
    const event = JSON.parse(rawBody.toString("utf8"));
    // Deliveries can repeat or arrive out of order: deduplicate by ID, then read current state from the API.
    if (!processed.has(event.id)) {
      processed.add(event.id);
      handleEvent(event);
    }
    response.writeHead(204).end(); // any 2xx within 15 seconds acknowledges the delivery
  });
});
server.listen(Number(process.env.PORT ?? 3000), () => console.log(`Listening on http://localhost:${server.address().port}`));

BODY='{"id":"job.succeeded:test:1790000420000","event":"job.succeeded","createdAt":1790000420000,"data":{"jobId":"test","kind":"article","result":{"articleId":"test"}}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SCENEWEAVE_WEBHOOK_SECRET" -hex | awk '{print $NF}')

curl -sS -i http://localhost:3000 \
  -H "Content-Type: application/json" \
  -H "Sceneweave-Id: job.succeeded:test:1790000420000" \
  -H "Sceneweave-Signature: t=$T,v1=$SIG" \
  --data "$BODY"

curl -sS https://sceneweave.levships.com/api/v1/openapi -o sceneweave-openapi.json