Construct

Create or replace a construct by id

Changed on
put/api/v2/construct/{id}

Request

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

Path parameters

idstring uuid required

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

rationalestring nullable

The internal reasoning, structure, or justification of how the construct functions or makes sense within the world. null stores ''.

historystring nullable

The historical development or ideation of the construct, and its place in wider historical contexts. null stores ''.

statusstring nullable

The present condition or operational status of the construct. null stores ''.

reachstring nullable

The geographic, cultural, or political extent of the construct's influence. null stores ''.

start_dateinteger nullable

The point in time when the construct began or was first established (uses world's TIME definition).

end_dateinteger nullable

The point in time when the construct ceased to function or lost its meaning.

founderstring uuid nullable

Character who conceived or initiated the construct. Links a Character: an existing one in this world.

custodianstring uuid nullable

Institution maintaining, enforcing, or exploiting the construct. Links an Institution: an existing one in this world.

charactersstring[] nullable

Characters relevant to the construct. Links Character elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

objectsstring[] nullable

Objects relevant to the construct. Links Object elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

locationsstring[] nullable

Locations relevant to the construct. Links Location elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

speciesstring[] nullable

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

creaturesstring[] nullable

Creatures relevant to the construct. Links Creature elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

institutionsstring[] nullable

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

traitsstring[] nullable

Traits relevant to the construct. Links Trait elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

collectivesstring[] nullable

Collectives relevant to the construct. Links Collective elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

zonesstring[] nullable

Zones relevant to the construct. Links Zone elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

abilitiesstring[] nullable

Abilities relevant to the construct. Links Ability elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

phenomenastring[] nullable

Phenomena relevant to the construct. Links Phenomenon elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

languagesstring[] nullable

Languages relevant to the construct. Links Language elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

familiesstring[] nullable

Families relevant to the construct. Links Family elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

relationsstring[] nullable

Relations relevant to the construct. Links Relation elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

titlesstring[] nullable

Titles relevant to the construct. Links Title elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

constructsstring[] nullable

Other constructs relevant to the construct. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

eventsstring[] nullable

Events relevant to the construct. Links Event elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

narrativesstring[] nullable

Narratives relevant to the construct. Links Narrative 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'construct' 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.

rationalestring required

The internal reasoning, structure, or justification of how the construct functions or makes sense within the world.

historystring required

The historical development or ideation of the construct, and its place in wider historical contexts.

statusstring required

The present condition or operational status of the construct.

reachstring required

The geographic, cultural, or political extent of the construct's influence.

start_dateinteger nullable required

The point in time when the construct began or was first established (uses world's TIME definition).

end_dateinteger nullable required

The point in time when the construct ceased to function or lost its meaning.

founderstring uuid nullable required

Character who conceived or initiated the construct. A Character's id.

custodianstring uuid nullable required

Institution maintaining, enforcing, or exploiting the construct. An Institution's id.

charactersstring[] required

Characters relevant to the construct. Character ids.

objectsstring[] required

Objects relevant to the construct. Object ids.

locationsstring[] required

Locations relevant to the construct. Location ids.

speciesstring[] required

Species relevant to the construct. Species ids.

creaturesstring[] required

Creatures relevant to the construct. Creature ids.

institutionsstring[] required

Institutions relevant to the construct. Institution ids.

traitsstring[] required

Traits relevant to the construct. Trait ids.

collectivesstring[] required

Collectives relevant to the construct. Collective ids.

zonesstring[] required

Zones relevant to the construct. Zone ids.

abilitiesstring[] required

Abilities relevant to the construct. Ability ids.

phenomenastring[] required

Phenomena relevant to the construct. Phenomenon ids.

languagesstring[] required

Languages relevant to the construct. Language ids.

familiesstring[] required

Families relevant to the construct. Family ids.

relationsstring[] required

Relations relevant to the construct. Relation ids.

titlesstring[] required

Titles relevant to the construct. Title ids.

constructsstring[] required

Other constructs relevant to the construct. Construct ids.

eventsstring[] required

Events relevant to the construct. Event ids.

narrativesstring[] required

Narratives relevant to the construct. Narrative 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 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