Developer changelog

October 30, 2026

API

Several updates to the API have been made to support working with Bases. This is a brand new feature that is still in development. Attempting to use any of these endpoints while the feature is in development will throw an error. A release announcement will be published here when the feature is available to all users. Brand new endpoints related to working with Bases:

Fetch bases (GET /v2/bases) — lists all the bases in your workspace, including each base’s GitHub connection.
Fetch a base (GET /v2/bases/{baseId}) — returns a single base, with its text item count, its folders and the projects connected to it.
Create bases (POST /v2/bases) — creates one or more bases. Supports linking new bases to a GitHub repository, which also kicks off an initial scan.
Update a base (PATCH /v2/bases/{baseId}) — edit an individual base. Currently supports name, developer ID and connecting to a GitHub repository.
Create text items from a base (POST /v2/textItems/fromBase) — copies text items from a base into a project connected to that base, optionally placing them in a new or existing block.
Publish to base (POST /v2/projects/{projectId}/publish) — publishes a project’s Modified and New text items to its base, either all of them or the ones you name. Text items in Conflict are only acted on when you choose which version to keep.
Update text items from base (POST /v2/projects/{projectId}/updateFromBase) — updates Outdated or Conflict text items in a project to their base’s version.

The following existing endpoints now include support for Bases:

Fetch text items (GET /v2/textItems) - Optional bases filter to retrieve Base Text Items. Project Text Items now include nullable baseId and baseTextItemId fields.
Export text items (GET /v2/textItems/export) - Optional bases filter to retrieve Base Text Items. If the same text item appears in a fetched project and base, the project’s value overrides the base’s.
Update text items (PUT /v2/textItems) - Takes an optional projectId parameter on each text item to update, to disambiguate between the same base text item appearing in multiple projects.
Delete text items (DELETE /v2/textItems) - Takes an optional projectId parameter to disambiguate between text items that are connected to the same library component or base text item.
Fetch projects (GET /v2/projects) - Added baseId to each project in the response.
Create project (POST /v2/projects) - Added optional baseId field to support creating a project from a base.

October 29, 2026

Ditto React — 1.6.4

Maintenance release to resolve security vulnerabilities in DOMPurify. Release Notes. Legacy customers using the React SDK should upgrade to the latest version. If you cannot upgrade ditto-react, you may also pin the DOMPurify version to ^3.4.17 to resolve the security vulnerabilities without upgrading the Ditto SDK directly.

October 21, 2026

API

Delete Text Items (DELETE /v2/textItems) now optionally accepts a projectId to disambiguate Developer IDs that match multiple project text items. A Developer ID could match multiple project text items if it is the ID of a library component or base text item. Provide a projectId to specify which individual text item to delete, while leaving all other instances unchanged. The projectId should sufficiently disambiguate as long as there are not multiple instances of the same library component in that project. In that case, you must delete the target instance(s) through Ditto app. Prior to this change, deletion of library component instances was not supported at all through this endpoint.

MCP

delete_text_items now optionally accepts a projectId to disambiguate Developer Ids that match multiple project text items. Follows the same patterns as the API endpoint.

October 20, 2026

Library component versioning

For workspaces that have opted into library component versioning, adds endpoints for saving component changes without publishing them, publishing or discarding those changes, and bringing instances up to date. In workspaces that haven’t opted in, these endpoints return a 404.

Fetch unpublished component changes (GET /v2/components/staged): returns the components that have unpublished changes, with those changes applied. Takes the same filter and richText parameters as Fetch components.
Save unpublished component changes (PATCH /v2/components/staged): saves changes to text, plurals, tags, notes, or characterLimit without making them available to instances.
Publish component changes (POST /v2/components/staged/publish): publishes the unpublished changes, allowing component instances to adopt those changes.
Discard unpublished component changes (DELETE /v2/components/staged): discards the unpublished changes, leaving the published component and its instances unchanged.
Upgrade component instances (PATCH /v2/components/upgrade): brings text items that are instances of a component up to date with its latest published version. Instances with local edits return a 409 unless discardLocalEdits is set.

In these workspaces, existing endpoints also include versioning details:

Fetch components (GET /v2/components): each component includes hasUnpublishedChanges.
Update components (PATCH /v2/components): can’t update text, plurals, tags, notes, or characterLimit on a component with unpublished changes, since publishing those changes would overwrite the updates.
Fetch text items (GET /v2/textItems): each text item includes component, with the component’s id and the instance’s state: current, outdated, modified, or conflict. It’s null for text items that aren’t instances.

October 19, 2026

API

Link Figma nodes (POST /v2/textItems/linkFigmaNodes) now supports linking Figma text nodes to many text items in one request. Request body now takes links, a mapping of text item developer IDs to Figma node IDs. Up to 500 distinct node IDs are allowed per request across all links. Reports whether linking was successful for each node in request.

The previous request body (textItemId with figma.nodeIds) is no longer accepted. Send one links entry to link nodes to a single text item.

Omitting branchId always targets linking nodes in the main Figma file. To link nodes in a branch, pass its ID explicitly in the top-level branchId field.

MCP

Add the update_project tool, which supports updating an individual project’s name, Developer ID, and/or connected base. More details on bases and connecting projects to bases coming soon! Add the link_figma_nodes_to_text_items tool for linking Figma text nodes to many text items in one call. It takes a mapping of text item developer IDs to Figma node IDs, up to 500 node IDs per call, and returns a count per outcome plus the nodes that did not link.

The link_figma_nodes_to_text_item tool has been removed. Use link_figma_nodes_to_text_items with a single entry in links to link nodes to one text item.

Omitting branchId always targets linking nodes in the main Figma file. To link nodes in a branch, pass its ID explicitly in the top-level branchId field.

Ditto CLI - 5.12.0

v5.12.0 released. Bumps @dittowords/text-extract to 0.4.1. The scan command now reports files.skipped_too_large in the extract summary. This count covers files larger than 1 MB, which are not scanned.

October 16, 2026

API

Adds a new endpoint: Update Project (PATCH /v2/projects/{projectId}) with support for changing the name or developerId of a project, as well as connecting to or disconnecting from a base (new feature coming soon!).

October 15, 2026

API

Filter text items by component

Adds a components filter to Fetch text items (GET /v2/textItems) that returns only the text items that are instances of the given library components.

Readable validation errors

When a request doesn’t match an endpoint’s request schema, the 400 response now has a readable message that names each invalid field and why it’s invalid. The invalid fields are also listed in details.errors, each with its location in the request (body, query, or params), its path, and a message. Previously, these responses returned the raw output of our validation library as an array. Affected endpoints: all /v2 endpoints. Legacy endpoints are unchanged.

October 12, 2026

API

Released several bugfixes and standardization measures across the Text Item and Component fetch and export endpoints.

New JSON metadata parameters

Adds two new optional parameters for JSON exports:

excludeVariantMetadata?: boolean. By default, all three JSON exports include the following fields at the bottom of each variant file: __variant-name and __variant-description. You can now set this query param to true to omit these two fields. Applies to the following formats: json_icu, json_i18next, json_vue_i18n. Ignored for base text (non-variant) exports or any other formats.
includeVariableSummary?: boolean. If true, will add a __variables_used field to the bottom of the exported file, which will contain an alphabetical list (array) of the names of all the variables that are present in the export. If omitted or set to false, this field will not be added to the file. Applies to the following formats: json_i18next, json_vue_i18n. Ignored for any other formats.

Affected endpoints:

Export text items (GET /v2/textItems/export)
Export components (GET /v2/components/export)

Empty text is now included in exports

