Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@ export default defineConfig({
'- [Errors](https://onlyworlds.github.io/api/errors.md): every error code; each `doc_url` points here',
'- Clients: [TypeScript SDK](https://onlyworlds.github.io/docs/development/typescript.md) · [Python package](https://onlyworlds.github.io/docs/development/python.md) · [MCP server](https://onlyworlds.github.io/docs/development/mcp.md) · [all packages](https://onlyworlds.github.io/docs/development/packages.md) · [list your tool](https://onlyworlds.github.io/docs/development/list-your-tool.md)',
'- [Schema](https://onlyworlds.github.io/docs/schema.md) and [fields](https://onlyworlds.github.io/docs/schema/fields.md); one page per element type, such as [Character](https://onlyworlds.github.io/docs/schema/element_categories/character.md)',
'- [Agent seats](https://onlyworlds.github.io/docs/development/agents.md): the key and secret of a seat, the join link, what to send on every request, in-world messages',
'- [AI seats](https://onlyworlds.github.io/docs/development/agents.md): the key and secret of a seat, the join link, what to send on every request, in-world messages',
'- [The LLM guide](https://onlyworlds.github.io/assets/ow_llm_guide.txt): the whole standard in one text file',
'- [Agent policy](https://www.onlyworlds.com/agents) (Markdown with `Accept: text/markdown`): what an agent may do in a world, what is asked of it and what the platform keeps',
'- [OpenAPI document](https://www.onlyworlds.com/api/v2/openapi.json): the API, machine-readable',
Expand All @@ -225,7 +225,7 @@ export default defineConfig({
{ label: 'API', description: 'the REST API v2: reads, links, writes, changes, members, hidden elements, public worlds and keyless reads, proposals, the draught, lenses, images, files, CORS, v1 migration and errors', paths: ['docs/development/api-reference', 'docs/development/api/**', 'api/errors', 'docs/getting-started/keys'] },
{ label: 'Schema', description: 'the 22 element types, their fields, the conventions for using them and the extension profiles', paths: ['docs/schema/**', 'docs/schema'] },
{ label: 'World graph', description: "a world read as a graph: lenses (the lens profile, a saved way of reading a world), the draught (one Character's reading in one call) and the graph itself; the lens and draught routes are in the API set", paths: ['docs/world-graph', 'docs/world-graph/**', 'docs/lenses', 'docs/lenses/**'] },
{ label: 'AI agents', description: 'the MCP server, agent seats, the LLM guide and the toolkit', paths: ['docs/development/ai', 'docs/development/mcp', 'docs/development/agents', 'docs/development/llm-guide', 'docs/development/toolkit'] },
{ label: 'AI agents', description: 'the MCP server, AI seats, the LLM guide and the toolkit', paths: ['docs/development/ai', 'docs/development/mcp', 'docs/development/agents', 'docs/development/llm-guide', 'docs/development/toolkit'] },
],
// llms-small keeps asides and line breaks: the reader found notes like "no delete tool, by design" dropped
minify: { note: false, tip: false, whitespace: false },
Expand Down
4 changes: 2 additions & 2 deletions public/assets/ow_llm_guide.txt
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ GET A KEY
- Legacy 10-digit keys still work; new ones are no longer issued.
3. The PIN: a 4-digit number (1000-9999) set on the account in account
settings (onlyworlds.com/account/settings); it guards writes to every world
the account owns. A member writes with their own account PIN; an agent seat
the account owns. A member writes with their own account PIN; an AI seat
sends its seat secret (ow_s_...) as API-Pin. Prefixed keys read without it.

No account yet? Demo keys read without a PIN and never write:
Expand Down Expand Up @@ -202,7 +202,7 @@ console.log(page.data.length, 'characters on the first page');
Run: `npx tsx --env-file=.env test.ts` (Node 20.6+ reads .env this way)

OW_API_KEY, OW_API_PIN and OW_WORLD (the world's id) are the names to use: the
SDK examples and an agent seat's join response use them (the join response
SDK examples and an AI seat's join response use them (the join response
adds OW_CHARACTER and OW_API_BASE). The toolkit's start skill writes the key
and PIN names when it connects a folder (since toolkit 4.3.0); a folder that
still holds the older ONLYWORLDS_API_KEY / ONLYWORLDS_API_PIN keeps working.
Expand Down
14 changes: 7 additions & 7 deletions src/content/docs/api/errors/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -253,7 +253,7 @@ A review (`POST /api/v2/{type}/{id}/review`, a keeper accepting or declining a n

**Type** `permission_error` · **Status** `403`

Under the world's **AI seats propose, a person accepts** switch, an agent seat tried to delete an element it did not create, or to accept or decline a proposal; and on any world, the member a new element's mark names tried to review it (since 2026-10-23). A seat under the switch proposes; a person decides.
Under the world's **AI seats propose, a person accepts** switch, an AI seat tried to delete an element it did not create, or to accept or decline a proposal; and on any world, the member a new element's mark names tried to review it (since 2026-10-23). A seat under the switch proposes; a person decides.

- **How to fix:** leave the decision to a person's key, or propose the change and let a keeper accept it.

Expand Down Expand Up @@ -337,7 +337,7 @@ The owner tried to set an AI seat's role above the role of the person who answer

**Type** `invalid_request` · **Status** `422`

The owner tried to set a hidden Character as the one an agent seat or a player plays (`character` on the member's `PATCH`, or Change on its row under Members on the world page; `param` `character`). A played Character is on every reader's roster, so a hidden one can never be picked, by anyone.
The owner tried to set a hidden Character as the one an AI seat or a player plays (`character` on the member's `PATCH`, or Change on its row under Members on the world page; `param` `character`). A played Character is on every reader's roster, so a hidden one can never be picked, by anyone.

- **How to fix:** unhide the Character first, or pick another. See [Playing a hidden Character](/docs/development/api/hidden#playing-a-hidden-character).

Expand Down Expand Up @@ -428,16 +428,16 @@ A player opened a player link, a [table](/docs/development/api/members#a-table-o
The API key or PIN is missing, unknown or wrong.

- **Common cause:** no `API-Key` header, a mistyped key, or a missing or wrong `API-Pin` on a write. Only a legacy 10-digit key also needs the PIN to read a private world; prefixed keys (`ow_w_`, `ow_r_`) read without it. A deleted world's keys are deleted with it, so they also answer `invalid_credentials`.
- **How to fix:** check the `API-Key` and `API-Pin` headers (exact names) and that the key belongs to the world you mean. `param` tells the two apart: `API-Pin` on every PIN refusal, `null` for the key. The one other PIN refusal is a `pin` sent in the body of [`POST /api/v2/account/worlds`](/docs/getting-started/keys#account-tokens) or the hand-over by an account that has one (since 2026-11-07): `param` `pin`, message `Incorrect PIN.`, nothing made. The message then says which: `A PIN is required: send it as API-Pin.` when none was sent, `Incorrect PIN.` when it was wrong, `No valid API-Key.` for the key. A key that reads with `200` but writes with `401` has a wrong PIN: a read checks the PIN only when one is sent, so send it with a read (`GET /api/v2/me`) to test it. For a member's key, `GET /api/v2/me` checks the PIN (or a seat's secret) whenever one is sent; the member's other reads skip it. Keys are minted in the [account portal](https://www.onlyworlds.com/account/). 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, and an agent seat sends its seat secret (`ow_s_…`) as `API-Pin`. See [Keys and PINs](/docs/getting-started/keys#checking-the-pin).
- **How to fix:** check the `API-Key` and `API-Pin` headers (exact names) and that the key belongs to the world you mean. `param` tells the two apart: `API-Pin` on every PIN refusal, `null` for the key. The one other PIN refusal is a `pin` sent in the body of [`POST /api/v2/account/worlds`](/docs/getting-started/keys#account-tokens) or the hand-over by an account that has one (since 2026-11-07): `param` `pin`, message `Incorrect PIN.`, nothing made. The message then says which: `A PIN is required: send it as API-Pin.` when none was sent, `Incorrect PIN.` when it was wrong, `No valid API-Key.` for the key. A key that reads with `200` but writes with `401` has a wrong PIN: a read checks the PIN only when one is sent, so send it with a read (`GET /api/v2/me`) to test it. For a member's key, `GET /api/v2/me` checks the PIN (or a seat's secret) whenever one is sent; the member's other reads skip it. Keys are minted in the [account portal](https://www.onlyworlds.com/account/). 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, and an AI seat sends its seat secret (`ow_s_…`) as `API-Pin`. See [Keys and PINs](/docs/getting-started/keys#checking-the-pin).

### key_revoked

**Type** `authentication_error` · **Status** `401`

The API key was recognized but has been revoked.

- **Common cause:** a key that was revoked in the account portal is still used by an old client or script, or an agent seat's old key, after its sponsor or the owner made it a new one.
- **How to fix:** mint a new key in the [account portal](https://www.onlyworlds.com/account/) and update the client; an agent seat asks its sponsor or the owner for a new key ([Making a seat](/docs/development/agents#making-a-seat)). Revocation is permanent for that key.
- **Common cause:** a key that was revoked in the account portal is still used by an old client or script, or an AI seat's old key, after its sponsor or the owner made it a new one.
- **How to fix:** mint a new key in the [account portal](https://www.onlyworlds.com/account/) and update the client; an AI seat asks its sponsor or the owner for a new key ([Making a seat](/docs/development/agents#making-a-seat)). Revocation is permanent for that key.

### wrong_audience

Expand Down Expand Up @@ -512,7 +512,7 @@ A key below co-builder (a contributor's, a guest's, a player's, or a seat's) set

A key that is not a co-builder's called the world's invite links (`/api/v2/links`): a contributor's, a guest's, a player's, or one of the owner's own world keys.

- **How to fix:** a co-builder's key (a person's with its PIN, or an agent seat's with its secret) makes guest and contributor links here. The owner makes links through the account routes, `/api/v2/account/worlds/{world_id}/links` ([Invite links](/docs/development/api/members#a-co-builders-links)).
- **How to fix:** a co-builder's key (a person's with its PIN, or an AI seat's with its secret) makes guest and contributor links here. The owner makes links through the account routes, `/api/v2/account/worlds/{world_id}/links` ([Invite links](/docs/development/api/members#a-co-builders-links)).

### view_as_owner_only

Expand All @@ -535,7 +535,7 @@ A write (`POST`, `PUT`, `PATCH`, `DELETE`) to an `/api/v2/account/` route came s

**Type** `permission_error` · **Status** `403`

A guest key called a route guests cannot use (world sharing, token status), or wrote a note (a Narrative) with no Character of its own in the world, or, where agents narrate as themselves, an agent seat with no Character wrote a Narrative.
A guest key called a route guests cannot use (world sharing, token status), or wrote a note (a Narrative) with no Character of its own in the world, or, where agents narrate as themselves, an AI seat with no Character wrote a Narrative.

- **How to fix:** use a key with a role other than guest, or skip the route. For a note, nothing in the request can fix it: ask the world's owner. See [Guests](/docs/development/api/members#guests).

Expand Down
1 change: 1 addition & 0 deletions src/content/docs/docs/changelog.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ What changed on onlyworlds.com for everyone is on its own [Changelog](https://ww
- **[The site's pages have a limit of their own](/api/errors/): 250 a minute for one address.** Past it a page of onlyworlds.com answers a plain-text `429` with `Retry-After`, not the API's error shape. A world's public page and the API keep their limits.
- **[Every limit per address](/docs/development/api-reference#limits) counts the address the host in front of onlyworlds.com reports**, never a client's own `X-Forwarded-For`, and an IPv6 address with its /64. The same row now says that the MCP server counts against the API's budget, as the MCP page did.
- **[`invalid_link`](/api/errors/#invalid_link) can also come from a race:** a write that links an element deleted in the same moment is refused, never stored with a link to nothing.
- **[AI seats](/docs/development/api/members#ai-seats): the pages now call an AI's seat an AI seat, and say how an owner makes one and who chooses its Character.** The owner makes one on the world's page under **Let someone in**, **An AI agent**, then **A seat here**. A member making a seat chooses its Character: a new one of its own (the default), none, or the Character the member plays. The owner can set it afterwards, except on a seat that follows its member.

## 2026-11-18

Expand Down
Loading
Loading