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.
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.
If you already have a Ditto account, you can create one by doing the following:
Head to your Account Settings
Under "API Keys", click "+ Create 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>'
The Ditto API currently has read-only endpoints to
fetch a list of names of projects that have Developer Mode turned on
fetch copy from a specific Ditto project as a JSON
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.
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. [{"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"},]
<Error message>
Unauthorized
Example Request
curl GET 'https://api.dittowords.com/projects' \--header 'Authorization: token <YOUR_DITTO_API_KEY>'
: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. ditto_component_library to fetch a component library with Developer Mode enabledvariant is specified, text items in the default and structured export formats will not include the variants key.flat or structured. If no format is provided, the full project JSON will be returned.{"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": "[email protected]"},"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.)"}}},}}]
<Error message>
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>'
Developer Mode enabled can be fetched.variant is specified, text items in the default and structured export formats will not include the variants key.flat or structured. If no format is provided, the full project JSON will be returned.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": "[email protected]"},"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": "[email protected]"},"text_609e9981eb133a013f941cf8": {"text": "[email protected]"},"text_609e9981eb133a013f941cfc": {"text": "[email protected]"},"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": "[email protected]"},"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","text": "[email protected]"},"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>'