Ditto API
The Ditto API allows you to read and write information from your Ditto workspace.
The Ditto API currently supports read access of Ditto workspaces and is served over HTTPS. All endpoint URLs have the following base:
https://api.dittowords.com
. To access any Ditto API endpoints, you'll need an API key. You can view, create, and revoke your API keys in your Account Settings.
Each API key is attached to a specific user and can only be used to fetch information from that user's Ditto workspace.
If you already have a Ditto account, you can create an API Key as follows:
- 1.
- 2.Under the section titled API Keys, click + Create key.

The User tab under the Account Settings page.
To use your API key to make a request to the Ditto API, you'll need to pass it in an
Authorization
header in all requests: 'Authorization: token <YOUR_API_KEY>'
Here's an example request to Ditto's
/project-names
endpoint:curl -X GET \
--header 'Authorization: token <YOUR_API_KEY>' \
'https://api.dittowords.com/project-names'
Only projects that have Developer Mode enabled are accessible via the API. Learn more about Developer Mode here.
Our API is most often used to integrate Ditto directly into development, and the needs of Ditto users often vary according to the type of application they're building and the ways in which their development toolchains are configured.
To support diverse workflows, API endpoints that return text data can be configured to return that data in a variety of formats.
If you're unsure whether or not a given endpoint supports different formats, please see the endpoint reference below.
This is the default format that is returned if no
format
parameter is specified.The full format has been deprecated and is NOT recommended for integration into development. It will be removed in future API versions.
Content-Type: text/json
{
{
"project_id": "[ID OF PROJECT",
"exported_at": "[UTC TIME OF EXPORT]",
"frames": {
"[FRAME ID]": {
"frame_name": "[NAME OF FRAME]",
"blocks": {
{
"[BLOCK ID]": {
"[TEXT ID]": {
"text": "[TEXT OF TEXT ITEM]",
"status": "[STATUS OF TEXT ITEM]", // optional
"notes": "[NOTES OF TEXT ITEM]", // optional
"variables": {
"[VARIABLE NAME]": {
... // variable properties: example, fallback, etc
}
},
"plurals": { // optional: only if plurals are enabled for text
"zero": "[TEXT FOR ZERO FORM]", // optional: depends on plural form being configured
"few": "[TEXT FOR FEW FORM]", // optional: depends on plural form being configured
"many": "[TEXT FOR MANY FORM]", // optional: depends on plural form being configured
"other": "[TEXT FOR OTHER FORM]", // optional: depends on plural form being configured
},
"tags": [ ... ], // optional: array of strings
"variants": { // optional: only present if text has variant values
"[VARIANT ID]": {
"text": "[TEXT OF VARIANT]",
"variables": { ... } // see previous `variables` property,
"plurals": { ... } // see previous `plurals` property
}
}
},
"[TEXT ID]": { ... }
}
},
"[BLOCK ID]": { ... }
},
"otherText": [ // text not in blocks
"[TEXT ID]": {
"text": "[TEXT OF TEXT ITEM]",
"status": "[STATUS OF TEXT ITEM]", // optional
"notes": "[NOTES OF TEXT ITEM]", // optional
"tags": [ ... ], // see previous `tags` property
"variants": { ... } // see previous `variants` property
},
"[TEXT ID]": { ... }
]
},
"[FRAME ID]": { ... },
...
}
}
}
Content-Type: text/json
{
"[TEXT ID]": {
"text": "[TEXT OF TEXT ITEM]",
"status": "[STATUS OF TEXT ITEM]", // optional
"notes": "[NOTES OF TEXT ITEM]", // optional
"tags": [ ... ], // optional: array of strings
"variables": {
"[VARIABLE NAME]": {
... // variable properties: example, fallback, etc
}
},
"plurals": { // optional: only if plurals are enabled for text
"zero": "[TEXT FOR ZERO FORM]", // optional: depends on plural form being configured
"few": "[TEXT FOR FEW FORM]", // optional: depends on plural form being configured
"many": "[TEXT FOR MANY FORM]", // optional: depends on plural form being configured
"other": "[TEXT FOR OTHER FORM]", // optional: depends on plural form being configured
},
"variants": { // optional: only present if text has variant values
"[VARIANT ID]": {
"text": "[TEXT OF VARIANT]",
"variables": { ... } // see previous `variables` property,
"plurals": { ... } // see previous `plurals` property
}
},
"[TEXT ID]": { ... },
...
}
- Text items with plural values will have those plural values included in the output as individual key/value pairs; pluralized keys are structured like
"[TEXT ID]_[PLURAL FORM]"
.
Content-Type: text/json
{
"[TEXT ID]": "[TEXT OF TEXT ITEM]",
"[TEXT ID]": "[TEXT OF TEXT ITEM]",
"[TEXT ID]_[PLURAL FORM]": "[TEXT OF PLURAL FORM]",
...
}
- Text items in Ditto are mapped to
<string>
tags and givenname
values that correspond to a given text item's API ID with-
characters replaced with_
. An additionalditto_api_id
field is also added with the original api id. - Variables in Ditto are mapped to
<xliff:g>
tags and givenid
andexample
values that correspond to a given variable's name andexample
values, respectively. - A text item with plurals will have a
<plurals>
tag generated for it, along with an<item>
for each plural form that is configured in Ditto (note:<item id="other">
will always be generated). Plural items also support variables via<xliff:g>
tags.
Although an example is shown below, please see the Android strings documentation and the Android localization documentation for a complete reference.
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
<string name="welcome_text" ditto_api_id="welcome-text">Welcome to the app!</string>
<string name="logout" ditto_api_id="logout">Logout</string>
</resources>
This format corresponds to the iOS .strings files that can be used for localization, documented here.
- Notes associated with text items will be included as comments above a given key value pair
- Variables in text items will be replaced with interpolation placeholders with a string format specifier
Content-Type: text/plain
"welcome-text" = "Welcome!";
/* This should only be used on the logout screen */
"logout" = "Logout";
get
https://api.dittowords.com
/project-names
Fetch project names
get
https://api.dittowords.com
/projects
Fetch projects
get
https://api.dittowords.com
/projects/:id
Fetch project by ID
get
https://api.dittowords.com
/projects/:id/components
Fetch components by project
get
https://api.dittowords.com
/components
Fetch components
put
https://api.dittowords.com
/components
Update components
get
https://api.dittowords.com
/component-folders
Fetch component folders
get
https://api.dittowords.com
/component-folders/:api_id/components
Fetch components by component folder
get
https://api.dittowords.com
/variables
Fetch variables
get
https://api.dittowords.com
/variants
Fetch variants
{
"[API ID]": {
"text": "[TEXT OF TEXT ITEM (CAN INCLUDE VARIABLES)]",
"notes": "[NOTES OF TEXT ITEM]", // optional
"tags": [ ... ], // optional: array of strings
"plurals": [ // optional: array of plural objects
{
"text": "[TEXT OF PLURAL FORM]",
"form": "[one|two|zero|few|many|other]"
}
]
}
}
Last modified 3d ago