Text items and components with empty text are now included in every export format, instead of being left out. This applies to empty base text, empty variant text, and empty plural forms; the behavior change primarily affects empty variants. Items that don’t have the requested variant at all are still left out of that variant’s export. Because these keys used to be missing, most localization libraries fell back to either the base text or to the key itself. Now that they’re included with an empty value, your app will render them as empty.

This is a behavior change for plaintext exports that contain empty text. If a variant’s text is empty by mistake, your app will now show it as empty instead of falling back to the base text. Fill in the variant’s text, or remove the variant from that text item or component to continue rendering base text.

Format-specific details:

json_vue_i18n: An empty plural form is written as the literal {''}, and a plural form that contains only whitespace is written as a literal that keeps it, such as {' '}. vue-i18n can’t compile a plural message with an empty choice, so plural messages with an empty form previously caused an error when they were rendered.
json_icu and arb: Plural messages are now included when their first form is empty. Previously, the whole message was left out, even if its other forms had text. FormatJS (react-intl) treats an empty message as missing by default; set fallbackOnEmptyString: false to render it as empty.
android: Empty strings and plural forms are written as self-closing elements, such as <string name="welcome"/>. This also fixes malformed XML in exports that contained an empty plural form.

Affected endpoints:

Export text items (GET /v2/textItems/export)
Export components (GET /v2/components/export)

Consistent `html` and `html_paragraphs` rich text output

Standardizes the html rich text outputs across all four related endpoints. richText="html_paragraphs" wraps all text in  tags, while richText="html" does not wrap its content in outer tags, and uses   for line breaks. All other html generation is identical between the two formats. Affected endpoints:

Fetch text items (GET /v2/textItems)
Export text items (GET /v2/textItems/export)
Fetch components (GET /v2/components)
Export components (GET /v2/components/export)

Prior to this change, the html parameter returned the unwrapped text from the Fetch endpoints, and the paragraph-wrapped text from the Export endpoints. Now, all four endpoints return the same output format for each richText option.

This is a behavior change for the Export endpoints. To continue receiving identical output, you must switch from html to html_paragraphs.

The Create and Update endpoints are unaffected by this change. They still maintain a single html rich text option, which can convert either paragraph format into Ditto rich text. Example: For a text item with two paragraphs:

Welcome back!
Your order has shipped.

richText=html returns:

<strong>Welcome back!</strong><br />Your order has shipped.

richText=html_paragraphs returns:

<p><strong>Welcome back!</strong></p>
<p>Your order has shipped.</p>

Variant notes in `arb` and `ios-strings` exports

Variant exports now use the variant’s own notes as each string’s description in arb, and as the comment above each string in ios-strings. If a variant has no notes, its base notes are used instead. Base exports are unchanged. Previously, both formats always used the base notes, even in variant exports. Affected endpoints:

Export text items (GET /v2/textItems/export)
Export components (GET /v2/components/export)

Ditto CLI - 5.11.0

Updates the CLI to support the new html_paragraphs rich text parameter. Prior to the API changes, the CLI used unwrapped html for the plain JSON export and the JSON export with i18next and vue-i18n frameworks. All other formats (including json_icu) returned the html_paragraphs style. The API changes mentioned above affect all CLI versions immediately. If you were using one of the other formats with rich text, and want to continue exporting with the legacy format, you will need to upgrade to this CLI version and change your config file from richText: html to richText: html_paragraphs. Additionally, this version includes the following bug fixes:

Generates plurals correctly for format: json, framework: vue-i18n, as returned from the Export endpoints.
Respects the integrated filter for components fetches. Previously, it was only applied to text items.

October 7, 2026

API

Add newDeveloperId to Update a style guide (PATCH /v2/styleguides) for renaming a style guide’s developer ID. It can be set alongside other field changes in the same request, and must be unique among the workspace’s style guides.

MCP

Add newDeveloperId to the update_styleguide tool for renaming a style guide’s developer ID. It can be combined with other field changes in the same call.

October 5, 2026

API

Improvements to plural exports for json formats.

json_i18next Now returns the unsuffixed key alongside all plural keys. This brings it in line with what the CLI exports for json and json + i18next.
json_vue_i18n Resolves a minor bug in how plurals were generated if you had a zero and other form defined but not a one form. This format still drops two, few, and many forms, which are not supported by Vue without a custom rule definition. This change is not yet reflected in the CLI.

This affects the following endpoints:

Export text items (GET /v2/textItems/export)
Export components (GET /v2/components/export)

October 1, 2026

MCP

Add the translate_text_items tool for translating project text items into a variant’s locale, applying any style guide scoped to that locale. Add the translate_library_components tool for translating library components into a variant’s locale, applying any style guide scoped to that locale.

September 17, 2026

Ditto CLI - 5.10.0

scan now requires a clean checkout of your repository’s default branch. Scanning from a tree with uncommitted changes, from a non-default branch, or from a detached HEAD stops with a message explaining what to change, before anything is uploaded. Scan records the commit and branch it read, and the code links Ditto builds point at them. A scan taken from anywhere else describes lines your default branch never had, so a later scan reports those links as changed or removed when nothing actually changed. The default branch comes from origin/HEAD, falling back to a local main or master. Because that reference is set when you clone and doesn’t update on its own, a mismatch is confirmed against your remote first, so a branch renamed after you cloned won’t block you. Scanning outside a Git repository is unaffected.

September 3, 2026

API

Add Publish component (POST /v2/components/publish) endpoint for publishing an existing text item to the component library. Add Link components (PATCH /v2/components/link) endpoint for linking text items to a library component by developer ID. Add Unlink components endpoint, which unlinks every text item that currently shares a given developer ID with its sibling instances. Accepts an optional projectId to scope the unlink to a single project.

MCP

Add the publish_library_component for publishing an existing text item to the component library. Add the link_text_items_to_component for linking text items to a library component by developer ID. Add the unlink_text_items_from_component tool, which unlinks every text item that currently shares a given developer ID with its sibling instances. Accepts an optional projectId to scope the unlink to a single project.

September 2, 2026

API

Add Link Figma nodes (POST /v2/textItems/linkFigmaNodes) endpoint for linking already-synced Figma text nodes to an existing text item, up to 50 node IDs per request.

MCP

Add the link_figma_nodes_to_text_item tool for linking already-synced Figma text nodes to an existing text item. Replaced by link_figma_nodes_to_text_items. Add figma to the search_ditto_text fields parameter, returning the Figma text node IDs linked to each text item.

August 27, 2026

API

Add ARB as an export format for Export text items (GET /v2/textItems/export) and Export components (GET /v2/components/export) — provide ?format=arb. See ARB JSON for the content shape.

Ditto CLI - 5.9.0

Add framework: arb and framework: icu for json-format outputs, generating ARB and ICU JSON respectively. See Frameworks. Add androidLocales, which maps Ditto variant IDs to Android locale-qualified resource directories (values-<locale>/) — the Android counterpart to iosLocales. Unlike iosLocales, there’s no need to map base, since Android already has a default resource directory (values/) that the platform falls back to automatically. Add androidLocalesOutDir and iosLocalesOutDir, which let Android and iOS locale-organized output be written to separate root directories — useful since they typically need to live in different parts of a codebase.

August 24, 2026

Ditto CLI - 5.8.1

scan now records which part of your repository it looked at, alongside the Git context added in 5.8.0. Scanning a repository root is recorded as covering the whole repository; scanning a single directory is recorded as covering only that directory. This lets Ditto tell the difference between a string removed from your code and a string that simply was not part of the scan, so re-scanning one directory implies nothing about the rest of the repository.

August 20, 2026

