Copy page

Documentation

Integration recipes

All examples assume your key is available server-side as MOCA_API_KEY.

A tiny typed client (TypeScript)

Code
const BASE = "https://api.moca.qwellco.de/v1";

async function moca<T>(path: string, params?: Record<string, string>): Promise<T> {
  const url = new URL(BASE + path);
  for (const [k, v] of Object.entries(params ?? {})) url.searchParams.set(k, v);
  const res = await fetch(url, {
    headers: { "X-API-Key": process.env.MOCA_API_KEY! },
  });
  if (!res.ok) {
    const body = await res.json().catch(() => null);
    throw new Error(body?.errors?.[0]?.message ?? `MOCA API ${res.status}`);
  }
  return (await res.json()).data as T;
}

// Usage
const collections = await moca<Collection[]>("/collections");
const artworks = await moca<Artwork[]>("/artworks", {
  collection: "genesis",
  limit: "50",
});

Rendering artworks correctly

The cardinal rule: respect the ratio. Works are portraits, panoramas, videos — never assume squares.

Code
function ArtworkFigure({ art }: { art: Artwork }) {
  if (art.animation) {
    return (
      <video
        src={art.animation.url}
        muted loop autoPlay playsInline
        style={{ aspectRatio: art.ratio }}
      />
    );
  }
  if (!art.media) return null;
  return (
    <figure>
      {/* width/height (when present) give the browser layout hints;
          the decoded file's own ratio always wins visually. */}
      <img
        src={art.media.url}
        width={art.media.width}
        height={art.media.height}
        alt={art.name ?? "Artwork"}
        loading="lazy"
        style={{ maxWidth: "100%", height: "auto" }}
      />
      <figcaption>
        {art.name} {art.artist_name ? `— ${art.artist_name}` : ""}
      </figcaption>
    </figure>
  );
}

Python

Code
import os, requests

BASE = "https://api.moca.qwellco.de/v1"
HEADERS = {"X-API-Key": os.environ["MOCA_API_KEY"]}

def artworks(collection: str | None = None, page: int = 1, limit: int = 25):
    params = {"page": page, "limit": limit}
    if collection:
        params["collection"] = collection
    r = requests.get(f"{BASE}/artworks", headers=HEADERS, params=params, timeout=30)
    r.raise_for_status()
    body = r.json()
    return body["data"], body["meta"]

works, meta = artworks(collection="genesis")
print(f"{meta['total']} works; first: {works[0]['name']} ({works[0]['ratio']:.2f})")

Paging through everything

Code
async function* allArtworks(collection?: string) {
  for (let page = 1; ; page++) {
    const res = await fetch(
      `${BASE}/artworks?limit=100&page=${page}` +
        (collection ? `&collection=${collection}` : ""),
      { headers: { "X-API-Key": process.env.MOCA_API_KEY! } }
    );
    const { data, meta } = await res.json();
    yield* data;
    if (page * meta.limit >= meta.total) break;
  }
}

At 100 items/request and 120 requests/minute, a full catalog sync stays comfortably inside the rate limit. Cache the result — the catalog changes on the timescale of hours, not seconds.

Building agents on DeCC0s

Each DeCC0 is a fully-written character: biography, voice, personality, philosophy. include=profiles adds ready-to-use agent persona blobs:

Code
const decc0 = await moca<Decc0Detail>(`/decc0s/1`, { include: "profiles,codex" });

const systemPrompt = [
  `You are ${decc0.name?.[0]}, ${decc0.description}`,
  ...(decc0.biography ?? []),
  decc0.writing_flavor,
].join("\n");
// decc0.agent_profiles / decc0.moltbot carry structured persona versions,
// decc0.codex_document the character's lore file.

Hanging art in your own 3D space

1. GET /v1/rooms → pick a room, download model_optimized_url (a draco-compressed GLB that always carries slots — un_MUSEUM sculptures get theirs generated from the onchain slot amount). model_url is the untouched high-quality original for hero/detail rendering.
2. Find meshes named Slot_001…Slot_NNN — their transforms are wall anchors, their bounding boxes the frame size.
3. GET /v1/artworks → fit each work into a slot preserving ratio (letterbox inside the slot rectangle).
4. For video works, use the animation.url as a video texture — muted and looping.

That's the entire recipe behind the museum's own world builder.