Getting started

This page is for developers and AI agents that read and write worlds through the API. To build a world without code, start at onlyworlds.com/start or open Atlas.

OnlyWorlds is an open standard for world data. It structures a world into 22 element types (Characters, Locations, Events and more) with fields and typed links between them, so any tool or AI agent that speaks the standard can read and write the same worlds.

It has four layers:

Layer	What it is
Standard	The element types, their fields and links, kept as YAML files, governed in public by the Council. See Schema.
Platform	onlyworlds.com stores worlds, their members and roles, and issues per-world keys.
Interfaces	The REST API, the change feed, the MCP server and agent seats.
Clients	Apps and tools (Atlas, the Obsidian plugin, converters), SDKs, and AI agents.

A video introduction covers the project as a whole.

Your first call

1. Get a key

Sign up at onlyworlds.com and create a world. Then mint a key for it in the account portal:

Key	What it is	Reads	Writes
ow_w_…	One world, read and write	The key alone	The key and your PIN
ow_r_…	One world, read only, safe to share	The key alone	Refused
ow_w_… and ow_s_…	An agent seat’s key and its seat secret	The key alone	The key, with the seat secret as the PIN
10-digit	The original world key, no longer issued	The key and the PIN when the world has one; the demo keys read with the key alone	The key and the PIN
ow_a_…	An account token, from signing in	A world you name with world=<id>, as you	Your account’s own routes, never a world’s elements

Each world key decides which world a request reads or writes, so you never send a world id. Older 10-digit keys still work and never expire. Keys and PINs covers each kind in full.

Send the key as the API-Key header, and the PIN as API-Pin. The PIN is a 4-digit number (1000 to 9999) set on your account in account settings, and it guards writes to every world you own; a member writes with their own account PIN.

2. Read

List the Characters in a world:

curl -H "API-Key: ow_r_your_key" \
  "https://www.onlyworlds.com/api/v2/character/"

Lists come in an envelope: {"data": [...], "has_more": false, "next_cursor": null}. When has_more is true, pass next_cursor back as ?cursor= for the next page. To try this before you have a world, use Moppetopia’s demo key 0000000001 (the home page’s sample world), which reads without a PIN (Demo keys lists the others).

Every element type has the same routes at its singular name: /api/v2/location/, /api/v2/event/, and so on. Reads and pagination covers filters, sparse fields and expansion.

3. Write

Create a Character with a write key and the PIN. Only name is required: the key must be present, and an empty string is accepted.

curl -X POST "https://www.onlyworlds.com/api/v2/character/" \
  -H "API-Key: ow_w_your_key" \
  -H "API-Pin: 1234" \
  -H "Content-Type: application/json" \
  -d '{"name": "The Consul"}'

The response is 201 with the full element, including its server-assigned id. Change it with PATCH, sending only the fields you change. A link is the id of the element it points to:

curl -X PATCH "https://www.onlyworlds.com/api/v2/character/<character-id>/" \
  -H "API-Key: ow_w_your_key" \
  -H "API-Pin: 1234" \
  -H "Content-Type: application/json" \
  -d '{"description": "Diplomat of the Hegemony.", "location": "<location-id>"}'

A read key on a write route answers 403 (permission_error). Writes and bulk covers upserts, deletes and clearing fields; Link fields covers adding and removing links without reading first.

Where to go next

• Build an app or script: SDKs for TypeScript, Python and Unity, or the API reference.
• Connect an AI agent: the MCP server, agent seats, the LLM guide and the toolkit, under AI agents.
• Learn the data model: Schema, Fields and Conventions.
• Build a world without code: the guide at onlyworlds.com/start covers which tool fits how you work, and Bring in your notes the ways to turn existing material into a world. Atlas is the recommended workspace and keeps your world as plain files on your own disk or in your browser; the Obsidian plugin keeps a world as markdown notes in your vault, with optional sync to onlyworlds.com. Every tool is listed under Tools.
• Shape the standard: motions and votes happen at council.onlyworlds.com.