Ditto CLI - 5.8.0

scan now records the Git repository, commit, and branch of the code it scans. Ditto uses these to recognize a codebase it has already seen, so a later scan of the same repository can be matched against an earlier one instead of importing every string again. This is read from your local Git checkout. Scan makes no additional network requests, does not send Git credentials, and records nothing about your remote beyond its host and path. Scanning outside a Git repository still works — the CLI notes that the scan can be imported but not re-synced, and continues.

August 18, 2026

Ditto CLI - 5.7.2

Move scan text extraction into the shared @dittowords/text-extract library. Extraction behavior is unchanged.

August 17, 2026

API

Add richText parameter to Create components (POST /v2/components) and Patch components (PATCH /v2/components). When richText param is set to html, all text values in the update request — including plural and variant text — will be parsed as an HTML string and saved as rich text.

August 13, 2026

Ditto CLI - 5.7.1

Improve how scan decodes the text it extracts. Escape sequences, XML entities, and inline markup are now handled per file format, so candidates arrive in Ditto as the text a user sees instead of as raw source.

MCP

Add the list_statuses tool, which lists the statuses text items and library components can be set to, in workflow order. The MCP server now supports logging in with your Ditto account via OAuth, in addition to a static API token. See Installation for setup instructions per client.

API

Add Delete components (DELETE /v2/components) endpoint for deleting library components by developer ID. Add Fetch statuses (GET /v2/statuses) endpoint for listing the statuses available in a workspace, in workflow order.

August 11, 2026

API

Add richText parameter to Update text items (PATCH /v2/textItems) and Create text items (POST /v2/textItems). When richText param is set to html, all text values in the update request — including plural and variant text — will be parsed as an HTML string and saved as rich text. For example, the following request would store formatted string “Inspiration for your next trip” as the Korean variant:

{
  "richText": "html",
  "variantId": "korean",
  "updates": [
    { "developerId": "homepage.section.inspiration", "text": "<strong>Inspiration</strong> for your next trip" }
  ]
}

Supported formatting: /, /, , <s>, and   for line breaks.
 and  are only supported for workspaces with superscript and subscript enabled.
We drop unsupported markup such as links, lists, or headings but keep its text.
{{variable_name}} placeholders still resolve, and keep any formatting applied around them.
Without the parameter, text is saved as plaintext and any markup is stored literally, unchanged from previous behavior.

August 10, 2026

MCP

Add create_variables, update_variables, and delete_variables tools for managing variables from your editor.

API

Add Create variables (POST /v2/variables), Update variables (PATCH /v2/variables), and Delete variables (DELETE /v2/variables) endpoints.

Renaming a variable with newName rewrites every {{variable_name}} placeholder referencing it — across text items, library components, variants, and plurals — so existing text keeps resolving.
A variable can’t be deleted while any text item or library component still references it.

August 6, 2026

MCP

Add create_variants, update_variants, and delete_variants tools for managing variants from your editor.

API

Add Create variants (POST /v2/variants), Update variants (PATCH /v2/variants), and Delete variants (DELETE /v2/variants) endpoints.

At most one variant per workspace can hold a given locale code.
A variant can’t be deleted while any text item or library component still has text for it.

August 5, 2026

Ditto CLI - 5.7.0

Add the login and logout commands. login signs you in through your browser, so the CLI no longer needs an API key.

npx @dittowords/cli login

The session is saved to $HOME/.config/ditto and renews itself as you keep using the CLI. Commands act as you — your Ditto account and its permissions — instead of as whoever generated an API key.
logout forgets the session on this machine and revokes it with Ditto.
API keys still work. DITTO_TOKEN takes precedence over a saved session, so CI and other headless environments are unaffected. See credential precedence.

August 3, 2026

MCP

Add create_styleguide, list_styleguides, and update_styleguide tools for managing style guides themselves — sections, the default-enabled setting, and metadata — as opposed to the rules inside them. Add create_styleguide_rules, update_styleguide_rules, and delete_styleguide_rules tools for managing the rules inside a style guide section. Add list_component_folders, create_component_folders, update_component_folders, and delete_component_folders tools for managing component library folders from your editor.

API

Add Create a style guide (POST /v2/styleguides) and Update a style guide (PATCH /v2/styleguides) endpoints, along with Create style guide rules (POST /v2/styleguides/rules), Update style guide rules (PATCH /v2/styleguides/rules), and Delete style guide rules (DELETE /v2/styleguides/rules) endpoints for managing the rules inside a section. Add Fetch component folders (GET /v2/componentFolders), Create component folders (POST /v2/componentFolders), Update component folders (PATCH /v2/componentFolders), and Delete component folders (DELETE /v2/componentFolders) endpoints.

July 31, 2026

MCP

Add the suggest_edit tool, which checks text against your workspace’s style guide rules and returns suggested edits — the same rule-based suggestions shown in the Ditto app. Check an existing text item by developer ID, or freeform text that isn’t saved as a text item yet.

July 29, 2026

MCP

Add list_project_blocks, create_project_blocks, update_project_blocks, and delete_project_blocks tools for managing the blocks that group text items within a project.

API

Add Fetch project blocks (GET /v2/projectBlocks), Create project blocks (POST /v2/projectBlocks), Update project blocks (PATCH /v2/projectBlocks), and Delete project blocks (DELETE /v2/projectBlocks) endpoints.

July 27, 2026

Ditto CLI - 5.6.3

Improve how scan handles codebases that are larger than a workspace’s plan’s scan limit. Add the --list-directories flag. scan <path> --list-directories prints the number of candidate strings found in each directory and exits without uploading anything, so you can choose a scope before running a real scan.

npx @dittowords/cli scan . --list-directories

Counts are rolled up: each directory includes the strings found in its subdirectories.
Directories are printed in tree order, indented by depth, with the whole scan total at the top.

When a scan exceeds your plan’s limit, the error now suggests narrower paths to scan instead of just reporting the limit.

The message lists the largest subdirectories that each fit within your remaining limit, with their string counts and a ready-to-run command for each.
The limit is checked before candidates are uploaded, so an oversized scan fails right away instead of after the upload finishes.

MCP

Add the create_ditto_project and list_project_folders tools for creating projects and looking up project folders from your editor.

API

Add Create a project (POST /v2/projects) endpoint. Optionally provide a folder’s developer ID to create the project inside that folder.

July 24, 2026

MCP

Add create_library_components and update_library_components tools for managing library components from your editor, and the list_component_folders tool for looking up their folders.

July 22, 2026

Documentation

Document the agent setup package as the default way to integrate Ditto with Claude Code. See Agent setup package. Standardize the API token environment variable to DITTO_TOKEN across the CLI, Ditto Specs, and MCP setup docs (previously DITTO_API_KEY and DITTO_API_TOKEN).

MCP

Add list_variants and list_variables tools, and expose variants and variables on the text item and library component tools — reference a variable with a {{variable_name}} placeholder, or set variant-specific text via a variant’s developer ID.

July 10, 2026

MCP

Add create_text_items, update_text_items, and delete_text_items tools for managing text items in bulk from your editor, and the list_projects tool for looking up a project’s developer ID.

July 9, 2026

API

Add Fetch activity (GET /v2/activity) endpoint for retrieving a paginated list of change events in your workspace, optionally filtered by project, text item, library component, or entity type.

July 1, 2026

API

Add blockName field to Fetch text items (GET /v2/textItems) response.

Each text item now includes a blockName field: the name of the block the text item belongs to, or null if it is not in a block.

June 25, 2026

API

Add sort parameter to Fetch text items (GET /v2/textItems).

