Components

Fetch components

Returns a list of components in your workspace.

get/components

Request

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

Query parameters

filterstring

Stringified JSON filter object. Supports the following filter fields:

  • folders: array of objects with id (folder developer ID or root for root-level components) and optional excludeNestedFolders (boolean)
  • 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 components, or null for unassigned
  • integrated: boolean value to filter by components that are or are not marked as integrated into development

By default, only base text will be returned. Provide a variants filter to specify which variants of the filtered components to include.

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.

By default, folder filters search for components in that folder and its folder children. To skip searching folder children for a given folder, set excludeNestedFolders to true.

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

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 components matching the filter criteria

idstring required

The Developer ID of the component

textstring required

The plaintext content of the component. Returns the variant's text when variantId is not null.

richTextstring

If a richText parameter is provided, this field contains the HTML-formatted version of the text, generated according to the specified format option. Not present if richText is omitted.

notesstring required

The notes on the component. Returns the variant's notes when variantId is not null.

characterLimitnumber nullable required

The character limit set on this component, or null if no limit is set. Returns the variant's character limit when variantId is not null.

tagsstring[] required

Array of tags associated with the component. Returns the base tags value in all responses; variants do not have their own tags.

integratedboolean required

Whether this component has been marked as integrated into development

variableIdsstring[] required

Array of Developer IDs of variables used in this base or variant text

variantIdstring nullable required

The Developer ID of this variant, or null for base text

pluralForm'one' | 'two' | 'few' | 'many' | 'zero' | 'other' | 'null' nullable required
folderIdstring nullable required

The Developer ID of the folder this component belongs to

namestring required

The name of the component

statusstring required

The status of the component. Returns the variant's status when variantId is not null. 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).

assigneestring email nullable required

The email of the user assigned to this component, or null if unassigned. Returns the variant's assignee when variantId is not null.

Example response

[
  {
    "id": "component-item-dev-id",
    "name": "Component Name",
    "text": "Base text",
    "status": "NONE",
    "notes": "base notes",
    "tags": [
      "baseTag1",
      "baseTag2"
    ],
    "assignee": "john@example.com",
    "integrated": true,
    "variableIds": [],
    "folderId": "folder-dev-id",
    "variantId": null,
    "richText": "<strong>Base</strong> text"
  },
  {
    "id": "component-item-dev-id",
    "name": "Component Name",
    "text": "French text",
    "status": "WIP",
    "notes": "base notes",
    "tags": [
      "baseTag1",
      "baseTag2"
    ],
    "assignee": "john@example.com",
    "integrated": true,
    "variableIds": [
      "age",
      "name"
    ],
    "folderId": "folder-dev-id",
    "variantId": "french",
    "richText": "<em>French</em> text"
  },
  {
    "id": "component-item-dev-id-2",
    "name": "Component Name 2",
    "text": "Some base text",
    "status": "FINAL",
    "notes": "base notes",
    "tags": [
      "baseTag1",
      "baseTag2"
    ],
    "assignee": null,
    "integrated": false,
    "variableIds": [
      "age",
      "name"
    ],
    "folderId": null,
    "variantId": null,
    "richText": "Some <strong>base</strong> text"
  }
]

Changes

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