Concepts

Worlds, documents, eras, and projects — the vvd data model.

World

A world is one storytelling universe — its characters, places, timelines, and lore. A world is created with a name and an optional genre (which sets its default theme). You must be a member of a world to see it, and an editor (owner, admin, or editor role) to change it.

POST /api/v1/worlds            { "name": "Eldermoor", "genre": "fantasy" }
GET  /api/v1/worlds            # the worlds you belong to
GET  /api/v1/worlds/{worldId}

Document

Everything inside a world is a document with a documentType: card (a character, place, or thing), timeline, map, folder, and more. Creating a document makes its metadata; its content is filled in through the editor or the content API.

GET  /api/v1/worlds/{worldId}/documents          # ?documentType=timeline to filter
POST /api/v1/worlds/{worldId}/documents          { "name": "…", "documentType": "card" }
GET  /api/v1/worlds/{worldId}/documents/{id}     # metadata + content projection

Documents accept only valid types for the world — the same allow-list the app enforces (built-in types plus any tool installed in that world).

Era

An era is a version of a world — "the world, five hundred years later." A new era inherits the world's full content by reference, so creating one copies nothing.

GET  /api/v1/worlds/{worldId}/eras
POST /api/v1/worlds/{worldId}/eras     { "name": "The Third Age" }

Project

A project is an app-instance inside a world — a Quill writing space, a Wiki, a Campaign. Its kind is the app id.

GET  /api/v1/worlds/{worldId}/projects
POST /api/v1/worlds/{worldId}/projects  { "kind": "quill", "name": "Draft One" }

Search

Full-text search across a world's document names and content:

GET /api/v1/worlds/{worldId}/search?q=dragon