id (default) sorts the response alphabetically by developer ID (matching previous behavior)
project_order groups items by project, returned alphabetically by project developer ID, then sorts within projects based on the custom sort order set up in the web app.

June 16, 2026

Ditto CLI - 5.6.0

Add the scan command. scan <path> analyzes a local directory for user-facing text and sends the candidates to Ditto, where you can review them and turn them into a content system tailored to your product. See the Scan documentation.

This release includes packages that require Node.js 20 or higher.

June 10, 2026

API

Add new variant fields variants[n].status, variants[n].assignee, variants[n].notes, and variants[n].characterLimit to the Create text items resource.

assignee must be a valid email matching a user in your workspace
variant status must be a valid status in your workspace

June 4, 2026

API

Add folderId to the Update components resource, allowing users to organize their components in bulk.

If folderId of null or "root" is provided, will move component into “All Components”.
If folderId omitted, component folder will remain unchanged

Add Get style guides (GET /v2/styleguides) endpoint for fetching the style guides created in your workspace, along with their sections and rules.

May 28, 2026

API

Add assignee, along with new variant fields variants[n].status, variants[n].assignee, variants[n].notes, and variants[n].characterLimit to the Create components resource.

assignee must be a valid email matching a user in your workspace
variant status must be a valid status in your workspace

May 18, 2026

API

Add characterLimit field to Fetch text items (GET /v2/textItems) and Fetch components (GET /v2/components) responses.

Each text item and component in the response now includes a characterLimit field: a positive integer when a limit is set, or null when no limit is configured.
For variant responses, characterLimit reflects the variant’s own character limit rather than the base value.

May 12, 2026

API

Update Text Item and Component endpoints to support variant assignee, notes and character limit.

Fetch text items (GET /v2/textItems) and Fetch components (GET /v2/components) now return variant assignee and notes in variant response objects, not the base properties.
Requests that include an assignee filter and a variantId return only items whose base and variant assignees both match the filter. This applies to Fetch text items (GET /v2/textItems), Export text items (GET /v2/textItems/export), Fetch components (GET /v2/components), and Export components (GET /v2/components/export).
Requests that include assignee, notes and/or character limit along with a variantId in the payload of Update text items (PATCH /v2/textItems) or Update components (PATCH /v2/components) will update that variant’s properties, not the base values.

April 30, 2026

API

Add component name to the response of Fetch components (GET /v2/components) endpoint. Each component in the response will now include a name field matching the component name. The same component name will be returned across base text, variants and plural forms.

April 6, 2026

API

Add Update components (PATCH /v2/components) endpoint. Supports updating text, tags, status, and assignee on components identified by developer ID. Includes optional variant targeting with variantId and forceVariantCreation parameters. Add PATCH /v2/textItems as the preferred method for updating text items. PUT /v2/textItems continues to work but is now deprecated.

April 1, 2026

Ditto CLI - 5.5.1

Dependency updates and internal improvements. See full release notes here.

March 31, 2026

Ditto CLI - 5.5.0

Add CLI support for filtering by tags. Add a tags configuration to your config file to scope text items and components by one or more tags, with support for AND/OR operators.

tags:
  values:
    - "tag-1"
    - "tag-2"
  operator: "AND"

The tags filter can be specified at the top level of your config or within individual outputs (output-level overrides top-level). When operator is "AND", only items with all specified tags are returned. When operator is "OR" (or omitted), items with any of the specified tags are returned. See full release notes here.

March 27, 2026

MCP

Add the get_workspace_tags tool, which lists the tags currently in use across the workspace — useful before adding tags to a style guide rule, since only existing tags are allowed. Add the first tools for creating, updating, and deleting style guide rules from your editor.

March 26, 2026

API

Add assignee and tags filters to Fetch components (GET /v2/components), Export components (GET /v2/components/export), and Export text items (GET /v2/textItems/export). The assignee filter accepts an email address or null to match unassigned items. The tags filter accepts an array of tag values with an optional operator field (AND or OR, defaulting to OR).

March 24, 2026

Ditto CLI - 5.4.0

Add CLI support for filtering by integration status. Add integrated: true to your config file to fetch only text items and components that have been marked as integrated into development. See full release notes here.

API

Add the ability to update the integrated flag of a text item via Update text items (PUT /v2/textItems).

March 23, 2026

API

Add integrated field to the response data of:

Fetch text items (GET /v2/textItems)
Fetch components (GET /v2/components).

Add optional integrated boolean filter to:

Fetch text items (GET /v2/textItems)
Export text items (GET /v2/textItems/export)
Fetch components (GET /v2/components)
Export components (GET /v2/components/export)

March 20, 2026

MCP

The Ditto MCP server can now run remotely over Streamable HTTP, instead of only as a local stdio server. See Installation for how to connect Claude Code, Cursor, VS Code, Windsurf, Codex, and other MCP clients.

March 19, 2026

API

Add plurals field to Update text items (PUT /v2/textItems) API endpoint. The plurals field supports upsert and remove operations for managing plural forms (zero, one, two, few, many, other) on text items. Existing plural forms not mentioned in either operation are preserved. Supports variant plurals via the variantId parameter.

March 18, 2026

API

Add assignee and tags filters to Fetch text items (GET /v2/textItems). The assignee filter accepts an email address or null to match unassigned text items. The tags filter accepts an array of tag values with an optional operator field (AND or OR, defaulting to OR). Fetch text items (GET /v2/textItems) and Fetch components (GET /v2/components) now include the assignee field in the response payload, returned as the assignee’s email address or null if unassigned.

March 16, 2026

API

Add assignee field to Update text items (PUT /v2/textItems) API endpoint. The assignee field accepts an optional email string of a user in the workspace to assign to the text item. Setting assignee to null will remove the current assignee.

March 12, 2026

MCP

Add the search_ditto_text tool, which searches your workspace for existing text items and library components by content — so agents can find and reuse strings instead of generating new ones.

March 5, 2026

MCP

Ditto’s MCP server is here! It connects AI coding agents to your team’s content in Ditto, starting with the get_styleguide_rules tool for fetching workspace and project-level style guide rules. See the MCP overview to get started.

February 10, 2026

API

Add Create components (POST /v2/components) endpoint for creating new library components.

February 2, 2026

API

Fetch text items (GET /v2/textItems), Fetch components (GET /v2/components), Export text items (GET /v2/textItems/export), and Export components (GET /v2/components/export) now return a 400 error response when statuses that don’t exist in your workspace are provided in the status filter.

January 14, 2026

API

Fetch text items (GET /v2/textItems) and Fetch components (GET /v2/components) now return separate records for each plural form. Plural forms follow the standard i18n plural forms outlined here. Each record in the response includes a pluralForm value, and for each pluralForm on a text item or component, a separate record is returned with that pluralForm and its respective value. If a record has a pluralForm, it will be appended to the end of the developer ID. Example response:

[
  { "id": "some-items", "text": "Some items", "pluralForm": null, ... },
  { "id": "some-items_other", "text": "Some items", "pluralForm": "other", ...},
  { "id": "some-items_one", "text": "An item", "pluralForm": "one", ... }
]

Ditto CLI - 5.3.1

Default JSON file formats now include plurals, where the standard unicode plural rule (zero, one, two, few, many, other) is appended to the end of the developer ID key. Example output:

{
  "some-items": "Some items",
  "some-items_one": "An item",
  "some-items_other": "{{count}} items"
}

See full release notes here.

January 7, 2026

API

Add Export text items (GET /v2/textItems/export) and Export components (GET /v2/components/export) endpoints for fetching text items and components in .json ICU, .json i18next, .json Vue i18n, .strings, .stringsdict, or .xml formats.

