--- title: "Create or replace a narrative by id" method: PUT path: "/api/v2/narrative/{id}" tags: ["Narrative"] --- # Create or replace a narrative by id `PUT /api/v2/narrative/{id}` ## Request - Base URL: `https://www.onlyworlds.com` - URL: `https://www.onlyworlds.com/api/v2/narrative/{id}` - Auth: API key in header `API-Key` and API key in header `API-Pin` ## Path parameters - `id` string, uuid, required ## Headers - `X-OW-Agent` string ## Request body - NarrativeWrite: A full narrative write (POST creates; PUT creates or fully replaces, resetting omitted fields to empty). Any key that is neither a field below nor an extension field (atlas_*, shadow_*, x_*) is a 422, including the server-managed type, created_at, updated_at and change_seq. - `id` string, uuid: POST: optional client-minted id (any RFC 4122 UUID; the server mints a UUIDv7 otherwise). PUT/PATCH: ignored, the path id wins. - `name` string, nullable, required: Name of the element. null stores ''. - `description` string, nullable: Any kind of details about the element. null stores ''. - `supertype` string, nullable: The top level category to which the element belongs. null stores ''. - `subtype` string, nullable: The sub level category through which the element is further classified. null stores ''. - `image_url` string, nullable: URL to an image representing the element. null stores ''. - `story` string, nullable: Content of the narrative, as told or remembered. null stores ''. - `consequences` string, nullable: Outcomes or legacy of the narrative. null stores ''. - `start_date` integer, nullable: Date when the narrative is first told or recorded, measured in world TIME units; the span it recounts lives on its events. - `end_date` integer, nullable: Date when the narrative stops being told, measured in world TIME units; empty while it is still told. - `order` integer, nullable: Position of this narrative within a parent narrative's sequence. - `parent_narrative` string, uuid, nullable: Larger narrative that this narrative takes place in. Links a Narrative: an existing one in this world. - `protagonist` string, uuid, nullable: Primary character of the narrative. Links a Character: an existing one in this world. - `antagonist` string, uuid, nullable: Opposing character of the narrative. Links a Character: an existing one in this world. - `narrator` string, uuid, nullable: Character credited with telling or recording the narrative. Links a Character: an existing one in this world. - `conservator` string, uuid, nullable: Institution that preserves or curates the narrative. Links an Institution: an existing one in this world. - `events` string[], nullable: Events relevant to the narrative. Links Event elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `characters` string[], nullable: Characters relevant to the narrative. Links Character elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `objects` string[], nullable: Objects relevant to the narrative. Links Object elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `locations` string[], nullable: Locations relevant to the narrative. Links Location elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `species` string[], nullable: Species relevant to the narrative. Links Species elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `creatures` string[], nullable: Creatures relevant to the narrative. Links Creature elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `institutions` string[], nullable: Institutions relevant to the narrative. Links Institution elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `traits` string[], nullable: Traits relevant to the narrative. Links Trait elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `collectives` string[], nullable: Groups relevant to the narrative. Links Collective elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `zones` string[], nullable: Zones relevant to the narrative. Links Zone elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `abilities` string[], nullable: Abilities relevant to the narrative. Links Ability elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `phenomena` string[], nullable: Phenomena relevant to the narrative. Links Phenomenon elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `languages` string[], nullable: Languages relevant to the narrative. Links Language elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `families` string[], nullable: Families relevant to the narrative. Links Family elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `relations` string[], nullable: Relationships relevant to the narrative. Links Relation elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `titles` string[], nullable: Titles relevant to the narrative. Links Title elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `constructs` string[], nullable: Constructs relevant to the narrative. Links Construct elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `laws` string[], nullable: Laws relevant to the narrative. Links Law elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world. - `world` unknown - `created_by` unknown - `changed_by` unknown - `changed_via` unknown ## Response `200` Replaced: the full element. - Narrative: A narrative as the API returns it. Single links are an id or null, multi links an array of ids; extension fields appear inline. `?fields=` returns only the named keys, and `?expand=` replaces the named links' ids with ElementStub objects. - `type` 'narrative', required - `id` string, uuid, required - `name` string, required: Name of the element. - `description` string, required: Any kind of details about the element. - `supertype` string, required: The top level category to which the element belongs. - `subtype` string, required: The sub level category through which the element is further classified. - `image_url` string, required: URL to an image representing the element. - `story` string, required: Content of the narrative, as told or remembered. - `consequences` string, required: Outcomes or legacy of the narrative. - `start_date` integer, nullable, required: Date when the narrative is first told or recorded, measured in world TIME units; the span it recounts lives on its events. - `end_date` integer, nullable, required: Date when the narrative stops being told, measured in world TIME units; empty while it is still told. - `order` integer, nullable, required: Position of this narrative within a parent narrative's sequence. - `parent_narrative` string, uuid, nullable, required: Larger narrative that this narrative takes place in. A Narrative's id. - `protagonist` string, uuid, nullable, required: Primary character of the narrative. A Character's id. - `antagonist` string, uuid, nullable, required: Opposing character of the narrative. A Character's id. - `narrator` string, uuid, nullable, required: Character credited with telling or recording the narrative. A Character's id. - `conservator` string, uuid, nullable, required: Institution that preserves or curates the narrative. An Institution's id. - `events` string[], required: Events relevant to the narrative. Event ids. - `characters` string[], required: Characters relevant to the narrative. Character ids. - `objects` string[], required: Objects relevant to the narrative. Object ids. - `locations` string[], required: Locations relevant to the narrative. Location ids. - `species` string[], required: Species relevant to the narrative. Species ids. - `creatures` string[], required: Creatures relevant to the narrative. Creature ids. - `institutions` string[], required: Institutions relevant to the narrative. Institution ids. - `traits` string[], required: Traits relevant to the narrative. Trait ids. - `collectives` string[], required: Groups relevant to the narrative. Collective ids. - `zones` string[], required: Zones relevant to the narrative. Zone ids. - `abilities` string[], required: Abilities relevant to the narrative. Ability ids. - `phenomena` string[], required: Phenomena relevant to the narrative. Phenomenon ids. - `languages` string[], required: Languages relevant to the narrative. Language ids. - `families` string[], required: Families relevant to the narrative. Family ids. - `relations` string[], required: Relationships relevant to the narrative. Relation ids. - `titles` string[], required: Titles relevant to the narrative. Title ids. - `constructs` string[], required: Constructs relevant to the narrative. Construct ids. - `laws` string[], required: Laws relevant to the narrative. Law ids. - `created_at` string, date-time, required - `updated_at` string, date-time, required - `change_seq` integer, required: The world change sequence at this element's last write. - `created_by` string, uuid, nullable, required: The world membership that created this element, or null when the world's owner did. - `changed_by` string, 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_of` true: 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`, and its type's public fields (none for a narrative); 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 what it keeps. 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, whatever its public fields. Read-only: a write carrying `known_of` is refused (`known_of_not_writable`). ## Other responses - `201`: Created: the full element. - `400`: A link names an element that does not exist in this world (code invalid_link). - `401`: Missing, invalid or revoked credential, or a wrong PIN (authentication_error; code key_revoked for a revoked key, invalid_credentials otherwise). - `403`: The credential is valid but lacks the scope: a read key on a write route (permission_error). Or a contributor or guest key changed, replaced, relinked or deleted an element someone else created (code not_author); those members change only their own, and, for an agent seat the owner gave a Character, that Character (never deleting it). - `409`: The id is held by an element in another world (id_conflict). - `422`: Invalid request: unknown or read-only field, bad value, unknown query parameter, over-long text, extensions over the size cap (invalid_request); `param` names the culprit. - `429`: Too many failed PIN attempts; see the Retry-After header (rate_limited). Or too many requests: over the request budget (code too_many_requests, type rate_limited): 300 requests a minute per key or account token, 60 a minute per address for a request with neither. Retry after the Retry-After header's seconds. - `503`: The server is busy: every request slot stayed full for 10 s (code server_busy, type api_error). Retry after the Retry-After header's seconds. ## Changes - **2026-10-20** `78df39c4c62e`: 7 warning - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `400` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `401` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `403` - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `409` - …3 more - **2026-10-20** `4dd5b1cd0687`: 14 warning, 2 info - added the new `character_taken` enum value to the `error/code` response property for the response status `400` - added the new `character_taken` enum value to the `error/code` response property for the response status `401` - added the new `character_taken` enum value to the `error/code` response property for the response status `403` - added the new `character_taken` enum value to the `error/code` response property for the response status `409` - …12 more [Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/narrative/:id/put.md) --- [API](https://skmtc.dev/onlyworlds/apis/onlyworlds-api.md) · [All operations](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/revisions/1752622ae8ce?raw)