Text Items

Fetch text items

Returns a list of text items in your workspace.

get/textItems

Request

Base URL: https://api.dittowords.com/v2
URL: https://api.dittowords.com/v2/textItems
Auth: API key in header Authorization

Query parameters

filterstring

Stringified JSON filter object. Supports the following filter fields:

projects: array of objects with id (project developer ID)
bases: array of objects with id (base developer ID)
variants: array of objects with id (variant developer ID, base, or all)
statuses: array of status strings (NONE, WIP, REVIEW, FINAL). These are stored status keys; by default the web app and Figma plugin display them as NONE = "Draft", WIP = "In Progress", REVIEW = "In Review", FINAL = "Final" (a workspace may rename these or replace the set entirely, so none of these keys are guaranteed to exist — read the workspace's actual statuses from GET /v2/statuses or the list_statuses MCP tool rather than assuming this set).
tags: object with values (array of tag strings) and optional operator (AND or OR, defaults to OR)
assignee: email string to match assigned text items, or null for unassigned
integrated: boolean value to filter by items that are or are not integrated into development

Without any filters, the response will include text items from all projects and no base text items. If a projects filter is provided, only text items from the specified projects will be returned. If a bases filter is provided, only text items from the specified bases will be returned. The projects and bases filters may be used together to return items from both sources. (More details about bases coming soon!)

By default, only the base text will be returned for each text item. Provide a variants filter to specify which variants of the filtered text items to include. Use all to return all variants, including base text. If individual variants are specified, base text will only be returned if base is included in the filter.

For each text item that has plurals defined, separate entries will be returned for each plural form, plus the primary text with pluralForm: null. This applies to base text and variants.

The status and assignee filters apply only to project text items. Base text items do not contain these fields and will be returned unfiltered. When pairing variants with a status or assignee filter, variant data will only be returned if both the base and variant status/assignee match the filter.

Example: {"projects":[{"id":"project-id"}], "variants":[{"id":"french"}], "statuses":["NONE","WIP","FINAL","REVIEW"], "tags":{"values":["tag-1","tag-2"],"operator":"AND"}, "assignee":"user@example.com", "integrated":true}

sort'id' | 'project_order'

Sort order for the returned text items (default: id):

id sorts all items alphabetically by developer ID.
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.

richText'html' | 'html_paragraphs'

When set to html or html_paragraphs, includes HTML-formatted rich text in the response.

html_paragraphs wraps all text in <p> tags. Matches legacy behavior.
html exports without wrapping tags and uses <br /> for line breaks.

Response

Returns an array of text items matching the filter criteria

Example response

[
  {
    "id": "base-text-item-dev-id",
    "text": "Save changes",
    "richText": "Save changes",
    "variantId": null,
    "pluralForm": null,
    "projectId": null,
    "baseId": "base-dev-id",
    "folderId": "buttons-folder-dev-id",
    "notes": "base notes",
    "characterLimit": null,
    "tags": [
      "baseTag1",
      "baseTag2"
    ],
    "integrated": true,
    "variableIds": []
  },
  {
    "id": "text-item-dev-id",
    "text": "Save changes",
    "richText": "<strong>Save</strong> changes",
    "variantId": null,
    "pluralForm": null,
    "projectId": "project-dev-id",
    "baseId": "base-dev-id",
    "baseTextItemId": "base-text-item-dev-id",
    "blockName": "block name",
    "status": "NONE",
    "assignee": "john@example.com",
    "notes": "base notes",
    "characterLimit": null,
    "tags": [
      "baseTag1",
      "baseTag2"
    ],
    "integrated": true,
    "variableIds": []
  },
  {
    "id": "text-item-dev-id",
    "text": "Enregistrer les modifications",
    "richText": "<em>Enregistrer</em> les modifications",
    "variantId": "french",
    "pluralForm": null,
    "projectId": "project-dev-id",
    "baseId": "base-dev-id",
    "baseTextItemId": "base-text-item-dev-id",
    "blockName": "block name",
    "status": "WIP",
    "assignee": "john@example.com",
    "notes": "french notes",
    "characterLimit": 40,
    "tags": [
      "baseTag1",
      "baseTag2"
    ],
    "integrated": true,
    "variableIds": []
  },
  {
    "id": "another-text-item",
    "text": "Hello {{name}}, you have 3 messages",
    "richText": "Hello {{name}}, you have 3 messages",
    "variantId": null,
    "pluralForm": "other",
    "projectId": "another-project",
    "baseId": null,
    "baseTextItemId": null,
    "blockName": null,
    "status": "FINAL",
    "assignee": null,
    "notes": "base notes",
    "characterLimit": 60,
    "tags": [
      "baseTag1",
      "baseTag2"
    ],
    "integrated": false,
    "variableIds": [
      "name"
    ]
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.