---
title: "Patch World"
method: PATCH
path: "/api/v2/world"
tags: ["World"]
---

# Patch World

`PATCH /api/v2/world`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/world`
- Auth: API key in header `API-Key` and API key in header `API-Pin`

Owner only, with one exception: a co-builder may send time_range_current alone (moving the world's now). Writable: name, description, image_url, time_basic_unit, time_format_names, time_format_equivalents, time_range_min, time_range_max, time_range_current, length_unit, mass_unit, distance_unit (free-text unit labels, at most 64 characters, trimmed; "" clears), and owner_character (a Character id in this world, or null: the owner's "this Character is me", shown by GET /members and GET /me).

## Request body

- WorldPatch: Only the fields to change. Any other key, a read-only one included, is a 422.
  - `name` string
  - `description` string
  - `image_url` string
  - `time_format_names` string[]: The names of the calendar's steps, e.g. ['Day', 'Week', 'Month', 'Year'].
  - `time_format_equivalents` string[]: How many time_basic_unit each step of time_format_names holds, in the same order, e.g. [1, 7, 30, 365] when the basic unit is Day.
  - `time_basic_unit` string: The unit every element date and duration counts in (e.g. 'Year', 'Day'): a birth_date of 1200 is 1200 of these.
  - `time_range_min` integer, nullable: The earliest point of the world's timeline, in time_basic_unit.
  - `time_range_max` integer, nullable: The latest point of the world's timeline, in time_basic_unit.
  - `time_range_current` integer, nullable: The world's present moment, in time_basic_unit.
  - `length_unit` string: Free-text label for the numbers counted in the world's length units; nothing converts.
  - `mass_unit` string: Free-text label for the numbers counted in the world's mass units; nothing converts.
  - `distance_unit` string: Free-text label for the numbers counted in the world's distance units; nothing converts.
  - `owner_character` string, uuid, nullable: The owner's "this Character is me": a Character id in this world, or null.

## Response `200`

The updated world.

- World: The world named by the credential.
  - `id` string, uuid, required
  - `name` string, required
  - `description` string, required
  - `image_url` string, required
  - `time_format_names` string[], required: The names of the calendar's steps, e.g. ['Day', 'Week', 'Month', 'Year'].
  - `time_format_equivalents` union[], required: How many time_basic_unit each step of time_format_names holds, in the same order, e.g. [1, 7, 30, 365] when the basic unit is Day.
    - union
      - integer
      - string
  - `time_basic_unit` string, required: The unit every element date and duration counts in (e.g. 'Year', 'Day'): a birth_date of 1200 is 1200 of these.
  - `time_range_min` integer, nullable, required: The earliest point of the world's timeline, in time_basic_unit.
  - `time_range_max` integer, nullable, required: The latest point of the world's timeline, in time_basic_unit.
  - `time_range_current` integer, nullable, required: The world's present moment, in time_basic_unit.
  - `length_unit` string, required: Free-text label for the numbers counted in the world's length units; nothing converts.
  - `mass_unit` string, required: Free-text label for the numbers counted in the world's mass units; nothing converts.
  - `distance_unit` string, required: Free-text label for the numbers counted in the world's distance units; nothing converts.
  - `public_read` boolean, required: Whether the world's owner opened it to the public: where the public reader is on, anyone reads it with no key (`?world=`). Set by the owner on the world page; not writable here.
  - `agent_narrator_rule` boolean, required: Whether a Narrative written through an agent seat is narrated by that seat's own Character, as a guest's is. Set by the world's owner on the world page; not writable here.
  - `owner_character` string, uuid, nullable, required: The owner's "this Character is me": a Character id in this world, or null.
  - `created_at` string, date-time, nullable, required
  - `updated_at` string, date-time, nullable, required: Moves when the world's own fields change, not on element writes.

## Other responses

- `401`: Missing, invalid or revoked credential, or a wrong PIN (authentication_error; code key_revoked for a revoked key, invalid_credentials otherwise).
- `403`: The credential is valid but lacks the scope: a read key on a write route (permission_error). Or a member key: only the world's owner can change the world's own settings (code owner_only), except that a co-builder may send time_range_current alone.
- `422`: Unknown or read-only field, or a bad value (param names it). owner_character that is not a Character in this world: "Not a Character in this world." (param owner_character).
- `429`: Too many failed PIN attempts; see the Retry-After header (rate_limited). Or too many requests: over the request budget (code too_many_requests, type rate_limited): 300 requests a minute per key or account token, 60 a minute per address for a request with neither. Retry after the Retry-After header's seconds.
- `503`: The server is busy: every request slot stayed full for 10 s (code server_busy, type api_error). Retry after the Retry-After header's seconds.

## Changes

- **2026-10-20** `78df39c4c62e`: 5 warning
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `401`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `403`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `422`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `429`
  - …1 more
- **2026-10-20** `4dd5b1cd0687`: 10 warning
  - added the new `character_taken` enum value to the `error/code` response property for the response status `401`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `403`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `422`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `429`
  - …6 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/world/patch.md)

---

[API](https://skmtc.dev/onlyworlds/apis/onlyworlds-api.md) · [All operations](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/revisions/1752622ae8ce?raw)