{ "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/v1" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization" } }, "schemas": {}, "parameters": {} }, "paths": { "/projects": { "get": { "tags": ["Projects"], "description": "Returns a list of Ditto projects. Only projects with Developer Mode enabled can be fetched.", "summary": "Fetch projects", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The projects will return as a JSON Object with each project under it's own project ID in the format project_ as the key in the object.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" } }, "required": ["id", "name", "url"] }, "example": [ { "id": "project_123", "name": "My Project", "url": "https://app.dittowords.com/projects/project_123" } ] } } } } } } }, "/projects/{id}": { "get": { "tags": ["Projects"], "description": "Returns the contents of the Ditto project referred to by :id. You can find the id of a Ditto project from its URL: https://app.dittowords.com/doc/:id. Only projects with Developer Mode enabled can be fetched. ", "summary": "Fetch text by project id", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "The API ID of the variant. If specified, will filter for text items or components that have the variant, and will return the attributes (e.g. text, status) of that text item's or component's variant.", "example": "french" }, "required": false, "description": "The API ID of the variant. If specified, will filter for text items or components that have the variant, and will return the attributes (e.g. text, status) of that text item's or component's variant.", "name": "variant", "in": "query" }, { "schema": { "type": "string", "enum": ["flat", "structured", "nested", "icu", "android", "ios-strings", "ios-stringsdict"], "example": "structured" }, "required": false, "name": "format", "in": "query" }, { "schema": { "type": "string", "enum": ["NONE", "WIP", "REVIEW", "FINAL"], "example": "FINAL" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "boolean" }, "required": false, "name": "includeRichText", "in": "query" }, { "schema": { "type": "boolean" }, "required": false, "name": "exclude_components", "in": "query" }, { "schema": { "type": "boolean" }, "required": false, "name": "includeTimeData", "in": "query" } ], "responses": { "200": { "description": "Returns contents of a project in the flat format", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "login-web-header-login": "Log In", "login-web-formbody-emailaddress": "Email address", "login-web-formbody-namecompanycom": "name@company.com", "login-web-formbody-password": "Password", "login-web-formbody-forgotpassword": "Forgot Password?", "login-web-footer-login": "Log In", "login-web-footer-donthaveanaccount": "Don’t have an account?", "login-web-footer-signup": "Sign Up", "login-mobile-header-login": "Log In", "login-mobile-formbody-emailaddress": "Email address", "login-mobile-formbody-namecompanycom": "name@company.com", "login-mobile-formbody-password": "Password", "login-mobile-formbody-forgotpassword": "Forgot Password?", "login-mobile-footer-login": "Log In", "login-mobile-footer-donthaveanaccount": "Don’t have an account?", "login-mobile-footer-signup": "Sign Up" } } } } } } } }, "/projects/{id}/components": { "get": { "tags": ["Projects"], "description": "Returns the components used in the specified project. Format is identical to the format used by the Fetch components endpoint.", "summary": "Fetch component text by project id", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "The API ID of the variant. If specified, will filter for components that have the variant, and will return the attributes (e.g. text, status) of that component's variant.", "example": "french" }, "required": false, "description": "The API ID of the variant. If specified, will filter for components that have the variant, and will return the attributes (e.g. text, status) of that component's variant.", "name": "variant", "in": "query" }, { "schema": { "type": "string", "enum": ["flat", "structured", "nested", "icu", "android", "ios-strings", "ios-stringsdict"], "example": "structured" }, "required": false, "name": "format", "in": "query" }, { "schema": { "type": "string", "enum": ["NONE", "WIP", "REVIEW", "FINAL"], "example": "FINAL" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "boolean" }, "required": false, "name": "includeRichText", "in": "query" } ], "responses": { "200": { "description": "Returns components a project", "content": { "application/json": { "schema": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] } }, { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folder": { "type": "string", "nullable": true }, "characterLimit": { "type": "number" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } }, "plurals": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "variants": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } }, "plurals": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": ["text", "variables", "plurals"] } } }, "required": ["text"] } } ], "example": { "introduction": { "name": "Introduction", "text": "Welcome to Ditto", "status": "FINAL", "folder": null, "tags": ["HOMEPAGE"], "notes": "Show on the homepage for new users", "variants": {} } } } } } } } } }, "/project-folders": { "get": { "tags": ["Project Folders"], "description": "Returns a list of project folders in the workspace of the requesting user.", "summary": "Fetch project folders", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Returns a list of project folders in the workspace of the requesting user.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "example": [ { "id": "folder_1", "name": "Folder 1" }, { "id": "folder_2", "name": "Folder 2" } ] } } } } } } }, "/project-folders/{folder_id}/projects": { "get": { "tags": ["Project Folders"], "description": "Returns a list of projects in the specified project folder.", "summary": "Fetch projects by project folder id", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "folder_id", "in": "path" } ], "responses": { "200": { "description": "Returns a list of projects in the specified project folder.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": ["id", "name"] }, "example": [ { "id": "project_1", "name": "Project 1" }, { "id": "project_2", "name": "Project 2" } ] } } } } } } }, "/components": { "get": { "tags": ["Components"], "description": "Returns the components in the workspace of the requesting user. Only component libraries with Developer Mode enabled can be fetched.", "summary": "Fetch component text", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The API ID of the variant. If specified, will filter for components that have the variant, and will return the attributes (e.g. text, status) of that component's variant.", "example": "french" }, "required": false, "description": "The API ID of the variant. If specified, will filter for components that have the variant, and will return the attributes (e.g. text, status) of that component's variant.", "name": "variant", "in": "query" }, { "schema": { "type": "string", "enum": ["flat", "structured", "nested", "icu", "android", "ios-strings", "ios-stringsdict"], "example": "structured" }, "required": false, "name": "format", "in": "query" }, { "schema": { "type": "string", "enum": ["NONE", "WIP", "REVIEW", "FINAL"], "example": "FINAL" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "boolean" }, "required": false, "name": "includeRichText", "in": "query" }, { "schema": { "type": "boolean", "description": "Include the `createdAt` and `updatedAt` fields for each component. Only supported for the `structured` format." }, "required": false, "description": "Include the `createdAt` and `updatedAt` fields for each component. Only supported for the `structured` format.", "name": "includeTimeData", "in": "query" } ], "responses": { "200": { "description": "Returns components", "content": { "application/json": { "schema": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] } }, { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folder": { "type": "string", "nullable": true }, "characterLimit": { "type": "number" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } }, "plurals": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "variants": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } }, "plurals": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": ["text", "variables", "plurals"] } } }, "required": ["text"] } } ], "example": { "footer.about.blog": { "name": "Footer/About/Blog", "text": "Blog", "status": "WIP", "folder": null }, "footer.about.careers": { "name": "Footer/About/Careers", "text": "Careers", "status": "FINAL", "folder": "folder_1" } } } } } } } }, "put": { "tags": ["Components"], "description": "Used for updating the text and status fields for components in the workspace of the requesting user.\n\n-> Currently only supports updating variant text or status on components via the variant query parameter (an error will be thrown if the variant param is not specified)\n\n-> Currently only available for teams on team or enterprise plans", "summary": "Update component text variant", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The API ID of the variant.", "example": "french" }, "required": true, "description": "The API ID of the variant.", "name": "variant", "in": "query" }, { "schema": { "type": "string", "enum": ["flat", "structured", "nested"], "example": "structured", "description": "Optional parameter to specify the format of the request body. Passing in this query parameter will validate the request body against the specified format preventing unexpected results if an invalid payload is provided." }, "required": false, "description": "Optional parameter to specify the format of the request body. Passing in this query parameter will validate the request body against the specified format preventing unexpected results if an invalid payload is provided.", "name": "format", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string", "description": "The component variant's text.", "example": "Nom d'utilisateur" }, "status": { "type": "string", "enum": ["NONE", "WIP", "REVIEW", "FINAL"], "example": "FINAL" }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "plurals": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "form": { "type": "string", "enum": ["one", "two", "zero", "few", "many", "other"] } }, "required": ["text", "form"] } } }, "required": ["text"] }, "description": "Object that maps component API IDs to their new attributes.", "example": { "signup_username": { "text": "Nom d'utilisateur", "status": "FINAL" } } } }, "required": ["data"] }, "examples": { "update_components_example": { "value": { "data": { "signup_username": { "text": "Nom d'utilisateur", "status": "FINAL" }, "signup_password": { "text": "Mot de passe" }, "signup_register": { "text": "S'inscrire" } } } } } } } }, "responses": { "200": { "description": "Update/skip counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "componentsUpdated": { "type": "number" }, "componentsSkipped": { "type": "number" } }, "required": ["componentsUpdated", "componentsSkipped"], "example": { "componentsUpdated": 1, "componentsSkipped": 0 } } } } } } } }, "/components/file": { "post": { "tags": ["Components"], "description": "For more information about importing components via a file please see: https://dittov3.notion.site/Importing-JSON-iOS-Android-Files-256cc8865c7a80fe94cdf135631bf8c6. The request body must be of type multipart/form-data.", "summary": "Import components via a file", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The API ID of the folder you want to import components into. If not specified, components will be imported into the root of your component library." }, "required": false, "description": "The API ID of the folder you want to import components into. If not specified, components will be imported into the root of your component library.", "name": "folderId", "in": "query" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "import": { "type": "string", "description": "The absolute path to the file you want to import. Postman and other tools support directly uploading files, but if you're using cURL you'll need to use the `@` prefix, e.g. `curl -F import=@/path/to/file.json`" } } } } } }, "responses": { "200": { "description": "Returns how many components were inserted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "componentsInserted": { "type": "number" }, "firstImportedId": { "anyOf": [ { "type": "string" }, { "nullable": true } ] } }, "required": ["componentsInserted", "firstImportedId"], "example": { "componentsInserted": 3, "firstImportedId": "507f1f77bcf86cd799439011" } } } } } } } }, "/component-folders": { "get": { "tags": ["Components Folders"], "description": "Returns an object of component folders in the requesting user's workspace.", "summary": "Fetch component folders", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Returns component folders", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" }, "example": { "folder_1": "Folder 1", "folder_2": "Folder 2" } } } } } } } }, "/component-folders/{api_id}/components": { "get": { "tags": ["Components Folders"], "description": "Returns the components in the specified folder. Format is identical to the format used by the Fetch components endpoint.", "summary": "Fetch component text by component folder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "api_id", "in": "path" }, { "schema": { "type": "string", "description": "The API ID of the variant. If specified, will filter for components that have the variant, and will return the attributes (e.g. text, status) of that component's variant.", "example": "french" }, "required": false, "description": "The API ID of the variant. If specified, will filter for components that have the variant, and will return the attributes (e.g. text, status) of that component's variant.", "name": "variant", "in": "query" }, { "schema": { "type": "string", "enum": ["flat", "structured", "nested", "icu", "android", "ios-strings", "ios-stringsdict"], "example": "structured" }, "required": false, "name": "format", "in": "query" }, { "schema": { "type": "string", "enum": ["NONE", "WIP", "REVIEW", "FINAL"], "example": "FINAL" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "boolean" }, "required": false, "name": "includeRichText", "in": "query" } ], "responses": { "200": { "description": "Returns a component folder's components", "content": { "application/json": { "schema": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "object", "additionalProperties": { "type": "string" } } ] } }, { "type": "object", "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "text": { "type": "string" }, "status": { "type": "string" }, "notes": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "folder": { "type": "string", "nullable": true }, "characterLimit": { "type": "number" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } }, "plurals": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "variants": { "type": "object", "additionalProperties": { "type": "object", "properties": { "text": { "type": "string" }, "variables": { "type": "object", "additionalProperties": { "type": "object", "properties": {} } }, "plurals": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": ["text", "variables", "plurals"] } } }, "required": ["text"] } } ], "example": { "example_component_1": { "name": "Component Name", "text": "This is some component text", "status": "WIP", "folder": "folder_1" }, "example_component_2": { "name": "Another Component Name", "text": "This is some more component text", "status": "FINAL", "folder": "folder_1" } } } } } } } } }, "/variables": { "get": { "tags": ["Variables"], "description": "Returns the variables in the workspace of the requesting user.", "summary": "Fetch variables", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "A JSON body containing variable information from your workspace, keyed by variable name.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "example": { "anyOf": [ { "type": "number" }, { "type": "string" } ] }, "fallback": { "anyOf": [ { "type": "number" }, { "type": "string" } ] } }, "required": ["example"] }, { "type": "object", "properties": { "example": { "type": "string" }, "fallback": { "type": "string" } }, "required": ["example"] }, { "type": "object", "properties": { "text": { "type": "string" }, "url": { "type": "string" } }, "required": ["text", "url"] }, { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "example": { "user_name": { "example": "Jessica", "fallback": "Ditto user" }, "user_age": { "example": 24, "fallback": 0 }, "help_link": { "text": "Get help", "url": "https://help.com" } } } } } } } } }, "/variants": { "get": { "tags": ["Variants"], "description": "Returns a list of variants in the workspace of the requesting user.", "summary": "Fetch variants", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "boolean" }, "required": false, "name": "showSampleData", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "projectIds", "in": "query" } ], "responses": { "200": { "description": "Variants in your workspace", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "apiID": { "type": "string" } }, "required": ["name", "description", "apiID"] }, "example": [ { "name": "french", "apiID": "french", "description": "" } ] } } } } } } } } }