Location

Update part of a location

Changed on
patch/api/v2/location/{id}

Request

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

Path parameters

idstring uuid required

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

Headers

If-Matchstring

Apply only if the element's change_seq is still this number (quoted or bare; * or no header means unconditional). When the element has moved, 412 precondition_failed with the live element as current beside the envelope; nothing is written and nothing is merged.

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

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 ''.

formstring nullable

Visual and environmental aspects of the location. null stores ''.

functionstring nullable

Main use, role, or purpose of the location within the world. null stores ''.

political_climatestring nullable

Political structure, stability, and dynamics of the location. null stores ''.

customsstring nullable

Cultural practices, habits, or festivals. null stores ''.

infrastructurestring nullable

Roads, ports, and other physical systems that enable the movement of goods and people. null stores ''.

architecturestring nullable

Look, form, and materials used in the built environment and location design. null stores ''.

defensibilitystring nullable

Qualities of natural, constructed, and implemented defenses at the location. null stores ''.

founding_dateinteger nullable

Date on which the location was founded, established, or designated.

elevationinteger nullable

Height or elevation of the location relative to surrounding terrain, in the world's distance unit (World distance_unit).

parent_locationstring uuid nullable

Wider location that this location is part of. Links a Location: an existing one in this world.

primary_powerstring uuid nullable

Institution that has the highest degree of political control over the location. Links an Institution: an existing one in this world.

governing_titlestring uuid nullable

Governing figure assigned by the location's primary power. Links a Title: an existing one in this world.

zonestring uuid nullable

Zone of interest that is associated with the location. Links a Zone: an existing one in this world.

rivalstring uuid nullable

Location with an active, traditional, or historical rivalry with this one. Links a Location: an existing one in this world.

partnerstring uuid nullable

Location with active, cooperative, or historical ties to this one. Links a Location: an existing one in this world.

populationsstring[] nullable

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

secondary_powersstring[] nullable

Institutions with significant political control. Links Institution elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

foundersstring[] nullable

Individual(s) who founded or named the location. Links Character elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

cultsstring[] nullable

Significant religious constructs practiced or recognized at the location. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

delicaciesstring[] nullable

Organisms or other species locally consumed or celebrated as specialty foods. Links Species elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

extraction_methodsstring[] nullable

Techniques or strategies used to gather natural resources. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

extraction_goodsstring[] nullable

Products and materials that are gathered or obtained. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

industry_methodsstring[] nullable

Techniques or workflows used to refine or manufacture goods. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

industry_goodsstring[] nullable

Products and materials that are refined or manufactured. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

extraction_marketsstring[] nullable

Locations that receive extracted goods through trade, interchange, or seizure. Links Location elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

industry_marketsstring[] nullable

Locations that receive industrial goods through trade, interchange, or seizure. Links Location elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

currenciesstring[] nullable

Trade media recognized or circulated at the location. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

buildingsstring[] nullable

Notable structural objects at the location. Links Object elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

building_methodsstring[] nullable

Techniques or systems used to construct structures at the location. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

fightersstring[] nullable

Military units or forces responsible for defending the location. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

defensive_objectsstring[] nullable

Objects or installations for defending the location. Links Object 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

Updated: the full element.

type'location' 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.

formstring required

Visual and environmental aspects of the location.

functionstring required

Main use, role, or purpose of the location within the world.

political_climatestring required

Political structure, stability, and dynamics of the location.

customsstring required

Cultural practices, habits, or festivals.

infrastructurestring required

Roads, ports, and other physical systems that enable the movement of goods and people.

architecturestring required

Look, form, and materials used in the built environment and location design.

defensibilitystring required

Qualities of natural, constructed, and implemented defenses at the location.

founding_dateinteger nullable required

Date on which the location was founded, established, or designated.

elevationinteger nullable required

Height or elevation of the location relative to surrounding terrain, in the world's distance unit (World distance_unit).

parent_locationstring uuid nullable required

Wider location that this location is part of. A Location's id.

primary_powerstring uuid nullable required

Institution that has the highest degree of political control over the location. An Institution's id.

governing_titlestring uuid nullable required

Governing figure assigned by the location's primary power. A Title's id.

zonestring uuid nullable required

Zone of interest that is associated with the location. A Zone's id.

rivalstring uuid nullable required

Location with an active, traditional, or historical rivalry with this one. A Location's id.

partnerstring uuid nullable required

Location with active, cooperative, or historical ties to this one. A Location's id.

populationsstring[] required

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

secondary_powersstring[] required

Institutions with significant political control. Institution ids.

foundersstring[] required

Individual(s) who founded or named the location. Character ids.

cultsstring[] required

Significant religious constructs practiced or recognized at the location. Construct ids.

delicaciesstring[] required

Organisms or other species locally consumed or celebrated as specialty foods. Species ids.

extraction_methodsstring[] required

Techniques or strategies used to gather natural resources. Construct ids.

extraction_goodsstring[] required

Products and materials that are gathered or obtained. Construct ids.

industry_methodsstring[] required

Techniques or workflows used to refine or manufacture goods. Construct ids.

industry_goodsstring[] required

Products and materials that are refined or manufactured. Construct ids.

extraction_marketsstring[] required

Locations that receive extracted goods through trade, interchange, or seizure. Location ids.

industry_marketsstring[] required

Locations that receive industrial goods through trade, interchange, or seizure. Location ids.

currenciesstring[] required

Trade media recognized or circulated at the location. Construct ids.

buildingsstring[] required

Notable structural objects at the location. Object ids.

building_methodsstring[] required

Techniques or systems used to construct structures at the location. Construct ids.

fightersstring[] required

Military units or forces responsible for defending the location. Construct ids.

defensive_objectsstring[] required

Objects or installations for defending the location. Object 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.

changed_via'seat' | 'mcp' | 'declared' | 'api' | 'v1' | 'sync' | 'server' | 'null' nullable required

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; 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 its name and description. 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.

Changes

  • 4dd5b1cd0687Revision 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 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

    • 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