Skip to main content
GET
/
components
Fetch components
curl --request GET \
  --url https://api.dittowords.com/v2/components \
  --header 'Authorization: <api-key>'
[
  {
    "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"
  }
]

Authorizations

​
Authorization
string
header
required

Query Parameters

​
filter
string

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)
  • 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
enum<string>

When set to 'html', includes HTML-formatted rich text in the response

Available options:
html

Response

200 - application/json

Returns an array of components matching the filter criteria

​
id
string
required

The Developer ID of the component

​
text
string
required

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

​
status
string
required

The status of the component. Returns the variant's status when variantId is not null.

​
assignee
string<email> | null
required

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

​
notes
string
required

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

​
characterLimit
number | null
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.

​
tags
string[]
required

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

​
integrated
boolean
required

Whether this component has been marked as integrated into development

​
variableIds
string[]
required

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

​
variantId
string | null
required

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

​
pluralForm
enum<string> | null
required
Available options:
one,
two,
few,
many,
zero,
other,
null
​
folderId
string | null
required

The Developer ID of the folder this component belongs to

​
name
string
required

The name of the component

​
richText
string

HTML-formatted version of the text content. Only included when richText=html query parameter is provided

Example:
[
  {
    "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"
  }
]