Ditto CLI - 5.3.0

Add CLI support for Android .xml, iOS .strings and .stringsdict, and ICU .json formats. In conjunction with iOS format additions, add iOS Locale directory generation for configured variant -> locale mappings in config. If iOS locales are configured, CLI will also auto-generate a Ditto.swift file for reading locale values. See full release notes here.

December 11, 2025

Ditto CLI - 5.2.0

Add CLI support for filtering text items/components by status when pulling changes. The filtering logic used for the cli is the same as the Fetch text items (GET /v2/textItems) and the Fetch components (GET /v2/components) API endpoints. See full release notes here.

December 10, 2025

API

Relax requirement in Update text items (PUT /v2/textItems) API endpoint that requires text to be included in the request. Add tags field which is an optional string[] that if set in the request will replace the existing tags with the specified tags on the textItem.

December 9, 2025

API

Clarified expected behavior with variant and status filtering for Fetch text items (GET /v2/textItems) API endpoint. Variants that match the variant filter should only be returned if they match the status filter and their base text also matches the status filter. Added query param in Fetch components (GET /v2/components) API endpoint status filter that allows for filtering components by status. Variants that match the variant filter should only be returned if they match the status filter and their base text also matches the status filter.

December 5, 2025

API

Added Fetch text items (GET /v2/textItems) API endpoint status filter that allows for fetching textItems by status. Relax requirement in Update text items (PUT /v2/textItems) API endpoints that requires all textItems to be in the same project. Now updates can include textItems that span multiple projects and all will be updated.

Documentation

Fix env var naming used in the cli for setting the ditto api token to the correct value DITTO_TOKEN

November 5, 2025

API

Added delete text items (DELETE /v2/textItems) API endpoint for deleting text items.

October 6, 2025

Ditto Github Action - 1.0.2

Updates the Github Action to work with CLI v5.x, compatible with both new and legacy Ditto. After upgrading, the Github Action will fetch from new Ditto projects/components by default. Legacy users will need to add pull-from-legacy: "true" to their workflow file to continue fetching legacy text. If you wish to use this action for both new and legacy Ditto, simply create separate steps with different inputs. See the README for more details and examples. Release notes:

Ditto CLI - 5.1.0

A small update to support the -m and --meta flags in commands. This is used internally for analytics and should not affect customer workflows. See full release notes here.

October 1, 2025

Ditto CLI - 5.0.0

First official stable release that provides support for fetching project text and components from the new Ditto experience, including all features from the v5 Beta release (through 5.0.0-beta.8). This version maintains full support for fetching from legacy projects and components. Simply include the --legacy flag along with any command from v4.x. Users with both new and legacy projects may pull data from both places into the same codebase by maintaining two separate config files and output directories, and including the path to the right config file in your pull command. See full release notes here.

September 29, 2025

API

Added fetch components (GET /v2/components) API endpoint for fetching components in the user’s workspace.

Ditto CLI - 5.0.0-beta.8

Added support for fetching components in addition to project text via the CLI. Include components in your config file to fetch components from the specified folders. Include projects in your config file to fetch text from the specified projects. Breaking change: If projects or components are omitted from the config file, will not fetch text from that area. Previously, if projects was omitted, it would fetch text from all projects. See full release notes here.

September 11, 2025

API

Added the ability to create variants from update text items (PUT /v2/textItems) API endpoint with the forceVariantCreation parameter.

August 18, 2025

Ditto CLI - 5.0.0-beta.7

Added support for fetching and outputting rich text (HTML) content for Ditto text, by adding richText: html to the config file. At this time, this version is still in Beta, accessible via @dittowords/cli@beta. See full release notes here.

July 24, 2025

API

Added create text items (POST /v2/textItems) API endpoint for creating new text items.

July 8, 2025

API

Added update text items (PUT /v2/textItems) API endpoint for editing existing text items.

April 30, 2025

Ditto CLI - 5.0.0-beta.6

Beta release of CLI for Ditto 2.0. This version supports fetching text from new, non-legacy Ditto projects. It requires a new format for the config file and supports returning json files formatted for i18next. This version is still in beta, and can be accessed via @dittowords/cli@beta. Supports all legacy features via --legacy flag. Release notes:

March 28, 2025

API

Added fetch project folders (GET /v1/project-folders) API endpoint for fetching project folders in the user’s workspace.
Added fetch projects by project folder id (GET /v1/project-folders/:folder_id/projects) API endpoint for fetching projects in the specified folder.

March 24, 2025

API

Added the first set of v2 endpoints to the API:

Added fetch projects (GET /v2/projects) API endpoint for fetching projects in the user’s workspace.
Added fetch text items (GET /v2/textItems) API endpoint for fetching text items in the user’s workspace.
Added fetch variables (GET /v2/variables) API endpoint for fetching variables in the user’s workspace.
Added fetch variants (GET /v2/variants) API endpoint for fetching variants in the user’s workspace.

February 3, 2025

API

The fetch component text (GET /v1/components) API endpoint now supports the includeTimeData query parameter. When includeTimeData is set to true, the response will include the createdAt and updatedAt fields for each component. This feature is only available when the structured format is used.

November 11, 2024

Ditto React - 1.6.3

Dependency upgrades

See full release notes here

May 21, 2024

Ditto CLI - 4.5.2

Fix to include header distinguishing Ditto CLI requests from direct API requests.

See full release notes here.

May 7, 2024

Ditto CLI - 4.5.1

Fix issue with error logs not being flushed before exiting the CLI

See full release notes here.

May 3, 2024

Ditto Github Action - 0.3.0

add optional name input parameter pr-title-prefix to distinguish prs with multi config setups

See full release notes here.

May 2, 2024

API / Web App

Pluralization is now supported for all JSON formats when importing components via the Ditto web app or the Fetch component text API endpoint. Example import data:

{
  "fruit": "You have fruit in your cart.",
  "fruit_one": "You have one fruit in your cart.",
  "fruit_other": "You have some fruit in your cart."
}

April 16, 2024

CLI

v4.5.0 released to add support for a new option which disables the generation of index.js and index.d.ts files when working with JSON formats. See the release notes here.

March 22, 2024

CLI

v4.4.1 released to fix periodic hanging from attempting to exit the CLI process using Ctrl + C. See full release notes here.

March 15, 2024

Documentation

Small fixes and wording clarifications on the SDKs page

March 13, 2024

Ditto React - 1.6.1

Fix crash when rich text is enabled

See release notes: https://github.com/dittowords/ditto-react/releases/tag/v1.6.1

February 29, 2024

Ditto CLI - 4.4.0

Add pull —sample-data flag for variants

See release notes: https://github.com/dittowords/cli/releases/tag/v4.4.0

February 27, 2024

Ditto API

/v1/variants now supports the showSampleData query parameter
Fix /v1/variants for projectIds query parameter

February 19, 2024

Ditto CLI - 4.3.0

nested format is now supported

See release notes: https://github.com/dittowords/cli/releases/tag/v4.3.0

Ditto CLI - 4.2.3

Upgrades to several dependencies

See release notes: https://github.com/dittowords/cli/releases/tag/v4.2.3

January 22, 2024

Ditto CLI - 4.2.2

Stop component folders with emojis from creating a leading separator

See release notes: https://github.com/dittowords/cli/releases/tag/v4.2.2

December 12, 2023

Ditto API

The /components/file endpoint now supports a folderId query parameter. You can supply the Developer ID of one of your component folders, and all the components will be imported to that folder.

December 7, 2023

Ditto React

