API Reference

The Ditto API allows you to fetch information from your Ditto projects.

Overview

In addition to being used by the CLI, you can also use our API directly.

The Ditto API currently supports read access of Ditto projects and is served over HTTPS. All endpoint URLs have the following base: https://api.dittowords.com.

Authentication

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 projects in that user's Ditto workspace.

Creating an API key

If you already have a Ditto account, you can create one by doing the following:

  1. Head to your Account Settings

  2. Under "API Keys", click "+ Create key"

Using an API key

To use your API key to make a request to the Ditto API, you'll need to pass it as a request header:

'Authorization: token <YOUR_API_KEY>'

Here's an example request to Ditto's /projects endpoint:

curl GET 'https://api.dittowords.com/projects' \
--header 'Authorization: token <YOUR_API_KEY>'

Endpoints

The Ditto API currently has two read-only endpoints to

  1. fetch a list of projects in your Ditto workpace and

  2. fetch copy as a structured JSON from a specific Ditto project.

Only projects that have Developer Mode enabled are accessible via the API. Learn more about Developer Mode here.

get
List projects

https://api.dittowords.com/projects
Returns a list of projects that have Developer Mode enabled in your Ditto workspace.
Request
Response
Request
Headers
Authorization
required
string
"token <YOUR_DITTO_API_KEY"
Response
200: OK
[
{
"id": "6037e51dcf85c100ae85524e",
"name": "Onboarding Flow",
"url": "https://beta.dittowords.com/doc/6037e51dcf85c100ae85524e"
},
{
"id": "602488f69971b04cdd60e194",
"name": "Pricing Flow",
"url": "https://beta.dittowords.com/doc/602488f69971b04cdd60e194"
},
{
"id": "6037149755dbc100b15cb533",
"name": "Billing Modal Updates",
"url": "https://beta.dittowords.com/doc/6037149755dbc100b15cb533"
},
]
400: Bad Request
<Error message>
401: Unauthorized
API key is invalid or missing from request.
Unauthorized

Example Request

curl GET 'https://api.dittowords.com/projects' \
--header 'Authorization: token <YOUR_DITTO_API_KEY>'

get
Fetch project content

https://api.dittowords.com/projects/:id
Returns the contents of the Ditto project referred to by :id as a structured JSON. Only projects that have Developer Mode enabled can be fetched. You can find the id of a Ditto project from its URL: https://beta.dittowords.com/doc/:id.
Request
Response
Request
Path Parameters
id
required
string
Id of Ditto project you're fetching
Headers
Authorization
required
string
"token <YOUR_DITTO_API_KEY"
Response
200: OK
Returns contents of a project as a structured JSON, with unique IDs for every frame, block, and string. You can view and edit these IDs in the Ditto web app.
{
"project_name": "Onboarding Flow",
"frames": {
"welcome": {
"frameName": "Welcome",
"blocks": {},
"otherText": {
"text_6024cb5c57023a00a2ca884e": {
"text": "Continue",
"tags": [
"WELCOME_CTA"
]
},
"text_6024cb5c57023a00a2ca8851": {
"text": "What is your work email address?",
"tags": [
"BODY",
"ENGLISH"
]
},
"text": {
},
"text_6024cb5c57023a00a2ca8853": {
"text": "Continue",
"tags": [
"CTA",
"ONBOARDING"
],
"is_comp": true,
"notes": "Should be used in any funnels in the app (onboarding, upgrade, etc.)"
}
}
},
"frame_6024cb5c57023a00a2ca8891": {
"frameName": "Pricing",
"blocks": {
"headings": {
"text_6024cb5c57023a00a2ca8856": {
"text": "Pick your pricing plan.",
"status": "REVIEW",
"tags": [
"ONBOARDING"
],
"notes": "a note!"
},
"text_6024cb5c57023a00a2ca8857": {
"text": "If you have any questions regarding pricing, please visit our detailed pricing page. ",
"status": "REVIEW"
}
},
"form": {
"text_6024cb5c57023a00a2ca8858": {
"text": "Basic",
"status": "REVIEW"
},
"text_6024cb5c57023a00a2ca885a": {
"text": "$48",
"status": "REVIEW"
}
},
"buttons": {
"text_6024cb5c57023a00a2ca8854": {
"text": "Continue",
"status": "REVIEW"
}
}
},
"otherText": {
"text_6024cb5c57023a00a2ca8855": {
"text": "Step 2 of 4"
},
"text_6024cb5c57023a00a2ca8859": {
"text": "Our Basic Plan provides integrations with Slack and WhatsApp."
},
"text_6024cb5c57023a00a2ca885b": {
"text": "Team"
},
"text_6024cb5c57023a00a2ca885c": {
"text": "Our Team Plan includes everything in the Basic Plan, in addition to unlimited messages between members of your workspace."
},
"text_6024cb5c57023a00a2ca885d": {
"text": "$98"
},
"text_6024cb5c57023a00a2ca885e": {
"text": "Continue",
"tags": [
"CTA",
"ONBOARDING"
],
"is_comp": true,
"notes": "Should be used in any funnels in the app (onboarding, upgrade, etc.)"
}
}
},
}
}
]
400: Bad Request
<Error message>
403: Forbidden
The requested project doesn't have Developer Mode enabled. Learn more about Developer Mode at: https://dittowords.com/docs/ditto-developer-mode.
Project doesn't have Developer Mode enabled

Example Request

curl GET 'https://api.dittowords.com/projects/<DITTO_PROJECT_ID>' \
--header 'Authorization: token <YOUR_DITTO_API_KEY>'

You can find more information on how IDs are generated and how you can edit them here.