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 read-only endpoints to

  1. fetch a list of names of projects that have Developer Mode turned on

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

  3. fetch copy from several projects as a JSON

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

get
List project names

https://api.dittowords.com/project-names
Returns a list of names of projects that have Developer Mode enabled in your Ditto workspace. If you have Developer Mode enabled for your workspace's Component Library, the Component Library will also be included in this list.
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 by ID

https://api.dittowords.com/projects/:id
Returns the contents of the Ditto project referred to by :id as a structured JSON. You can find the id of a Ditto project from its URL: https://beta.dittowords.com/doc/:id. If you want to fetch the JSON of your component library, you can use the ID ditto_component_library. Only projects with Developer Mode enabled can be fetched.
Request
Response
Request
Path Parameters
id
required
string
ID of Ditto project you're fetching or ditto_component_library to fetch a component library with Developer Mode enabled
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>'

get
Fetch projects

https://api.dittowords.com/projects
Returns the contents of multiple Ditto projects based on the provided project IDs. The ID's of Only projects with Developer Mode enabled can be fetched.
Request
Response
Request
Headers
Authorization
required
string
"token <YOUR_DITTO_API_KEY"
Query Parameters
projectIds
required
array
Array of project IDs to be fetched
Response
200: OK
The projects will return as a JSON Object with each project under it's own project ID in the format project_<DITTO_PROJECT_ID> as the key in the object.
{
"projects": {
"project_609e9981c313f8018d0c346a": {
"project_name": "NUX Onboarding Flow",
"frames": {
"frame_609e9981eb133a013f941ce0": {
"frameName": "Welcome",
"blocks": {
"heading_": {
"text_609e9981eb133a013f941ce3": {
"text": "Setting up your account should take less than 10 minutes."
},
"text_609e9981eb133a013f941ce2": {
"text": "Let’s get you set up!",
"status": "REVIEW",
"tags": [
"H1",
"ONBOARDING"
],
"notes": "Onboarding header, should be a single line"
}
}
},
"otherText": {
"text_609e9981eb133a013f941ce4": {
"text": "What is your work email address?"
},
"text_609e9981eb133a013f941ce5": {
},
"text_609e9981eb133a013f941ce6": {
"text": "This will be the email address you use to access your account."
},
"text_609e9981eb133a013f941ce1": {
"text": "Next",
"status": "FINAL",
"tags": [
"CTA"
]
}
}
},
"frame_609e9981eb133a013f941ce7": {
"frameName": "Pricing",
"blocks": {},
"otherText": {
"text_609e9981eb133a013f941ce9": {
"text": "Step 2 of 4"
},
"text_609e9981eb133a013f941cea": {
"text": "Pick your pricing plan."
},
"text_609e9981eb133a013f941ceb": {
"text": "If you have any questions regarding pricing, please visit our detailed pricing page. "
},
"text_609e9981eb133a013f941cec": {
"text": "Basic"
},
"text_609e9981eb133a013f941ced": {
"text": "Choose your pricing plan!",
"tags": [
"PRICING"
],
"is_comp": true,
"notes": "line 1\n\"line 2\"\nline 3"
},
"text_609e9981eb133a013f941cee": {
"text": "$48"
},
"text_609e9981eb133a013f941cef": {
"text": "Team"
},
"text_609e9981eb133a013f941cf0": {
"text": "Our Team Plan includes everything in the Basic Plan, in addition to unlimited messages between members of your workspace."
},
"text_609e9981eb133a013f941cf1": {
"text": "$98"
},
"text_609e9981eb133a013f941cf2": {
"text": "<- Back"
},
"text_609e9981eb133a013f941ce8": {
"text": "Next",
"status": "FINAL",
"tags": [
"CTA"
]
}
}
},
"frame_609e9981eb133a013f941cf3": {
"frameName": "Invite",
"blocks": {},
"otherText": {
"text_609e9981eb133a013f941cf5": {
"text": "Step 3 of 4"
},
"text_609e9981eb133a013f941cf6": {
"text": "Invite your teammates."
},
"text_609e9981eb133a013f941cf7": {
"text": "They’ll receive an email with more instructions to join you here."
},
"text_609e9981eb133a013f941cf9": {
},
"text_609e9981eb133a013f941cf8": {
},
"text_609e9981eb133a013f941cfc": {
},
"text_609e9981eb133a013f941cfa": {
"text": "Skip"
},
"text_609e9981eb133a013f941cf4": {
"text": "Next",
"status": "FINAL",
"tags": [
"CTA"
]
},
"text_609e9981eb133a013f941cfb": {
"text": "<- Back"
}
}
},
"frame_609e9981eb133a013f941d05": {
"frameName": "Welcome",
"blocks": {},
"otherText": {
"text_609e9981eb133a013f941d07": {
"text": "Welcome back!"
},
"text_609e9981eb133a013f941d08": {
"text": "Setting up your account should take less than 10 minutes."
},
"text_609e9981eb133a013f941d09": {
"text": "What is your work email address?"
},
"text_609e9981eb133a013f941d0a": {
},
"text_609e9981eb133a013f941d0b": {
"text": "This will be the email address you use to access your account."
},
"text_609e9981eb133a013f941d0c": {
"text": "Skip"
},
"text_609e9981eb133a013f941d06": {
"text": "Next",
"status": "FINAL",
"tags": [
"CTA"
]
}
}
},
"frame_609e9981eb133a013f941d0d": {
"frameName": "Pricing",
"blocks": {},
"otherText": {
"text_609e9981eb133a013f941d0f": {
"text": "Step 2 of 4"
},
"text_609e9981eb133a013f941d10": {
"text": "Pick your pricing plan."
},
"text_609e9981eb133a013f941d11": {
"text": "If you have any questions regarding pricing, please visit our detailed pricing page. "
},
"text_609e9981eb133a013f941d12": {
"text": "Our Basic Plan provides integrations with Slack and WhatsApp."
},
"text_609e9981eb133a013f941d13": {
"text": "Basic"
},
"text_609e9981eb133a013f941d14": {
"text": "$48"
},
"text_609e9981eb133a013f941d16": {
"text": "Team"
},
"text_609e9981eb133a013f941d17": {
"text": "Our Team Plan includes everything in the Basic Plan, plus unlimited messages."
},
"text_609e9981eb133a013f941d15": {
"text": "Skip"
},
"text_609e9981eb133a013f941d18": {
"text": "$98"
},
"text_609e9981eb133a013f941d19": {
"text": "<- Back"
},
"text_609e9981eb133a013f941d0e": {
"text": "Next",
"status": "FINAL",
"tags": [
"CTA"
]
},
"text_609e9981eb133a013f941d1a": {
"text": "Skip"
}
}
},
"frame_609e99fc55c15d00e4f15068": {
"frameName": "[[M]]Confirm",
"blocks": {},
"otherText": {
"text_609e9981eb133a013f941cff": {
"text": "Step 4 of 4"
},
"text_609e9981eb133a013f941d00": {
"text": "You’re almost done!"
},
"text_609e9981eb133a013f941d01": {
"text": "Check your email for a confirmation and invoice. "
},
"text_609e9981eb133a013f941d02": {
"text": "Your invoice will be billed monthly, and new members will be prorated."
},
"text_609e9981eb133a013f941d03": {
"text": "Thank you for signing up!"
},
"text_609e9981eb133a013f941cfe": {
"text": "Finish"
},
"text_609e9981eb133a013f941d04": {
"text": "<- Back"
}
}
},
"frame_609e99fc55c15d00e4f15069": {
"frameName": "[[I]]Confirm",
"blocks": {},
"otherText": {
"text_609e99fc55c15d00e4f1506b": {
"text": "Step 4 of 4"
},
"text_609e99fc55c15d00e4f1506c": {
"text": "You’re almost done!"
},
"text_609e99fc55c15d00e4f1506d": {
"text": "Check your email for a confirmation and invoice. "
},
"text_609e99fc55c15d00e4f1506e": {
"text": "Your invoice will be billed monthly, and new members will be prorated."
},
"text_609e99fc55c15d00e4f1506f": {
"text": "Thank you for signing up!"
},
"text_609e99fc55c15d00e4f1506a": {
"text": "Finish"
},
"text_609e99fc55c15d00e4f15070": {
"text": "<- Back"
}
}
}
}
},
"ditto_component_library": {
"project_name": "Ditto Component Library",
"component": {
"placeholderemail": {
"name": "1email",
},
"bestpracticeserrormessageserror1": {
"name": "Best practices/error 1",
"text": "best practice error!"
},
"billing_invoicing_choose_pricing": {
"name": "Billing/Enterprise/Choose pricing",
"text": "Choose your pricing plan!",
"notes": "line 1\n\"line 2\"\nline 3",
"tags": [
"PRICING"
]
},
"cta_onboarding_proceed": {
"name": "Billing/Enterprise/Proceed",
"text": "Proceed now",
"notes": "proceed message for onboarding"
},
"billinginvoicingdisclaimer": {
"name": "Billing/Invoicing/Disclaimer",
"text": "If you have any questions regarding pricing, please visit our detailed pricing page. "
},
"billing_legal_invoice_info": {
"name": "Billing/invoice_info",
"text": "Your invoice is billed monthly and new members will be prorated",
"notes": "Approved by legal",
"tags": [
"LEGAL_TEXT",
"PRICING"
]
},
"billing_team_plan_price": {
"name": "Billing/price",
"text": "$50/mo.",
"notes": "Heading during onboarding flow step 2",
"tags": [
"H2",
"ONBOARDING"
]
},
"cta": {
"name": "CTA",
"text": "Got it, thanks!"
},
"billing_invoicing_prorate_disclaimer": {
"name": "CTA/Prorate Disclaimer",
"text": "Your invoice is billed monthly and new members will be prorated. Check your email for a confirmation message!"
},
"cta_mobile_consumer12": {
"name": "CTA/consumer",
"text": "let's go, {{First Name}}!",
"notes": "Call-to-action used everywhere!",
"tags": [
"CTA",
"H1"
]
},
"cta_mobile_next": {
"name": "CTA/next",
"text": "Continue!",
"notes": "Should be used in any funnels in the app (onboarding, upgrade, etc.)",
"tags": [
"CTA",
"ONBOARDING"
]
},
"cta_input_validation": {
"name": "CTA/validation",
"text": "Enter your validation text!",
"tags": [
"BODY"
]
},
"test_test": {
"name": "Checkout/Confirmation",
"text": "Checkout success",
"notes": "Toast",
"tags": [
"NOTIF"
]
},
"checkout_pricing_pricing_plan": {
"name": "Checkout/Pricing plan",
"text": "Pick your pricing plan.",
"tags": [
"PRICING"
]
},
"client1errormessageserror1": {
"name": "Client 1/error 1",
"text": "some error1"
},
"createred-test": {
"name": "Create \"red-test\"",
"text": "Red"
},
"modal_choose_pricing_message": {
"name": "Development/Choose Pricing Message",
"text": "Please choose your plan from the options below. Thanks!",
"notes": "Message for pricing modal",
"tags": [
"PRICING"
]
},
"modal_setup_component_name": {
"name": "Development/Component name",
"text": "test name"
},
"modal_nux_welcome": {
"name": "Development/NUX Welcome",
"text": "Welcome! Let’s get your team's account set up. ",
"notes": "first message user sees in onboarding ",
"tags": [
"HEADER",
"H1"
]
},
"development_integrations": {
"name": "Development/integrations",
"text": "Our basic plan provides integrations with Slack and WhatsApp. For additional integrations, please contact us at [email protected]",
"notes": "Note about the integrations we provide",
"tags": [
"SUPPORT"
]
},
"modal_setup_placeholder_text": {
"name": "Development/test",
"text": "Placeholder dfksdf",
"notes": "Should be sample input value.",
"tags": [
"FORM",
"INPUT"
]
},
"error": {
"name": "Error",
"text": "error message"
},
"modal_setup_onboarding_time_disclaimer": {
"name": "Modal/Onboarding time disclaimer",
"text": "Setting up your account should take less than 10 minutes."
},
"newcomponentprice": {
"name": "New Component Price",
"text": "$90"
},
"new_comp": {
"name": "New comp",
"text": "some text"
},
"onboarding_draft_component": {
"name": "Onboarding",
"text": "Sample component text"
},
"onboardingnewtext": {
"name": "Onboarding/new text",
"text": "This will give users access to the project! xxxxxxx",
"tags": [
"MODAL",
"BODY"
]
},
"placeholdersaddress": {
"name": "Placeholder/address",
"text": "123 main street",
"tags": [
"FORM"
]
},
"placeholdersusaddress": {
"name": "Placeholder/us address",
"text": "123 main street"
},
"null": {
"name": "Sample text",
"text": "text here"
},
"testcase": {
"name": "Test Case",
"text": "Page 1 Frame 1 Text 1",
"notes": "testing comp"
},
"test-1": {
"name": "Test!",
"text": "test1"
},
"testgrapefruit": {
"name": "Test/grapefruit",
"text": "grapefruit"
},
"testtest-1": {
"name": "TestTest",
"text": "s"
},
"component_draft": {
"name": "component draft",
"text": "draft text"
},
"testteee1": {
"name": "newblock/testteee",
"text": "Next!!",
"tags": [
"CTA"
]
},
"onboardingmessage": {
"name": "onboarding/message",
"text": "This will be the email address you use to access your account."
},
"placeholderphonenumber": {
"name": "placeholder/phone number",
"text": "123 4567"
},
"pricing_v2": {
"name": "pricing v2",
"text": "Choose your pricing plan. Thanks!"
},
"testtest-3": {
"name": "tEstTest",
"text": "te"
},
"test": {
"name": "test",
"text": "You’re almost done."
},
"testtest-2": {
"name": "test TeST",
"text": "Modal header",
"notes": "notes!",
"tags": [
"ONBOARDING"
]
},
"test-9999": {
"name": "test-9999",
"text": "Button\nsdf\nsdf",
"notes": "test\nmuilt\nsdf\n\"dtsdf\"\nsdf sfd \"sdfsdf\""
},
"test_23-1": {
"name": "test_23",
"text": "Page 2 Frame 1 Text 1"
},
"testasdfa-1": {
"name": "testasdfa",
"text": "fsdfadsf"
},
"xav-test-10": {
"name": "xav-test-10",
"text": "some test"
}
}
}
}
}
curl GET 'https://api.dittowords.com/projects?projectIds[]=<DITTO_PROJECT_ID>,<DITTO_PROJECT_ID>' \
--header 'Authorization: token <YOUR_DITTO_API_KEY>'