> ## 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.
# Fetch components
> Returns a list of components in your workspace. Use the `filter` query param to configure the folders and variants that you would like to include.
## 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. Use the `filter` query
param to configure the folders and variants that you would like to
include.
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`)
- `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`)
- `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.
status:
type: string
description: >-
The status of the component. Returns the variant's
status when variantId is not null.
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.
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
richText:
type: string
description: >-
HTML-formatted version of the text content. Only
included when richText=html query parameter is provided
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
required:
- id
- text
- status
- assignee
- notes
- characterLimit
- tags
- integrated
- variableIds
- variantId
- pluralForm
- folderId
- name
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
````