Text Items

Link Figma nodes to a text item

Links one or more Figma text nodes to an existing text item in a Figma-linked project, so those nodes become Figma instances of that text item.

The nodes must already have been synced to Ditto through the Ditto Figma plugin. Pass figma.branchId to link nodes inside a branch file; without it, nodes are looked up in the project's main Figma file.

The link is recorded in Ditto right away, but Ditto writes to a Figma file only from the plugin. So the Figma layer doesn't reflect the link — and later edits to the text item don't reach that layer — until someone next opens the Ditto Figma plugin on the file.

Nodes are handled independently rather than all-or-nothing: the response reports an outcome per node ID — linked, already_linked, not_found (sync the file from the plugin, then retry), not_text_node, wrong_file_or_branch, or main_component_text_node (link instance text nodes directly, or link the main component's text from the Figma plugin).

post/textItems/linkFigmaNodes

Request

  • Base URL: https://api.dittowords.com/v2
  • URL: https://api.dittowords.com/v2/textItems/linkFigmaNodes
  • Auth: API key in header Authorization

Request body

projectIdstring required

Developer ID of the Ditto project linked to the Figma file containing these nodes.

textItemIdstring required

Developer ID of the existing Ditto text item to link these Figma nodes to.

Example request

{
  "projectId": "project-id-1",
  "textItemId": "greeting",
  "figma": {
    "nodeIds": [
      "1:23",
      "1:24"
    ],
    "branchId": null
  }
}

Response

Returns the resolved project, text item, and branch context, plus 1 result per distinct Figma node ID

projectIdstring required
textItemIdstring required
branchIdstring nullable required

Example response

{
  "projectId": "project-id-1",
  "textItemId": "greeting",
  "branchId": null,
  "results": [
    {
      "figmaNodeId": "1:23",
      "outcome": "linked",
      "linkedTextItemId": "greeting"
    },
    {
      "figmaNodeId": "1:24",
      "outcome": "not_found",
      "message": "This Figma text node is not in the cache for the target project context. Sync first, then retry."
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.