# 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](https://www.onlyworlds.com/start) or open [Atlas](https://atlas.onlyworlds.com).

OnlyWorlds is an open standard for world data. It structures a world into [22 element types](/docs/schema/) (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](https://council.onlyworlds.com). See [Schema](/docs/schema/). |
| **Platform** | [onlyworlds.com](https://www.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](https://youtu.be/1IEazx8wg4I) covers the project as a whole.

## Your first call

### 1. Get a key

Sign up at [onlyworlds.com](https://www.onlyworlds.com/accounts/signup/) and create a world. Then mint a key for it in the [account portal](https://www.onlyworlds.com/account/):

| 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](/docs/getting-started/keys#agent-seat-keys)'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](/docs/getting-started/keys#account-tokens), 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](/docs/getting-started/keys) 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](https://www.onlyworlds.com/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:

```bash
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](/docs/getting-started/keys#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](/docs/development/api/reads) 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.

```bash
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:

```bash
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`](/api/errors/#permission_error)). [Writes and bulk](/docs/development/api/writes) covers upserts, deletes and clearing fields; [Link fields](/docs/development/api/links) covers adding and removing links without reading first.

## Where to go next

- **Build an app or script**: [SDKs](/docs/development/packages) for TypeScript, Python and Unity, or the [API reference](/docs/development/api-reference).
- **Connect an AI agent**: the [MCP server](/docs/development/mcp), agent seats, the LLM guide and the toolkit, under [AI agents](/docs/development/ai).
- **Learn the data model**: [Schema](/docs/schema/), [Fields](/docs/schema/fields) and [Conventions](/docs/schema/conventions).
- **Build a world without code**: the guide at [onlyworlds.com/start](https://www.onlyworlds.com/start) covers which tool fits how you work, and [Bring in your notes](/docs/tools/#bring-in-your-notes) the ways to turn existing material into a world. [Atlas](https://atlas.onlyworlds.com) is the recommended workspace and keeps your world as plain files on your own disk or in your browser; the [Obsidian plugin](https://github.com/OnlyWorlds/obsidian-plugin) keeps a world as markdown notes in your vault, with optional sync to onlyworlds.com. Every tool is listed under [Tools](/docs/tools/).
- **Shape the standard**: motions and votes happen at [council.onlyworlds.com](https://council.onlyworlds.com).