v1.3.2 released to fix a bug that incorrectly tracked the “Searching” location.

November 28, 2023

Ditto CLI - 4.2.1

Only run init() on commands that need it in https://github.com/dittowords/cli/pull/89

This change prevents the ditto directory from being created on commands that don’t need it (e.g. generate-suggestions) See release notes: https://github.com/dittowords/cli/releases/tag/v4.2.1

November 16, 2023

Ditto CLI - 4.2.0

Add --sample-data flag to the components-folders command in https://github.com/dittowords/cli/pull/88 See release notes: https://github.com/dittowords/cli/releases/tag/v4.2.0

November 2, 2023

Ditto React

Ditto text items with rich text can now be rendered natively by passing the richText property on either Ditto or DittoText. This expands rich text support from v1.5.0 which introduced support for rich text on components. Example:

<Ditto textId="text_61e7238bbae5dc00fb66de15" variables={{ itemCount: 5 }} richText />

October 30, 2023

Ditto CLI — 4.1.0

This release includes features designed to tighten integration for a variety of environments, including iOS, TypeScript, and more. See the release notes here.

New example apps

We’ve released new versions of our example applications, which have been updated to include the latest in recommended practices for integrating Ditto into development. See the full list here.

September 29, 2023

Ditto Webhooks have been released!

August 29, 2023

Ditto React

Ditto components with rich text can now be rendered natively by passing the richText property on either Ditto or DittoComponent.
Example: <Ditto componentId="shopping-cart" richText />

August 18, 2023

Ditto API

Endpoints for fetching project text now support an exclude_components query parameter.
When exclude_components=true, only text items not associated with Ditto components will be returned from a given endpoint.

Ditto CLI

We’ve released a new major version (v4) of the CLI. See the release notes here.

August 15, 2023

Ditto API

The behavior of variables when exporting to mobile formats (.strings, .stringsdict, and .xml) has changed. Variables will now maintain a consistent ordering across base text, variant text, and plural forms; they’re assigned an index according to the order of usage (starting with base text, and then variants), and that index is maintained through variant exports. For example, consider the following text:

// Base Text
{{username}}, your role is {{role}}.

// Variant Text
Tú papel es {{role}}, {{username}}.
Previously, exports for the base text and variant text would cause format specifier indices to be reversed for the variables:
/* base-example.strings */
"text" = "%1$@, your role is %2$@.";

/* spanish-example.strings */
"text" = "Tú papel es %1$@, %2$@.";
To facilitate ease of integration into development, exports for variant text will now ensure that the format specifier indices match those in the base text:
/* base-example.strings */
"text" = "%1$@, your role is %2$@.";

/* spanish-example.strings */
"text" = "Tú papel es %2$@, %1$@.";

August 7, 2023

Ditto API

Support has been added for an exclude_components query parameter to the endpoint.
When set to true, only text items not associated with components will be returned from the endpoint.

Ditto CLI

Small bug fix to ensure files aren’t written to disk for empty API responses.
For more information, please refer to the release here.

July 26, 2023

Ditto API

When exporting data for variants, variant metadata (name and description) is now included.
- In the JSON formats, two new meta keys are added at the top level: variant_name and variant-description
- In the Android .xml, iOS .strings, and iOS .stringsdict formats, a comment is added for each field at the top of the file

July 17, 2023

Ditto API

The flat format now supports rich text.

June 27, 2023

Ditto CLI

Added support for specifying a list of formats in the format configuration property.
For more information, please refer to the release here.

June 26, 2023

Ditto React

v1.4.1 fixes a bug introduced in v1.4.0 which caused variables to ignore passed values.

June 14, 2023

Ditto CLI

Added the import-components command which enables component imports via a file through the CLI. For information about the command please refer to the documentation in the README.

June 12, 2023

Ditto API

We’ve added the new POST /components/file endpoint to enable uploading components through the API.

June 8, 2023

VSCode Extension

Add the ability to only match on components from a component folder. Must be used with v3.8.0 of the Ditto CLI.

Ditto CLI

Add component-folders command which lists component folders in your workspace. See the release here.

June 5, 2023

Ditto CLI

Add the -cf (--component-folder) flag for generate-suggestions. See the release here.

June 2, 2023

Ditto CLI

Performance improvements. See the release here.

May 30, 2023

Ditto CLI

We’ve added support for specifying the new ios-stringsdict format in the CLI configuration. See the release here.

Ditto API

We clarified a small point of confusion with the documentation around the request payload expected for the endpoint. The JSON payload should include a top-level data property:

{
  "data": {
    "[API ID]": {
      "text": "[TEXT OF TEXT ITEM (CAN INCLUDE VARIABLES)]",
      "notes": "[NOTES OF TEXT ITEM]", // optional
      "tags": [ ... ], // optional: array of strings
      "plurals": [ // optional: array of plural objects
        {
          "text": "[TEXT OF PLURAL FORM]",
          "form": "[one|two|zero|few|many|other]"
        }
      ]
    }
  }
}

May 12, 2023

Ditto API

We’ve added support for the iOS .stringsdict format to our API. Read more here.

May 3, 2023

Ditto CLI

Adds ICU support
Fixes a bug where pulling would fail on new initializations
Full Changelog

May 1, 2023

VS Code Extension

We’ve create a VS Code extension! Check it out here.

April 28, 2023

Ditto API

We’ve added support for an ICU JSON export format to our API. Read more here.

April 26, 2023

Ditto CLI

v3.4.0 of the CLI has been published, which adds a -v, --version flag to output what version of the CLI is being run.

March 23, 2023

Ditto React

We’ve published v1.4.0, which includes explicit support for map and list variables, in addition to miscellaneous cleanup. Read about the release here.

March 22, 2023

Ditto API, Ditto CLI, Ditto React

We’ve added a __type property to variable output in our structured export format; this enables simple discrimination between different types of variables:

{
  "some-variable-1": {
    "example": "Hello world!",
   "__type": "string"
  },
  "some-variable-2": {
    "example": 100,
    "__type": "number"
  },
  "some-variable-3": {
    "text:" "Foo",
    "url": "https://bar.com",
    "__type": "hyperlink"
  }
}

March 21, 2023

Ditto API

We’ve added support for a nested JSON export format to our API. Read more here.

March 9, 2023

Ditto CLI

We’ve published v3.0.0 of the CLI, which focuses around a number breaking changes intended to better align default CLI behavior with Ditto best practices. Read the release notes here.

February 15, 2023

Ditto API

We’ve released two bug fixes specific to the Android XML export format:

index values for format specifiers will now be relative to a text item’s base value AND its plurals, instead of resetting for each plural form (issue)
extra whitespace is no longer added between text and variables in the final output (issue)

February 14, 2023

Ditto API

We’ve released a new version of our API that includes some breaking changes. The old API endpoints are deprecated, and existing users should migrate to the new endpoints at their earliest convenience.

February 6, 2023

Ditto Web App

Removed the deprecated the full format from the export modals on the project page and in the component library
Set the flat format to be the default export format in the web app

February 3, 2023

Ditto API

Minor documentation update to add and emphasize a deprecation notice for the full format.

February 1, 2023

Ditto React — 1.3.0

Added support for using variables in conjunction with the flat format. See the release here.

January 25, 2023

We added support to the web app for importing components from two new file formats:

Android localization files (.xml)
iOS localization files (.strings)

January 19, 2023

Ditto React — 1.2.1

Updated README to clarify that the flat format does not currently support variables.
Fixed a bug preventing falsy values (namely 0 and "") from being properly interpolated.

See the release here.

December 15, 2022

Ditto CLI

