Ability

Create an ability

Changed on
post/api/v2/ability

Request

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

Headers

Idempotency-Keystring

Replays of the same key with the same body return the first successful response (with Idempotent-Replay: true) for 24h; the same key with a different body is a 409 idempotency_error. While the first request with a key is still running, the same key is a 409 idempotency_in_flight: retry after Retry-After.

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

activationstring nullable

Method or conditions under which the ability is activated. null stores ''.

challengesstring nullable

Describes specific difficulties or constraints that make the ability hard to master or use effectively. null stores ''.

prevalencestring nullable

How widely the ability is known or practiced, and potential clues to its origins and cultural diffusion. null stores ''.

durationinteger nullable

Length of time the ability remains active or its effects persist, measured in TIME units.

potencyinteger nullable

Relative measure of the ability's inherent potency or force, used for scaling or comparison purposes.

rangeinteger nullable

Effective reach or distance at which the ability can be used, in the world's distance unit (World distance_unit).

traditionstring uuid nullable

A construct that expresses the conceptual, social, or institutional system this ability operates within. Links a Construct: an existing one in this world.

sourcestring uuid nullable

The phenomenon that serves as the enabling force or condition that allows this ability to function. Links a Phenomenon: an existing one in this world.

locusstring uuid nullable

Location where the ability is most strongly rooted, developed, or traditionally practiced. Links a Location: an existing one in this world.

effectsstring[] nullable

Phenomena that result from the ability's use, such as environmental changes or sensory effects. Links Phenomenon elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

talentsstring[] nullable

Traits that naturally enhance or improve performance with this ability. Links Trait elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

requisitesstring[] nullable

Constructs that must be satisfied for the ability to be used, such as rituals, permissions, or required roles. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

instrumentsstring[] nullable

Objects or tools required to activate, channel, or perform the ability. Links Object elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.

systemsstring[] nullable

Magic frameworks or structures that the ability associates with. 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

Created: the full element.

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

activationstring required

Method or conditions under which the ability is activated.

challengesstring required

Describes specific difficulties or constraints that make the ability hard to master or use effectively.

prevalencestring required

How widely the ability is known or practiced, and potential clues to its origins and cultural diffusion.

durationinteger nullable required

Length of time the ability remains active or its effects persist, measured in TIME units.

potencyinteger nullable required

Relative measure of the ability's inherent potency or force, used for scaling or comparison purposes.

rangeinteger nullable required

Effective reach or distance at which the ability can be used, in the world's distance unit (World distance_unit).

traditionstring uuid nullable required

A construct that expresses the conceptual, social, or institutional system this ability operates within. A Construct's id.

sourcestring uuid nullable required

The phenomenon that serves as the enabling force or condition that allows this ability to function. A Phenomenon's id.

locusstring uuid nullable required

Location where the ability is most strongly rooted, developed, or traditionally practiced. A Location's id.

effectsstring[] required

Phenomena that result from the ability's use, such as environmental changes or sensory effects. Phenomenon ids.

talentsstring[] required

Traits that naturally enhance or improve performance with this ability. Trait ids.

requisitesstring[] required

Constructs that must be satisfied for the ability to be used, such as rituals, permissions, or required roles. Construct ids.

instrumentsstring[] required

Objects or tools required to activate, channel, or perform the ability. Object ids.

systemsstring[] required

Magic frameworks or structures that the ability associates with. 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.

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

    • 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