---
title: "Create or replace a character by id"
method: PUT
path: "/api/v2/character/{id}"
tags: ["Character"]
---

# Create or replace a character by id

`PUT /api/v2/character/{id}`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/character/{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

- CharacterWrite: A full character 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 ''.
  - `physicality` string, nullable: The character's visible physical features and body attributes. null stores ''.
  - `mentality` string, nullable: The character's mindset, emotional tone, and style of thinking. null stores ''.
  - `background` string, nullable: History, upbringing, or formative experiences of the character. null stores ''.
  - `motivations` string, nullable: Core desires, goals, or values that drive the character's choices and behavior. null stores ''.
  - `reputation` string, nullable: Brief summary of the character's current condition, role, or predicament. null stores ''.
  - `height` integer, nullable: The character's approximate or exact height, in the world's length unit (World length_unit).
  - `weight` integer, nullable: The character's approximate or exact weight, in the world's mass unit (World mass_unit).
  - `birth_date` integer, nullable: Moment of birth, expressed in the world's TIME units.
  - `charisma` integer, nullable: Ability to attract, inspire, and influence others.
  - `coercion` integer, nullable: Capacity to dominate, intimidate, or apply force to shape outcomes.
  - `competence` integer, nullable: Skill in planning, understanding, and managing complex systems or situations.
  - `compassion` integer, nullable: Willingness to empathize with and care for others.
  - `creativity` integer, nullable: Ability to generate novel ideas, perspectives, or solutions.
  - `courage` integer, nullable: Readiness to face danger, risk, or adversity.
  - `level` integer, nullable: Progression rank of the character in a game system.
  - `hit_points` integer, nullable: Total health available to the character.
  - `STR` integer, nullable: Physical force and carrying capacity.
  - `DEX` integer, nullable: Agility, coordination, and reflexes.
  - `CON` integer, nullable: Endurance and resistance to strain.
  - `INT` integer, nullable: Reasoning, memory, and learning.
  - `WIS` integer, nullable: Intuition, awareness, and judgment.
  - `CHA` integer, nullable: Persuasiveness and personal magnetism.
  - `birthplace` string, uuid, nullable: Location where the character was born. Links a Location: an existing one in this world.
  - `location` string, uuid, nullable: The character's present physical location. Links a Location: an existing one in this world.
  - `species` string[], nullable: Species the character might belong to. Links Species elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `traits` string[], nullable: Traits for notable behavioral, physical, or systemic characteristics. Links Trait elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `abilities` string[], nullable: Abilities the character might perform, control, or invoke. Links Ability elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `languages` string[], nullable: Languages the character can understand, speak, or use for communication. Links Language elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `objects` string[], nullable: Key objects owned by or symbolically linked to the character. Links Object elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `institutions` string[], nullable: Institutions the character is affiliated with. Links Institution elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `family` string[], nullable: Families the character belongs to by blood or adoption. Links Family elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `friends` string[], nullable: Characters the character considers close allies or companions. Links Character elements; replaces the whole list (null is the same as []). Every id must name an existing one in this world.
  - `rivals` string[], nullable: Characters the character is in active opposition or competition with. Links Character 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.

- Character: A character 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` 'character', 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.
  - `physicality` string, required: The character's visible physical features and body attributes.
  - `mentality` string, required: The character's mindset, emotional tone, and style of thinking.
  - `background` string, required: History, upbringing, or formative experiences of the character.
  - `motivations` string, required: Core desires, goals, or values that drive the character's choices and behavior.
  - `reputation` string, required: Brief summary of the character's current condition, role, or predicament.
  - `height` integer, nullable, required: The character's approximate or exact height, in the world's length unit (World length_unit).
  - `weight` integer, nullable, required: The character's approximate or exact weight, in the world's mass unit (World mass_unit).
  - `birth_date` integer, nullable, required: Moment of birth, expressed in the world's TIME units.
  - `charisma` integer, nullable, required: Ability to attract, inspire, and influence others.
  - `coercion` integer, nullable, required: Capacity to dominate, intimidate, or apply force to shape outcomes.
  - `competence` integer, nullable, required: Skill in planning, understanding, and managing complex systems or situations.
  - `compassion` integer, nullable, required: Willingness to empathize with and care for others.
  - `creativity` integer, nullable, required: Ability to generate novel ideas, perspectives, or solutions.
  - `courage` integer, nullable, required: Readiness to face danger, risk, or adversity.
  - `level` integer, nullable, required: Progression rank of the character in a game system.
  - `hit_points` integer, nullable, required: Total health available to the character.
  - `STR` integer, nullable, required: Physical force and carrying capacity.
  - `DEX` integer, nullable, required: Agility, coordination, and reflexes.
  - `CON` integer, nullable, required: Endurance and resistance to strain.
  - `INT` integer, nullable, required: Reasoning, memory, and learning.
  - `WIS` integer, nullable, required: Intuition, awareness, and judgment.
  - `CHA` integer, nullable, required: Persuasiveness and personal magnetism.
  - `birthplace` string, uuid, nullable, required: Location where the character was born. A Location's id.
  - `location` string, uuid, nullable, required: The character's present physical location. A Location's id.
  - `species` string[], required: Species the character might belong to. Species ids.
  - `traits` string[], required: Traits for notable behavioral, physical, or systemic characteristics. Trait ids.
  - `abilities` string[], required: Abilities the character might perform, control, or invoke. Ability ids.
  - `languages` string[], required: Languages the character can understand, speak, or use for communication. Language ids.
  - `objects` string[], required: Key objects owned by or symbolically linked to the character. Object ids.
  - `institutions` string[], required: Institutions the character is affiliated with. Institution ids.
  - `family` string[], required: Families the character belongs to by blood or adoption. Family ids.
  - `friends` string[], required: Characters the character considers close allies or companions. Character ids.
  - `rivals` string[], required: Characters the character is in active opposition or competition with. Character 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 (for a character: `physicality`, `height`, `weight`, `species`, `reputation`; a link among them still names only what the reader sees); 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/character/: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/78df39c4c62e?raw)