> ## Documentation Index > Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt > Use this file to discover all available pages before exploring further. # Update variants > Updates one or more variants in the workspace, identified by their current developer IDs. A variant's name and its developer ID are independent. The name is the human-readable label shown in Ditto; the developer ID is the stable key that code, integrations, and CLI output use to refer to the variant. Renaming a variant leaves its developer ID untouched, so anything already referencing it keeps resolving — set newDeveloperId only when you want that key itself to change. Nothing inside Ditto is orphaned or rewritten by either change: text items and library components reference a variant by an internal id rather than its developer ID, so each keeps its text for the variant, and variant-scoped style guides stay attached. What breaks is outside Ditto — anything naming the old developer ID, such as CLI output, an integration config, or code, along with later API and MCP calls, which have to use the new one. At most one variant in a workspace can hold a given locale code; pass null to clear one. Changing a locale code reaches past the variant itself: variant-scoped style guides and AI translation targeting both resolve a locale to a variant, so moving a locale onto a different variant changes which style guide governs that locale's text and where translated text is suggested. The whole batch is rejected if any update is invalid. ## OpenAPI ````yaml openapi.json patch /variants openapi: 3.0.0 info: version: 1.0.0 title: Ditto API description: Programmatically read and write data in your Ditto workspace. servers: - url: https://api.dittowords.com/v2 security: [] paths: /variants: patch: tags: - Variants summary: Update variants description: >- Updates one or more variants in the workspace, identified by their current developer IDs. A variant's name and its developer ID are independent. The name is the human-readable label shown in Ditto; the developer ID is the stable key that code, integrations, and CLI output use to refer to the variant. Renaming a variant leaves its developer ID untouched, so anything already referencing it keeps resolving — set newDeveloperId only when you want that key itself to change. Nothing inside Ditto is orphaned or rewritten by either change: text items and library components reference a variant by an internal id rather than its developer ID, so each keeps its text for the variant, and variant-scoped style guides stay attached. What breaks is outside Ditto — anything naming the old developer ID, such as CLI output, an integration config, or code, along with later API and MCP calls, which have to use the new one. At most one variant in a workspace can hold a given locale code; pass null to clear one. Changing a locale code reaches past the variant itself: variant-scoped style guides and AI translation targeting both resolve a locale to a variant, so moving a locale onto a different variant changes which style guide governs that locale's text and where translated text is suggested. The whole batch is rejected if any update is invalid. requestBody: content: application/json: schema: type: object properties: updates: type: array items: type: object properties: developerId: type: string description: The variant's current developer ID name: type: string minLength: 1 description: >- New name for the variant. If not provided, the name is unchanged. newDeveloperId: type: string minLength: 1 description: >- A new developer ID for this variant. Must be unique within the workspace, and is accepted in any casing and stored lowercase. Renaming a variant does not change its developer ID, so set this only when the key used to refer to the variant should change too. No text is lost or orphaned: text items and library components reference a variant by an internal id, not its developer ID. What has to be updated to match is outside Ditto — CLI output, integration configs, and code naming the old developer ID. Can be set alongside other field changes in the same update object. description: type: string description: >- New description for the variant. Pass an empty string to clear it. If not provided, unchanged. localeCode: type: string nullable: true enum: - af - ar - ar-ae - ar-bh - ar-dz - ar-eg - ar-iq - ar-jo - ar-kw - ar-lb - ar-ly - ar-ma - ar-om - ar-qa - ar-sa - ar-sy - ar-tn - ar-ye - az - be - bg - bs - ca - cs - cy - da - de - de-at - de-ch - de-li - de-lu - el - en - en-au - en-bz - en-ca - en-gb - en-ie - en-jm - en-nz - en-sg - en-tt - en-us - en-za - es - es-ar - es-bo - es-cl - es-co - es-cr - es-do - es-ec - es-gt - es-hn - es-mx - es-ni - es-pa - es-pe - es-pr - es-py - es-sv - es-uy - es-ve - et - eu - fa - fi - fo - fr - fr-be - fr-ca - fr-ch - fr-lu - ga - gd - he - hi - hr - hu - hy - id - is - it - it-ch - ja - ka - kk - ko - ku - lt - lv - mk - ml - ms - mt - nb - nl - nl-be - nn - 'no' - pa - pl - pt - pt-br - rm - ro - ro-md - ru - ru-md - sk - sl - sq - sr - sv - sv-fi - th - tn - tr - ts - uk - ur - ve - vi - wen - xh - yi - zh-cn - zh-hk - zh-sg - zh-tw - zu - null description: >- Locale code for the variant, from the set Ditto supports. Casing does not matter on the way in — 'fr-CA' and 'fr-ca' are both accepted — and the code is stored lowercase, which is the form reads return. Not every language-region pairing exists in the set, so pick one of the listed values rather than composing your own. At most one variant per workspace can hold a given locale code. Set this whenever the variant represents a language: translation tools treat it as the authoritative target locale. Moving a locale onto a different variant re-points the variant-scoped style guides and AI translation targeting that resolve a locale to a variant. Pass null to clear it. If not provided, unchanged. required: - developerId minItems: 1 description: Array of updates to variants required: - updates example: updates: - developerId: spanish description: Spanish translations for Mexico localeCode: es-mx - developerId: fr-ca name: French (Canada) newDeveloperId: french-canada responses: '200': description: Returns success status of the update operation content: application/json: schema: type: object properties: success: type: boolean description: Indicates whether the update was successful required: - success example: success: true '400': description: >- Returned when the request body fails validation. Common causes include: an update that changes nothing; the same value being claimed by two updates in one request; a reserved developer ID. content: application/json: schema: type: object properties: message: type: string description: Error message describing the validation failure required: - message example: message: 'Duplicate new developer IDs in request: french-canada' '404': description: >- Returned when a developer ID does not match any existing variant in the workspace content: application/json: schema: type: object properties: message: type: string description: Error message describing the validation failure required: - message example: message: 'Variants not found: spanish' '409': description: >- Returned when a name, developer ID, or locale code an update claims is already held by another variant in the workspace content: application/json: schema: type: object properties: message: type: string description: Error message describing the conflict required: - message example: message: >- Couldn't update variant "spanish": Variant with same name already exists! security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ````