Guide
The agentic museum guide: exhibition context (rooms, architects, artists, works), visitor question suggestions, and in-persona Q&A. Public — these endpoints power anonymous in-world visitors in Hyperfy and require no API key.
Register an exhibition for the guide
Register (or refresh) a world-builder exhibition so the museum guide can answer questions about it. Accepts a trimmed moca-exhibition@1 document — only id, name, and per-placement room/artwork identity are read; the API enriches architects, descriptions, and artist data from the museum’s own collections. Idempotent per exhibition id. Spawners call this automatically when a curator spawns with a guide — that spawn is the curator’s explicit opt-in to publish the context. Rate-limited per IP. Cortex-generated question starters are added asynchronously after registration.
Register an exhibition for the guide › Request Body
formatid^[\w.:-]+$ · requirednamegeneratorRegister an exhibition for the guide › Responses
Registered
The exhibition context document
The enriched context the guide reasons over: every room with its architect and description, every artwork with its artist — plus distinct artist/architect lists and Cortex question starters.
path Parameters
idThe exhibition id from the world builder.
The exhibition context document › Responses
The context document
The enriched context document the museum guide reasons over — the authoritative record of what hangs where in a spawned exhibition.
Visitor question suggestions
Question starters for a visitor — Cortex-generated starters plus questions templated from the exhibition’s actual works, artists, rooms, and architects. Deterministic per seed; vary it to rotate the pool.
path Parameters
idquery Parameters
seedRotation seed (default: derived from the exhibition id).
Visitor question suggestions › Responses
Suggestions
Ask the museum guide
Answer a visitor’s question about a registered exhibition. Combines the exhibition context with the museum’s Cortex Library (RAG with citations) and answers in persona — Oblak (DeCC0 #2875) by default, or any Art DeCC0 via decc0, a Soulweaver soul via soulRef, or a curator-supplied SOUL.md via soul (first match wins: soul > soulRef > decc0). Pass the running conversation in history so the guide reacts to the dialogue, not just the last question. Falls back to a context-only answer (fallback: true) when the Library is unreachable. Rate-limited per IP (~20/min).
Ask the museum guide › Request Body
exhibitionThe registered exhibition id.
questionConversation so far (last ~8 turns are used).
decc0Art DeCC0 token id whose persona the guide adopts. Omit for the default guide.
visitorVisitor display name. Optional.
soulA complete SOUL.md the guide embodies (beats soulRef/decc0).
soulNameDisplay name for the custom soul.
A Soulweaver soul coordinate — the EIP-191-signed SOUL file is resolved server-side (beats decc0).
session^[\w-]{1,64}$Stable per-visitor id. Enables server-side session memory + the async Library follow-up. Omit for a stateless reply.
speakSynthesize spoken audio for the answer (when the deployment has TTS configured).
voiceVenice TTS voice id (e.g. Serena). Empty = the deployment default.
roomUidThe placement uid of the room the visitor is in (authoritative spatial signal). Grounds 'what's in this room?' and lets the guide notice when the visitor moves rooms.
Fallback spatial signal when roomUid is absent: the visitor's world position (meters); the API maps it to the room they're inside, else the nearest.
The single work the visitor is standing in front of — grounds 'which artwork is this?' on the right piece.
Ask the museum guide › Responses
The guide’s answer