# Ditto

> Developer documentation for Ditto, the source of truth for product text. Scan a codebase to import its strings, then connect coding agents through the Ditto MCP server, link Figma files, and pull localized string files with the CLI.

> ## 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.

- [Ditto developer documentation](https://developer.dittowords.com/introduction.md): Ditto is a single source of truth for product copy across design, review, localization, and code. Start by bringing in the strings from your codebase.
- [Scan your repo](https://developer.dittowords.com/get-started/scan-your-repo.md): Bring in your product's existing strings with one command. Once they're in, you can search, audit, and reuse the text from your live product.
- [Connect Figma files](https://developer.dittowords.com/guides/connect-figma-files.md): Link your Figma file to a Ditto project from your editor: your agent matches text layers to the strings from your codebase, links them, and organizes them.
- [Set up localization](https://developer.dittowords.com/guides/set-up-localization.md): Manage and automate localization in Ditto: add locales as variants, translate with AI, preview in design, and bring localized string files to code.
- [Key concepts](https://developer.dittowords.com/concepts.md): Definitions for Ditto's data model: projects, text items, library components, component versioning, developer IDs, style guides, variants, variables, plurals, and scans.
- [Install and log in to the Ditto CLI](https://developer.dittowords.com/cli-reference/authentication.md): Install the Ditto CLI and log in with your Ditto account so you can scan a codebase and pull string files.
- [Ditto CLI commands](https://developer.dittowords.com/cli-reference/commands.md): Reference for every Ditto CLI command and its options.
- [Ditto CLI configuration](https://developer.dittowords.com/cli-reference/configuration.md): Setting what text and formats the CLI pulls down
- [Ditto CLI output files](https://developer.dittowords.com/cli-reference/files.md): The file structure of text pulled down via the CLI
- [Ditto API authentication](https://developer.dittowords.com/api-reference/authentication.md): Create a Ditto API key and pass it in the Authorization header. Covers the token format, key management, and how the CLI and MCP log in instead.
- [Fetch activity](https://developer.dittowords.com/api-reference/activity/get-activity.md): Returns a paginated list of activity items (change events) in your workspace, optionally filtered by project, text item, library component, or entity type.
- [Fetch components](https://developer.dittowords.com/api-reference/components/get-components.md): Returns a list of components in your workspace.
- [Export components](https://developer.dittowords.com/api-reference/components/export-components.md): Returns components in your workspace in the provided format.
- [Create components](https://developer.dittowords.com/api-reference/components/create-components.md): Creates one or more library components in your workspace.
- [Update components](https://developer.dittowords.com/api-reference/components/patch-components.md): Updates a set of components' base or variant text, plural forms, tags, status, assignee, notes, character limit, integrated, and variables.
- [Delete components](https://developer.dittowords.com/api-reference/components/delete-components.md): Deletes library components from the workspace by their developer IDs.
- [Publish a text item to the library](https://developer.dittowords.com/api-reference/components/publish-component.md): Publishes an existing project text item to the component library, turning it into a reusable library component.
- [Link text items to a component](https://developer.dittowords.com/api-reference/components/link-components.md): Links one or more existing text items to an existing library component by developer ID, so they share the component's text going forward.
- [Unlink text items from a component](https://developer.dittowords.com/api-reference/components/unlink-components.md): Unlinks one or more text items from their library component by developer ID.
- [Fetch unpublished component changes](https://developer.dittowords.com/api-reference/components/get-unpublished-component-changes.md): Returns the components in your workspace that have unpublished changes, with those changes applied.
- [Save unpublished component changes](https://developer.dittowords.com/api-reference/components/save-unpublished-component-changes.md): Saves changes to library components without publishing them. The changes are not available to instances until they're published.
- [Discard unpublished component changes](https://developer.dittowords.com/api-reference/components/discard-unpublished-component-changes.md): Discards the unpublished changes on library components by their Developer IDs. The components' published values, versions, and instances are unchanged. Components with no unpublished changes are left as they are and returned in `skippedIds`.
- [Publish component changes](https://developer.dittowords.com/api-reference/components/publish-component-changes.md): Publishes the unpublished changes on library components by their Developer IDs. Components with no unpublished changes are left as they are and returned in `skippedIds`.
- [Upgrade component instances](https://developer.dittowords.com/api-reference/components/upgrade-component-instances.md): 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…
- [Fetch component folders](https://developer.dittowords.com/api-reference/component-folders/get-component-folders.md): Returns all folders in your component library, with their developer IDs, names, and parent folder (by developer ID; null when the folder sits directly under the library root).
- [Create component folders](https://developer.dittowords.com/api-reference/component-folders/create-component-folders.md): Creates one or more folders in the component library.
- [Update component folders](https://developer.dittowords.com/api-reference/component-folders/patch-component-folders.md): Updates a set of component folders.
- [Delete component folders](https://developer.dittowords.com/api-reference/component-folders/delete-component-folders.md): Deletes folders from the component library.
- [Fetch projects](https://developer.dittowords.com/api-reference/projects/get-projects.md): Returns a list of Ditto projects in your workspace.
- [Create a project](https://developer.dittowords.com/api-reference/projects/create-projects.md): Creates a new Ditto project in your workspace.
- [Update a project](https://developer.dittowords.com/api-reference/projects/patch-projects.md): Updates a project's name, Developer ID, and/or connected base.
- [Fetch project blocks](https://developer.dittowords.com/api-reference/project-blocks/get-project-blocks.md): Returns the blocks in a Ditto project, in display order.
- [Create project blocks](https://developer.dittowords.com/api-reference/project-blocks/create-project-blocks.md): Creates one or more blocks in a Ditto project.
- [Update project blocks](https://developer.dittowords.com/api-reference/project-blocks/patch-project-blocks.md): Updates a set of blocks in a Ditto project.
- [Delete project blocks](https://developer.dittowords.com/api-reference/project-blocks/delete-project-blocks.md): Deletes blocks from a Ditto project.
- [Fetch statuses](https://developer.dittowords.com/api-reference/statuses/get-statuses.md): Returns the statuses which text items and library components in the workspace can be set to, in workflow order — from earliest (a first draft) to latest (ready to ship).
- [Get style guides](https://developer.dittowords.com/api-reference/styleguides/get-styleguides.md): Returns the style guides created in the workspace, with their sections and rules.
- [Create a style guide](https://developer.dittowords.com/api-reference/styleguides/create-styleguides.md): Creates a new style guide in your workspace.
- [Update a style guide](https://developer.dittowords.com/api-reference/styleguides/patch-styleguides.md): Updates a style guide's name, description, enabled-by-default setting, or sections.
- [Create style guide rules](https://developer.dittowords.com/api-reference/styleguides/create-styleguide-rules.md): Creates one or more rules in a style guide section.
- [Update style guide rules](https://developer.dittowords.com/api-reference/styleguides/patch-styleguide-rules.md): Updates a set of style guide rules, each identified by its Developer ID.
- [Delete style guide rules](https://developer.dittowords.com/api-reference/styleguides/delete-styleguide-rules.md): Deletes style guide rules by their Developer IDs.
- [Fetch text items](https://developer.dittowords.com/api-reference/text-items/get-text-items.md): Returns a list of text items in your workspace.
- [Export text items](https://developer.dittowords.com/api-reference/text-items/export-text-items.md): Returns text items in your workspace in the desired export format.
- [Create text items](https://developer.dittowords.com/api-reference/text-items/create-text-items.md): Creates a set of text items in a project.
- [Update text items](https://developer.dittowords.com/api-reference/text-items/patch-text-items.md): Updates a set of text items' base or variant text, plural forms, tags, status, assignee, notes, character limit, integrated, variables, and block placement.
- [Update text items](https://developer.dittowords.com/api-reference/text-items/update-text-items.md): Updates a set of text items' base or variant text, tags, status, assignee, and plural forms.
- [Delete text items](https://developer.dittowords.com/api-reference/text-items/delete-text-items.md): Deletes text items by their developer IDs.
- [Link Figma nodes to text items](https://developer.dittowords.com/api-reference/text-items/link-figma-nodes.md): Links Figma text nodes to existing text items in a Figma-linked project, so those nodes become Figma instances of their text items. Takes a mapping of text item developer IDs to Figma node IDs.
- [Fetch variables](https://developer.dittowords.com/api-reference/variables/get-variables.md): Returns a list of the variables in the workspace.
- [Create variables](https://developer.dittowords.com/api-reference/variables/create-variables.md): Creates variables in your workspace.
- [Update variables](https://developer.dittowords.com/api-reference/variables/patch-variables.md): Renames variables or changes their type or value.
- [Delete variables](https://developer.dittowords.com/api-reference/variables/delete-variables.md): Permanently deletes variables from your workspace.
- [Fetch variants](https://developer.dittowords.com/api-reference/variants/get-variants.md): Returns a list of the variants in the workspace.
- [Create variants](https://developer.dittowords.com/api-reference/variants/create-variants.md): Creates one or more variants in the workspace.
- [Update variants](https://developer.dittowords.com/api-reference/variants/patch-variants.md): Updates one or more variants in the workspace, identified by their current developer IDs.
- [Delete variants](https://developer.dittowords.com/api-reference/variants/delete-variants.md): Deletes variants from the workspace by their developer IDs. This can't be undone.
- [JSON](https://developer.dittowords.com/string-formats/json.md): JSON string formats Ditto exports via the API and CLI: flat, structured, nested, ICU, and ARB, with plurals, variables, and variant metadata.
- [iOS string formats](https://developer.dittowords.com/string-formats/ios.md): The .strings and .stringsdict formats Ditto exports for iOS via the API and CLI, including variable placeholders, plurals, and variant metadata.
- [Android XML string format](https://developer.dittowords.com/string-formats/android.md): The strings.xml resource format Ditto exports for Android via the API and CLI, including xliff variables, plurals, and variant metadata.
- [Ditto MCP server overview](https://developer.dittowords.com/mcp-reference/overview.md): The Ditto MCP (Model Context Protocol) server connects AI coding agents to your team's product text in Ditto.
- [Connect the Ditto MCP](https://developer.dittowords.com/guides/connect-the-mcp.md): Connect Claude Code, Cursor, Codex, VS Code, Windsurf, or Figma Make to Ditto with your Ditto login so agents follow your style guide and reuse text.
- [Ditto MCP tools](https://developer.dittowords.com/mcp-reference/tools.md): Available tools in the Ditto MCP server
- [Agent instructions](https://developer.dittowords.com/guides/agent-instructions.md): The CLAUDE.md / AGENTS.md block that makes a coding agent check Ditto before writing copy, plus example prompts and the MCP tools each one triggers.
- [Ditto Specs overview](https://developer.dittowords.com/ditto-specs-cli-reference/overview.md): Ditto spec files put your style guide rules next to your design system components, so agents get the rules that apply to each element.
- [Ditto Specs CLI setup](https://developer.dittowords.com/ditto-specs-cli-reference/setup.md): Install the Specs CLI, configure your project, and set up API keys and agent integration
- [Ditto Specs CLI commands](https://developer.dittowords.com/ditto-specs-cli-reference/commands.md): All commands available in the Ditto Specs CLI
- [Ditto Spec Files](https://developer.dittowords.com/ditto-specs-cli-reference/spec-files.md): Format and structure of .ditto.md Ditto spec files for workspaces and components
- [Ditto Specs agent skills](https://developer.dittowords.com/ditto-specs-cli-reference/agent-skills.md): Interactive agent workflows for scaffolding Ditto specs, auditing text, and finding style guide rule gaps
- [GitHub PR Review Bot](https://developer.dittowords.com/additional-tools/github-pr-review-bot.md): Automatically review pull requests for style guide violations and text re-use suggestions
- [Webhooks](https://developer.dittowords.com/additional-tools/webhooks.md): Webhooks enable HTTP payloads to be sent to an external service when data in Ditto is changed.
- [GitHub Action](https://developer.dittowords.com/additional-tools/gh-action.md): Automatically create pull requests with the latest text updates
- [Legacy API authentication](https://developer.dittowords.com/legacy/api-reference-legacy/authentication.md): Authenticate requests to the legacy (v1) Ditto API with an API key in the Authorization header.
- [Fetch component text](https://developer.dittowords.com/legacy/api-reference-legacy/components/fetch-component-text.md): Returns the components in the workspace of the requesting user. Only component libraries with Developer Mode enabled can be fetched.
- [Import components via a file](https://developer.dittowords.com/legacy/api-reference-legacy/components/import-components-via-a-file.md): For more information about importing components via a file please see: https://dittov3.notion.site/Importing-JSON-iOS-Android-Files-256cc8865c7a80fe94cdf135631bf8c6. The request body must be of type multipart/form-data.
- [Update component text variant](https://developer.dittowords.com/legacy/api-reference-legacy/components/update-component-text-variant.md): Used for updating the text and status fields for components in the workspace of the requesting user.
- [Fetch component folders](https://developer.dittowords.com/legacy/api-reference-legacy/components-folders/fetch-component-folders.md): Returns an object of component folders in the requesting user's workspace.
- [Fetch component text by component folder](https://developer.dittowords.com/legacy/api-reference-legacy/components-folders/fetch-component-text-by-component-folder.md): Returns the components in the specified folder. Format is identical to the format used by the Fetch components endpoint.
- [Fetch component text by project id](https://developer.dittowords.com/legacy/api-reference-legacy/projects/fetch-component-text-by-project-id.md): Returns the components used in the specified project. Format is identical to the format used by the Fetch components endpoint.
- [Fetch projects](https://developer.dittowords.com/legacy/api-reference-legacy/projects/fetch-projects.md): Returns a list of Ditto projects. Only projects with Developer Mode enabled can be fetched.
- [Fetch text by project id](https://developer.dittowords.com/legacy/api-reference-legacy/projects/fetch-text-by-project-id.md): Returns the contents of the Ditto project referred to by :id. You can find the id of a Ditto project from its URL: https://app.dittowords.com/doc/:id. Only projects with Developer Mode enabled can be fetched.
- [Fetch project folders](https://developer.dittowords.com/legacy/api-reference-legacy/project-folders/fetch-project-folders.md): Returns a list of project folders in the workspace of the requesting user.
- [Fetch projects by project folder id](https://developer.dittowords.com/legacy/api-reference-legacy/project-folders/fetch-projects-by-project-folder-id.md): Returns a list of projects in the specified project folder.
- [Fetch variables](https://developer.dittowords.com/legacy/api-reference-legacy/variables/fetch-variables.md): Returns the variables in the workspace of the requesting user.
- [Fetch variants](https://developer.dittowords.com/legacy/api-reference-legacy/variants/fetch-variants.md): Returns a list of variants in the workspace of the requesting user.
- [Legacy CLI installation](https://developer.dittowords.com/legacy/cli-reference-legacy/authentication.md): Installation and authentication of the Ditto CLI
- [Legacy CLI configuration](https://developer.dittowords.com/legacy/cli-reference-legacy/configuration.md): Setting what text and formats the CLI pulls down
- [Legacy CLI output files](https://developer.dittowords.com/legacy/cli-reference-legacy/files.md): The file structure of text pulled down via the CLI
- [Legacy tools](https://developer.dittowords.com/legacy/legacy-tools.md): The legacy CLI mode, the Ditto React SDK, the VS Code extension, and legacy webhook events, with the current tools that replace each one.
- [Example apps](https://developer.dittowords.com/example-apps.md): Reference apps that connect the DittoPay sample project to React, iOS, and Android to show Ditto's string files, developer IDs, and variants in a working app.
- [Feedback & Support](https://developer.dittowords.com/feedback-support/feedback-support.md): Where to report issues and ask questions about the Ditto CLI, API, MCP server, React SDK, and GitHub Action.
- [Developer changelog](https://developer.dittowords.com/feedback-support/changelog.md): Release notes for the Ditto API, CLI, MCP server, GitHub Action, and React SDK, newest first.

## OpenAPI Specs

- [openapi-legacy](/openapi-legacy.json)
- [openapi](/openapi.json)

## Optional

- [Help Guides](https://help.dittowords.com/en/)
- [What's New](https://www.dittowords.com/whats-new)
- [Figma Plugin](https://www.figma.com/community/plugin/798826066406007173/ditto-manage-copy-from-design-to-production)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.