> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt
> Use this file to discover all available pages before exploring further.
> ## 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.
# Fetch components
> Returns a list of components in your workspace.
## OpenAPI
````yaml openapi.json get /components
openapi: 3.0.0
info:
version: 1.0.0
title: Ditto API
description: Programmatically read and write data in your Ditto workspace.
servers:
- url: https://api.dittowords.com/v2
security: []
paths:
/components:
get:
tags:
- Components
summary: Fetch components
description: Returns a list of components in your workspace.
parameters:
- schema:
type: string
description: >-
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}`
required: false
description: >-
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}`
name: filter
in: query
- schema:
type: string
enum:
- html
description: >-
When set to 'html', includes HTML-formatted rich text in the
response
required: false
description: >-
When set to 'html', includes HTML-formatted rich text in the
response
name: richText
in: query
responses:
'200':
description: Returns an array of components matching the filter criteria
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The Developer ID of the component
text:
type: string
description: >-
The plaintext content of the component. Returns the
variant's text when variantId is not null.
richText:
type: string
description: >-
HTML-formatted version of the text content. Only
included when richText=html query parameter is provided
notes:
type: string
description: >-
The notes on the component. Returns the variant's notes
when variantId is not null.
characterLimit:
type: number
nullable: true
description: >-
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:
type: array
items:
type: string
description: >-
Array of tags associated with the component. Returns the
base tags value in all responses; variants do not have
their own tags.
integrated:
type: boolean
description: >-
Whether this component has been marked as integrated
into development
variableIds:
type: array
items:
type: string
description: >-
Array of Developer IDs of variables used in this base or
variant text
variantId:
type: string
nullable: true
description: The Developer ID of this variant, or null for base text
pluralForm:
type: string
nullable: true
enum:
- one
- two
- few
- many
- zero
- other
- null
folderId:
type: string
nullable: true
description: The Developer ID of the folder this component belongs to
name:
type: string
description: The name of the component
status:
type: string
description: >-
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).
assignee:
type: string
nullable: true
format: email
description: >-
The email of the user assigned to this component, or
null if unassigned. Returns the variant's assignee when
variantId is not null.
required:
- id
- text
- notes
- characterLimit
- tags
- integrated
- variableIds
- variantId
- pluralForm
- folderId
- name
- status
- assignee
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: Base 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: French 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 base text
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.