> ## 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. > ## Agent Instructions > These are Ditto's developer docs. Ditto is a single source of truth for product copy across design, review, localization, and code. > The first step on any codebase is a scan: https://developer.dittowords.com/get-started/scan-your-repo.md. That page also covers reviewing the style guide Ditto drafts from the scan. After it, the follow-on guides are Connect Figma files and Set up localization (under /guides/) and Connect the Ditto MCP (the Setup page of the MCP reference). > Two different MCP servers: the Ditto MCP server at https://api.dittowords.com/v2/mcp gives an agent a workspace's text and style guide rules; the documentation MCP server at https://developer.dittowords.com/mcp searches these docs. > Prefer logging in with a Ditto account (npx -y @dittowords/cli@latest login; OAuth in MCP clients) over API keys. API keys are for CI and headless clients only. > Commands are complete as written and use npx -y @dittowords/cli@latest; nothing needs a global install. # Upgrade component instances > Brings library component instances in projects up to date with the latest published version of their component, by the text items' Developer IDs. Instances that are already up to date are returned in `unchangedTextItemIds`. The operation is all-or-nothing: if any instance can't be upgraded due to an error condition, none are. Only available in workspaces that have opted into library component versioning. ## OpenAPI ````yaml openapi.json patch /components/upgrade 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: /components/upgrade: patch: tags: - Components summary: Upgrade component instances description: >- Brings library component instances in projects up to date with the latest published version of their component, by the text items' Developer IDs. Instances that are already up to date are returned in `unchangedTextItemIds`. The operation is all-or-nothing: if any instance can't be upgraded due to an error condition, none are. Only available in workspaces that have opted into library component versioning. requestBody: content: application/json: schema: type: object properties: textItemIds: type: array items: type: string minItems: 1 maxItems: 100 description: >- Developer IDs of the project text items to bring up to date with their library component. Each must be a library instance. projectId: type: string description: >- Developer ID of the project to scope the upgrade to. If provided, each given Developer ID must match a text item in this project, and only that text item is upgraded. Required when a Developer ID is shared by text items spawned from the same base text item in multiple projects. discardLocalEdits: type: boolean description: >- Whether to discard the local edits held by any of the text items (those in the `modified` or `conflict` state), resetting them to match their component. When omitted or false, the request fails if any text item holds local edits. required: - textItemIds additionalProperties: false example: textItemIds: - text-item-id-1 - text-item-id-2 examples: upgrade_instances: summary: Upgrade instances value: textItemIds: - text-item-id-1 - text-item-id-2 discard_local_edits: summary: Upgrade instances, discarding local edits description: >- Instances with local edits are reset to match their component's latest version instead of failing the request. value: textItemIds: - text-item-id-1 discardLocalEdits: true upgrade_scoped_to_project: summary: Upgrade a base text item's text in one project description: >- Copies of the same base text item in different projects share its Developer ID, so `projectId` picks which text to upgrade. value: textItemIds: - base-text-item-id-1 projectId: my-project-id responses: '200': description: >- Returns success status of the upgrade operation, the Developer IDs of the text items that were upgraded, and the Developer IDs of any that were already up to date content: application/json: schema: type: object properties: success: type: boolean description: Indicates whether the upgrade was successful upgradedTextItemIds: type: array items: type: string description: >- Developer IDs of the text items brought up to date with their component, in request order. Each is now `current`. unchangedTextItemIds: type: array items: type: string description: >- Developer IDs of the text items that were already `current`, in request order required: - success - upgradedTextItemIds - unchangedTextItemIds example: success: true upgradedTextItemIds: - text-item-id-1 unchangedTextItemIds: - text-item-id-2 '400': description: >- Returned when a Developer ID does not match any existing text item (or, if projectId was given, any text item in that project), the projectId does not match any existing project, a Developer ID is shared by copies of a base text item in multiple projects and projectId was not given, a text item is not linked to a library component, or a text item's link to its component is broken content: application/json: schema: type: object properties: message: type: string description: Error message describing why the request failed details: type: object description: Optional additional error details required: - message example: message: >- Text items are not linked to a library component: text-item-id-1 '404': description: >- Returned when the workspace hasn't opted into library component versioning content: application/json: schema: type: object properties: message: type: string description: Error message describing why the request failed details: type: object description: Optional additional error details required: - message example: message: This workspace hasn't opted into library component versioning '409': description: >- Returned when an instance has local edits and `discardLocalEdits` is not set, or when an instance changes while the upgrade is running content: application/json: schema: type: object properties: message: type: string description: Error message describing why the request failed modifiedTextItemIds: type: array items: type: string description: >- Developer IDs of the text items with local edits that upgrading would discard required: - message example: message: >- Text item with developer ID text-item-id-1 has local edits that upgrading would discard. Set discardLocalEdits to discard them, or update the component to match first. modifiedTextItemIds: - text-item-id-1 security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.