Title

Get one title

Changed on
get/api/v2/title/{id}

Request

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

Path parameters

idstring uuid required

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

Query parameters

expandstring[]

Comma-separated link fields whose ids are replaced by ElementStub objects (one level deep). A field that is not a link is a 422.

fieldsstring[]

Comma-separated sparse fieldset: only these keys are returned, so type never and id only when named. Accepts: id, name, description, supertype, subtype, image_url, authority, eligibility, status, history, grant_date, revoke_date, issuer, body, superior_title, holders, symbols, characters, institutions, families, zones, locations, objects, constructs, laws, collectives, creatures, phenomena, species, languages, created_at, updated_at, change_seq, created_by, changed_by, changed_via, or any extension field name. Anything else is a 422. With expand, a link is expanded only if it is also named here.

asstring

View as (the owner's keys only: a key with no member): read as another reader would. A membership id of this world (a person, an agent seat or a player seat) reads as that member's own key, its own creations included; a Character id reads as a guest of that Character with no membership (what it knows, the roster, nothing counted as its own); public reads everything that is not hidden. A hidden element is the plain 404, never a 410. An unknown value is a 422 (param as); a member key sending it is a 403 view_as_owner_only. Writes, /changes, /members, /me, the world and the files routes do not take it (422).

Response

The element. With ?fields= the body holds only the named keys (not this schema's required set); with ?expand= each named link holds ElementStub objects instead of ids.

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

authoritystring required

Rights or powers granted by the title.

eligibilitystring required

Conditions or qualifications for receiving or holding the title.

statusstring required

Current state or general condition of the title.

historystring required

Background information on the title's origin, evolution, or significance.

grant_dateinteger nullable required

Date on which the title was granted, defined in world TIME units.

revoke_dateinteger nullable required

Date on which the title ended or was revoked, defined in world TIME units.

issuerstring uuid nullable required

Institution that formally created or granted the title. An Institution's id.

bodystring uuid nullable required

Institution in which the title functions or holds relevance. An Institution's id.

superior_titlestring uuid nullable required

Another title that has authority over this one. A Title's id.

holdersstring[] required

Characters who currently hold or represent the title. Character ids.

symbolsstring[] required

Objects that symbolize or authorize the title. Object ids.

charactersstring[] required

Characters otherwise relevant to the title. Character ids.

institutionsstring[] required

Institutions relevant to the title. Institution ids.

familiesstring[] required

Families relevant to the title. Family ids.

zonesstring[] required

Zones relevant to the title. Zone ids.

locationsstring[] required

Locations relevant to the title. Location ids.

objectsstring[] required

Objects otherwise relevant to the title. Object ids.

constructsstring[] required

Constructs relevant to the title. Construct ids.

lawsstring[] required

Laws relevant to the title. Law ids.

collectivesstring[] required

Collectives relevant to the title. Collective ids.

creaturesstring[] required

Creatures relevant to the title. Creature ids.

phenomenastring[] required

Phenomena relevant to the title. Phenomenon ids.

speciesstring[] required

Species relevant to the title. Species ids.

languagesstring[] required

Languages relevant to the title. Language 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