Build on OnlyWorlds
OnlyWorlds is open source and license free. A world on onlyworlds.com is reachable through a REST API, a change feed and an MCP server; every interface reads and writes the same data, scoped by a per-world key. New here? Getting started walks through a first read and write.
The REST API at https://www.onlyworlds.com/api/v2/ serves every element type at the same routes, with cursor pagination, one-shape links, bulk writes and a change feed.
| Page | Covers |
|---|---|
| API reference | Overview: base URL, authentication, routes |
| Reads and pagination | Lists, filters, sparse fields, expansion |
| Link fields | Link fields and adding or removing links atomically |
| Writes and bulk | Create, upsert, patch, delete, bulk |
| Changes and export | The change feed, for keeping a cache or mirror in step, and the world export |
| Members | Worlds shared with people and agents, and their roles |
| Images | Uploading images |
| CORS | Calling the API from a browser |
| Classic API | The original /api/worldapi/ dialect, still supported |
| Errors | The error envelope and every error code |
The interactive reference is at onlyworlds.com/api/docs, and the machine-readable spec at openapi.json. Any language or engine without an SDK can generate a client from the spec.
| Page | For |
|---|---|
| Packages | Which SDK fits, and calling the API without one |
| TypeScript | Web apps and tools: a typed client and generated constants (npm install @onlyworlds/sdk) |
| Python | Scripts and data pipelines |
| Unity | Games: typed C# models and a client |
To start a web tool from a page that already runs, use World Starter, a template repository (MIT): plain TypeScript with Vite and the TypeScript SDK, no framework. Out of the box it reads the demo world Moppetopia, one element type at a time and one element with its links; paste a read key to read your own world. It only reads.
AI agents
Section titled “AI agents”| Page | For |
|---|---|
| AI agents | Which way in fits where the agent runs |
| MCP server | Any MCP client, at https://www.onlyworlds.com/mcp |
| Agent seats | An agent joining a world as a member, with its own key and Character |
| LLM guide | One text file that teaches the standard to a chat assistant |
| Toolkit | A Claude Code plugin with skills to import, model, read, draw and move worlds and build tools |
The schema for tool builders
Section titled “The schema for tool builders”The element types, fields and links are documented under Schema. Tools that decode the schema directly should use schema-dist: the generated distribution of the YAML, its decoder, and the ruling table.