Creature

Update part of a creature

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

Request

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

Path parameters

idstring uuid required

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

appearancestring nullable

Visual description of the creature. null stores ''.

habitsstring nullable

Typical behaviors, instincts, or recurring actions the creature tends to display. null stores ''.

demeanorstring nullable

The emotional tone or attitude the creature conveys through posture, expression, or aggression. null stores ''.

statusstring nullable

Current situation or classification of the creature. null stores ''.

weightinteger nullable

Approximate or exact weight of the creature, in the world's mass unit (World mass_unit).

heightinteger nullable

Approximate height of the creature, in the world's length unit (World length_unit).

birth_dateinteger nullable

The time of the creature's birth, recorded in the world's defined TIME unit.

challenge_ratinginteger nullable

Difficulty or threat level of the creature in a gameplay context.

hit_pointsinteger nullable

Total health or durability value in combat.

armor_classinteger nullable

Defense rating against physical attacks or effects.

speedinteger nullable

Typical movement speed, in the world's distance unit (World distance_unit) per round.

locationstring uuid nullable

Specific location where the creature is currently found or most associated with. Links a Location: an existing one in this world.

zonestring uuid nullable

Larger area or region commonly inhabited or currently claimed by the creature. Links a Zone: an existing one in this world.

speciesstring[] nullable

Species this creature belongs to. Links Species elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

traitsstring[] nullable

Traits that influence the creature's behavior, capabilities, or appearance. Links Trait elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

abilitiesstring[] nullable

Innate or learned abilities the creature can perform or activate. Links Ability elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

languagesstring[] nullable

Languages the creature can understand, speak, or otherwise use to communicate. Links Language elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

actionsstring[] nullable

Combat or tactical abilities the creature can perform or use. Links Ability 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'creature' 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.

appearancestring required

Visual description of the creature.

habitsstring required

Typical behaviors, instincts, or recurring actions the creature tends to display.

demeanorstring required

The emotional tone or attitude the creature conveys through posture, expression, or aggression.

statusstring required

Current situation or classification of the creature.

weightinteger nullable required

Approximate or exact weight of the creature, in the world's mass unit (World mass_unit).

heightinteger nullable required

Approximate height of the creature, in the world's length unit (World length_unit).

birth_dateinteger nullable required

The time of the creature's birth, recorded in the world's defined TIME unit.

challenge_ratinginteger nullable required

Difficulty or threat level of the creature in a gameplay context.

hit_pointsinteger nullable required

Total health or durability value in combat.

armor_classinteger nullable required

Defense rating against physical attacks or effects.

speedinteger nullable required

Typical movement speed, in the world's distance unit (World distance_unit) per round.

locationstring uuid nullable required

Specific location where the creature is currently found or most associated with. A Location's id.

zonestring uuid nullable required

Larger area or region commonly inhabited or currently claimed by the creature. A Zone's id.

speciesstring[] required

Species this creature belongs to. Species ids.

traitsstring[] required

Traits that influence the creature's behavior, capabilities, or appearance. Trait ids.

abilitiesstring[] required

Innate or learned abilities the creature can perform or activate. Ability ids.

languagesstring[] required

Languages the creature can understand, speak, or otherwise use to communicate. Language ids.

actionsstring[] required

Combat or tactical abilities the creature can perform or use. Ability 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