> ## 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 text items
> Returns a list of text items in your workspace. Use the `filter` query param to configure the projects and variants that you would like to include.
## OpenAPI
````yaml openapi.json get /textItems
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:
/textItems:
get:
tags:
- Text Items
summary: Fetch text items
description: >-
Returns a list of text items in your workspace. Use the `filter` query
param to configure the projects and variants that you would like to
include.
parameters:
- schema:
type: string
description: >-
Stringified JSON filter object. Supports the following filter
fields:
- `projects`: array of objects with `id` (project developer ID)
- `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 text items, or `null`
for unassigned
- `integrated`: boolean value to filter by items that are or are
not integrated into development
By default, only base text will be returned. Provide a variants
filter to specify which variants of the filtered base text items
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.
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}`
required: false
description: >-
Stringified JSON filter object. Supports the following filter
fields:
- `projects`: array of objects with `id` (project developer ID)
- `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 text items, or `null`
for unassigned
- `integrated`: boolean value to filter by items that are or are not
integrated into development
By default, only base text will be returned. Provide a variants
filter to specify which variants of the filtered base text items 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.
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}`
name: filter
in: query
- schema:
type: string
enum:
- id
- project_order
description: >-
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.
required: false
description: >-
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.
name: sort
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 text items matching the filter criteria
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The Developer ID of the text item
text:
type: string
description: >-
The plaintext content of the text item. Returns the
variant's text when variantId is not null.
status:
type: string
description: >-
The status of the text item. 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 text item, or
null if unassigned. Returns the variant's assignee when
variantId is not null.
notes:
type: string
description: >-
The notes on the text item. Returns the variant's notes
when variantId is not null.
characterLimit:
type: number
nullable: true
description: >-
The character limit set on this text item, 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 text item. Returns the
base tags value in all responses; variants do not have
their own tags.
integrated:
type: boolean
description: >-
Whether this text item 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
projectId:
type: string
description: >-
The Developer ID of the project this text item belongs
to
blockName:
type: string
nullable: true
description: >-
The name of the block this text item belongs to, or null
if it is not in a block
required:
- id
- text
- status
- assignee
- notes
- characterLimit
- tags
- integrated
- variableIds
- variantId
- pluralForm
- projectId
- blockName
example:
- id: text-item-dev-id
text: Base text
status: NONE
notes: base notes
tags:
- baseTag1
- baseTag2
assignee: john@example.com
integrated: true
variableIds: []
projectId: project-dev-id
variantId: null
blockName: block name
richText: Base text
- id: text-item-dev-id
text: French text
status: WIP
notes: base notes
tags:
- baseTag1
- baseTag2
assignee: john@example.com
integrated: true
variableIds:
- age
- name
projectId: project-dev-id
variantId: french
blockName: block name
richText: French text
- id: another-text-item
text: Some base text
status: FINAL
notes: base notes
tags:
- baseTag1
- baseTag2
assignee: null
integrated: false
variableIds:
- age
- name
projectId: another-project
variantId: null
blockName: null
richText: Some base text
security:
- ApiKeyAuth: []
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````