Zone

Create or replace a zone by id

Changed on Oct 20, 2026

put/api/v2/zone/{id}

Request

Base URL: https://www.onlyworlds.com
URL: https://www.onlyworlds.com/api/v2/zone/{id}
Auth: API key in header API-Key and API key in header API-Pin

Path parameters

idstring uuid required

The zone's id (a malformed id is a 422).

Headers

X-OW-Agentstring

Send it (any non-empty value) when an agent makes this write: the change is recorded with changed_via declared (a delete's tombstone with deleted_via). An agent seat's key and MCP are recorded as agent-made without it. The value is never stored.

Request body

idstring uuid

POST: optional client-minted id (any RFC 4122 UUID; the server mints a UUIDv7 otherwise). PUT/PATCH: ignored, the path id wins.

namestring nullable required

Name of the element. null stores ''.

descriptionstring nullable

Any kind of details about the element. null stores ''.

supertypestring nullable

The top level category to which the element belongs. null stores ''.

subtypestring nullable

The sub level category through which the element is further classified. null stores ''.

image_urlstring nullable

URL to an image representing the element. null stores ''.

rolestring nullable

The operational function or intent of the zone. null stores ''.

contextstring nullable

Historical and key knowledge about the zone. null stores ''.

start_dateinteger nullable

Date when the zone becomes extant or relevant, defined in world TIME units.

end_dateinteger nullable

Date when the zone ceases to be meaningful or enforced, defined in world TIME units.

phenomenastring[] nullable

Phenomena that affect, define, or occur within the zone. Links Phenomenon elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

linked_zonesstring[] nullable

Other zones that are associated with the zone. Links Zone elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

populationsstring[] nullable

Distinct collective groups or communities residing within the zone. Links Collective elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

titlesstring[] nullable

Titles assigned to represent, manage, or protect the zone. Links Title elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

principlesstring[] nullable

Influential mechanics acted within, upon, or by the zone. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

worldunknown

created_byunknown

changed_byunknown

changed_viaunknown

Response

Replaced: the full element.

type'zone' required

idstring uuid required

namestring required

Name of the element.

descriptionstring required

Any kind of details about the element.

supertypestring required

The top level category to which the element belongs.

subtypestring required

The sub level category through which the element is further classified.

image_urlstring required

URL to an image representing the element.

rolestring required

The operational function or intent of the zone.

contextstring required

Historical and key knowledge about the zone.

start_dateinteger nullable required

Date when the zone becomes extant or relevant, defined in world TIME units.

end_dateinteger nullable required

Date when the zone ceases to be meaningful or enforced, defined in world TIME units.

phenomenastring[] required

Phenomena that affect, define, or occur within the zone. Phenomenon ids.

linked_zonesstring[] required

Other zones that are associated with the zone. Zone ids.

populationsstring[] required

Distinct collective groups or communities residing within the zone. Collective ids.

titlesstring[] required

Titles assigned to represent, manage, or protect the zone. Title ids.

principlesstring[] required

Influential mechanics acted within, upon, or by the zone. Construct ids.

created_atstring date-time required

updated_atstring date-time required

change_seqinteger required

The world change sequence at this element's last write.

created_bystring uuid nullable required

The world membership that created this element, or null when the world's owner did.

changed_bystring uuid nullable required

The world membership that last changed this element, or null when the world's owner (or the server) did, or no write has touched it since doors were recorded.

The door of the last change: seat (an agent seat), mcp (the MCP server), declared (the request sent an X-OW-Agent header), api, v1, sync (the mobile app's sync) or server (the server, on its own behalf). The first three mean an agent made it. Null: no write since doors were recorded.

known_oftrue

Present, and true, only on an element this reader knows of but does not see whole: a guest or player reaches it only because its own Character's sheet links to it (one step out). Such a row keeps id, type, name, description, supertype, subtype, image_url, created_at, updated_at and change_seq, and its type's public fields (none for a zone); every other field reads as unset (text "", numbers and single links null, multi links [], created_by, changed_by and changed_via null, no extension fields), its files are 404, and search matches only what it keeps. Absent: the element is whole. Any other grant (it names the reader's Character, the reader knows it, it is on the roster, the reader made it) makes it whole; a hidden element is never even a stub, whatever its public fields. Read-only: a write carrying known_of is refused (known_of_not_writable).

Changes

Oct 20, 202678df39c4c62e Revision changes
- warning
  added the new known_of_not_writable enum value to the / response property for the response status
- warning
  added the new known_of_not_writable enum value to the / response property for the response status
- warning
  added the new known_of_not_writable enum value to the / response property for the response status
- warning
  added the new known_of_not_writable enum value to the / response property for the response status
- warning
  added the new known_of_not_writable enum value to the / response property for the response status
- warning
  added the new known_of_not_writable enum value to the / response property for the response status
- warning
  added the new known_of_not_writable enum value to the / response property for the response status
Oct 20, 20264dd5b1cd0687 Revision changes
- warning
  added the new character_taken enum value to the / response property for the response status
- warning
  added the new character_taken enum value to the / response property for the response status
- warning
  added the new character_taken enum value to the / response property for the response status
- warning
  added the new character_taken enum value to the / response property for the response status
- warning
  added the new character_taken enum value to the / response property for the response status
- warning
  added the new character_taken enum value to the / response property for the response status
- warning
  added the new character_taken enum value to the / response property for the response status
- warning
  added the new world_full enum value to the / response property for the response status
- warning
  added the new world_full enum value to the / response property for the response status
- warning
  added the new world_full enum value to the / response property for the response status
- warning
  added the new world_full enum value to the / response property for the response status
- warning
  added the new world_full enum value to the / response property for the response status
- warning
  added the new world_full enum value to the / response property for the response status
- warning
  added the new world_full enum value to the / response property for the response status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status

Operation history