Added rich text support. See more info here

December 13, 2022

Ditto API

Added the includeRichText flag to the following endpoints (format must be full or structured):

/projects
/projects/:id
/projects/:id/components
/components
/component-folders/:api*id/components

November 30, 2022

Ditto CLI

Added the status filter as a configuration variable. To filter the fetched text by its status, you can now use the status parameter in your config.yml.

November 29, 2022

Ditto CLI

Added android and ios-strings as available formats. To use these formats, specify them under the format paramter in your config.yml.

November 10, 2022

Ditto API

Fixed a typo in an example in the documentation containing an incorrect usage of the curl command.

Ditto CLI

Added information to the README about two supported environment variables:

DITTO_CONFIG_FILE: used to specify an alternate file location for the CLI to read authentication information from. The default path is $HOME/.config/ditto.
DITTO_TEXT_DIR: used to specify an alternate folder location for the CLI to write its output files to. The default path is ./ditto.

Oct 11, 2022

Ditto API

Added new endpoint: Fetch component folders
Added new endpoint: Fetch components by component folder
Added sub-headings to divide the endpoints by the entity they’re associated with, and implemented minor miscellaneous cleanup across the endpoint documentation

Sep 23, 2022

Ditto API

Text items with plural values will have those plural values included in flat exports as individual key/value pairs; pluralized keys are structured like [TEXT ID]_[PLURAL FORM]. See the flat format documentation for more details. Fixed a bug where the status field failed to properly filter returned data when specified in conjunction with the android or ios-strings formats.

Sep 19, 2022

Ditto React — 1.2.0

We exported two hooks that can be used for accessing synced data: useDittoSingleText and useDittoComponent. These hooks are experimental and will likely undergo API changes in the future.
See the release here.

Ditto API

Added the status field to data returned from the /components and /projects/:id/components endpoints.

Jun 30, 2022

Ditto API

Added support for including variables in payloads sent to the PUT /components endpoint.
Fixed an issue with Android & iOS export formats not escaping special characters: \n, \t, @, ?, ', and " characters are now properly escaped.
Added missing xliff namespace to exported Android .xml files. = Fixed a bug with Android .xml exports that occurred with text items with API IDs that include the - character. Now, all - characters are replaced with \_ characters in the name property of <string> and <plural> tags, and a ditto_api_id property has been added to string and plural tags to serve as a reference to the original API ID.

Ditto CLI — 2.5.1

Fixed a bug when using the project add / project remove commands and selecting the component library caused incorrect modifications to be made to the CLI’s configuration file.
See the release here.

Ditto Example Projects

Added new iOS Example Project showcasing how to use exported .strings files.
Added new Android Example Project showcasing how to use exported .xml string files.

See Example Projects for more details.

Jun 13, 2022

Ditto GitHub Action — 0.2.0

Added an optional ditto-dir input parameter for projects that do not have the ditto directory in the root of the repository

June 7, 2022

Ditto API

Added support for upserting plurals via the PUT /components. See our API documentation for more details.

June 1, 2022

Ditto API

Added early support for exporting text data to Android and iOS Strings formats. All endpoints that support a format query parameter can now accept values of android or ios-strings.
Added GET /variables endpoint that returns the variables in the workspace of the requesting user.
Added the ability to filter by text item status by passing a status query parameter in API requests. Supported by the following endpoints:
- GET /projects
- GET /projects/:id
- GET /projects/:id/components
- GET /components See our API documentation for more details.

May 23, 2022

Ditto CLI — 2.5.0

Added meta option flag in support of the Ditto GitHub Action release. See the release here.

Ditto GitHub Action — 0.1.0

v0.1.0 released! Check it out here.

May 16, 2022

Ditto CLI — 2.4.0

Update some user-facing CLI messages to accurately reflect our new subdomain: app.dittowords.com (instead of the old beta.dittowords.com). See the release here.

May 10, 2022

Ditto CLI — 2.3.0

Allows users to override the output directory via a new environment variable DITTO_TEXT_DIR
When no projects are found in the config.yml file an additional help message displays about verifying that the projects have developer mode enabled
See the release here.

February 28, 2022

Ditto API

Added better error handling for the niche edge case where an API request is made using the token of a user that has been removed from their workspace.

January 20, 2022

Ditto React — 1.1.1

Our React SDK now supports variable interpolation by passing in values through the variables prop.
Our React SDK now supports displaying plural forms through the count prop. For more information about using variable interpolations and pluralization through our React SDK, check out our SDK documentation.

Ditto CLI — 2.2.0

The CLI now supports reading API keys from an environment variable (DITTO_API_KEY).
See the release here.

January 11, 2022

Ditto CLI

We deployed a bugfix release to fix issues introduced in the latest minor version of the package:

the pull command no longer crashes when projects other than the component library are specified in config.yml
resolves a casing issue in the project add command that was causing it to crash

See the release here.

January 6, 2022

Ditto CLI

We’ve added a new supported property to ditto/config.yml to allow explicitly specifying that the component library should be fetched and included in the CLI’s output: components: true This is now the preferred alternative to the old way of specifying the component library:

projects:
  name: Ditto Component Library
  id: ditto_component_library

Our goal with this change is to make the CLI easier to use and understand by aligning it with the way things work in the Ditto web app, where the component library is fundamentally different from the projects in a workspace. See the release here.

December 8, 2021

Ditto API

GET /projects/:id/components can now be used to fetch the components used in a project
Return format matches the GET /components endpoint
Supports format and variant parameters (the same as the /projects, /project/:id, and /components endpoints)

November 29, 2021

Ditto API

GET /components can now be used to fetch the components in a workspace
- Supports format and variant parameters (the same as the /projects and /project/:id endpoints)
GET /projects/ditto_component_library has been deprecated; the endpoint is still available, but references to it have been removed from the documentation.
PUT /components can now be used to update the text of components in a workspace
- Currently only supports updating variant text via the variant query parameter (an error will be thrown if not specified)
- Currently only available to teams on Team or Enterprise plans
- Data is specified on data key in request body and must be in one of our three supported import formats

November 11, 2021

Ditto CLI — 2.0.0

Output files are now written to disk in several different ways according to how the CLI is configured; most notably, if the variants option is set and a format of structured or flat is specified, output files will be written on a per-project per-variant basis
Data for structured and flat formats is saved without arbitrary top-level nesting
Files are only written for variants that contain values for the configured projects (no more empty files) For a more in-depth description (with examples) of these changes and others in the release, see the full release notes here.

Ditto React — 1.0.0

ditto-react now only works with CLI version 2.x.x — leaning into new CLI improvements allowed us to drastically reduce many areas of complex logical overhead
We made some stabilization improvements to the way that missing/invalid frameId, blockId, textId, or componentId values are handled
We implemented significant refactoring in several areas of the project For a more in-depth description of these changes, see the full release notes here

Ditto Demo

We added a new branch that showcases how Ditto can be integrated into a project with react-i18next
We updated dependencies to the latest versions of the Ditto CLI (v2.0.0) and Ditto React (v1.0.0)

October 22, 2021

Ditto API — 2.4.1

We fixed a bug with the API (and in-app exports) that included hidden text in flat and structured JSON exports. Now, hidden text will correctly not be included in these export formats!

Ditto Demo

We included the files to import into the component library separately from where they’d be synced via the CLI
We included more instructions on linking the demo app with its corresponding design file

October 7, 2021

General

Refactored API documentation to be easier to navigate and communicate critical concepts more clearly

Ditto CLI — 1.1.1

When the pull command is executed, all .json and .js files are now removed from the ditto folder prior to new data being written = Support added for new options in ditto/config.yml:
- variants: true or false
  - If set to true, data will be fetched for both base and variant text and stored in separate JSON files
- format: flat or structured - If specified, data will be fetched and stored in the specified format = Refactored README
GET /variants will now return names and API IDs for variants in the workspace associated with the requesting user.

Ditto React — 0.0.5

Support added for flat and structured formats
Support added for passing a variant value to DittoProvider
Bug fixes around support for integrating with workspace component libraries (as opposed to individual projects)
Refactored README

Ditto Demo

Refactored ditto-sdk usage to integrate with a component library instead of an individual project
Added a language picker to showcase ditto-react and ditto-cli support for variants
Refactored README, including adding instructions for connecting the repo to a component library

September 27, 2021

General

Fixed incorrect example of /projects usage in API Reference. The projectIds query parameter should be specified as follows:

Correct: ?projectIds[]=<PROJECT_ID>&projectIds[]=<PROJECT_ID>
Incorrect: ?projectIds[]=<PROJECT_ID>,<PROJECT_ID>

API — 2.4.0

GET /variants will now return names and API IDs for variants in the workspace associated with the requesting user.

September 8, 2021

API — 2.3.0

GET /projects and GET /projects/:id now accept an optional query parameter of variant; when provided, the data exported will be specific to the variant with an API ID that matches the parameter’s value. For default and structured formats, the variants key will not be included when the variant parameter is provided.

Example: /projects/<PROJECT_ID>?variant=xxx-xxx-xxx

GET /projects/:id will not include top-level projects and project_xyz keys Example request: GET /projects/123

Example response before change:

{ projects: { project_123: { text_item: "Hello World", ... }}}

Example response after change:

{ text_item: "Hello World", ... }

August 11, 2021

API — 2.2.0

GET /projects and GET /projects/:id now accepts an optional query parameter of format, which can be either flat or structured. If no format is provided, the full JSON of the project will be returned with blocks and frames. Example: /projects/<PROJECT_ID>?format=flat

July 28, 2021

With the recent release of Variants for Components, we’ve included them in both exports from our web-app and the JSON response from the API.

API — 2.1.0

GET /projects/:id will now return component variants. This applies both for when fetching projects or when fetching the component library (i.e. id = ditto_component_library)
GET /projects/:id will now match the project JSON export from the web-app to include component information (is_comp and component_api_id) in the text object

June 21, 2021

We’ve updated our React library and our demo project to work with the multi-project JSON structure that the CLI now saves in text.json.

Ditto React — 0.0.4

TypeScript bindings are now exported 🎉 A new projectId prop can be passed to DittoProvider or Ditto

If passed to DittoProvider, all descendant Ditto components will default to pulling text from the associated project
If passed to Ditto, the component will pull text from the associated project
If passed to both DittoProvider and Ditto, the value passed to Ditto will take precedence
Breaking change: If a Ditto component is rendered that is not provided a projectId via direct prop or DittoContext ancestor, an error will be thrown

See more details in the updated documentation.

Ditto Demo

Upgraded ditto-react to v0.0.4
Updated source to work with new ditto-react version by passing projectId props to all instances of DittoContext

June 7, 2021

We’ve updated both our CLI and API to handle multiple projects. Heads up! This results in some breaking changes to the CLI in order for it to list projects, and will change the format of the text.json fetched by the CLI. Please upgrade your Ditto CLI via either npm or yarn.

API — 2.0.0

GET /project-names is the new name of the previous GET /projects endpoint. Just as before, this will return the names and IDs of projects in your Ditto workspace with Developer Mode turned on
GET /projects/:id will now return the structured JSON in a format compatible with multiple projects
GET /projects is a new endpoint that will return the content of multiple projects (specified via the query parameter projectIds) as a single JSON object

CLI — 1.0.0

We’ve updated the CLI to handle syncing multiple projects in a single directory! This means several things: /ditto/config.yml now supports multiple projects. ditto-cli pull will pull all projects in the current directory’s /ditto/config.yml
We’ve added two new commands to add and remove projects from /ditto/config.yml
- ditto-cli project add
- ditto-cli project remove
- The regular ditto-cli project command will now function as ditto-cli project add

April 1, 2021

API — 1.1.0

GET /projects now includes the Component Library if Developer Mode is enabled for the Component Library
GET /projects/:id will return the Component Library as a structured JSON if the ID provided is ditto_component_library

February 25, 2021

API — 1.0.0

GET /projects endpoint for fetching Ditto projects from workspace
GET /projects/:id endpoint for fetching content in Ditto project as structured JSON

​October 30, 2026

​API

​October 29, 2026

​Ditto React — 1.6.4

​October 21, 2026

​API

​MCP

​October 20, 2026

​Library component versioning

​October 19, 2026

​API

​MCP

​Ditto CLI - 5.12.0

​October 16, 2026

​API

​October 15, 2026

​API

​Filter text items by component

​Readable validation errors

​October 12, 2026

​API

​New JSON metadata parameters

​Empty text is now included in exports

​Consistent html and html_paragraphs rich text output

​Variant notes in arb and ios-strings exports

​Ditto CLI - 5.11.0

​October 7, 2026

​API

​MCP

​October 5, 2026

​API

​October 1, 2026

​MCP

​September 17, 2026

​Ditto CLI - 5.10.0

​September 3, 2026

​API

​MCP

​September 2, 2026

​API

​MCP

​August 27, 2026

​API

​Ditto CLI - 5.9.0

​August 24, 2026

​Ditto CLI - 5.8.1

​August 20, 2026

​Ditto CLI - 5.8.0

​August 18, 2026

​Ditto CLI - 5.7.2

​August 17, 2026

​API

​August 13, 2026

​Ditto CLI - 5.7.1

​MCP

​API

​August 11, 2026

​API

​August 10, 2026

​MCP

​API

​August 6, 2026

​MCP

​API

​August 5, 2026

​Ditto CLI - 5.7.0

​August 3, 2026

​MCP

​API

​July 31, 2026

​MCP

​July 29, 2026

​MCP

​API

​July 27, 2026

​Ditto CLI - 5.6.3

​MCP

​API

​July 24, 2026

​MCP

October 30, 2026

API

October 29, 2026

Ditto React — 1.6.4

October 21, 2026

API

MCP

October 20, 2026

Library component versioning

October 19, 2026

API

MCP

Ditto CLI - 5.12.0

October 16, 2026

API

October 15, 2026

API

Filter text items by component

Readable validation errors

October 12, 2026

API

New JSON metadata parameters

Empty text is now included in exports

Consistent `html` and `html_paragraphs` rich text output

Variant notes in `arb` and `ios-strings` exports

Ditto CLI - 5.11.0

October 7, 2026

API

MCP

October 5, 2026

API

October 1, 2026

MCP

September 17, 2026

Ditto CLI - 5.10.0

September 3, 2026

API

MCP

September 2, 2026

API

MCP

August 27, 2026

API

Ditto CLI - 5.9.0

August 24, 2026

Ditto CLI - 5.8.1

August 20, 2026

Ditto CLI - 5.8.0

August 18, 2026

Ditto CLI - 5.7.2

August 17, 2026

API

August 13, 2026

Ditto CLI - 5.7.1

MCP

API

August 11, 2026

API

August 10, 2026

MCP

API

August 6, 2026

MCP

API

August 5, 2026

Ditto CLI - 5.7.0

August 3, 2026

MCP

API

July 31, 2026

MCP

July 29, 2026

MCP

API

July 27, 2026

Ditto CLI - 5.6.3

MCP

API

July 24, 2026

MCP