> ## Documentation Index > Fetch the complete documentation index at: https://developer.dittowords.com/llms.txt > Use this file to discover all available pages before exploring further. # 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). ## OpenAPI ````yaml openapi.json post /textItems/linkFigmaNodes 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/v2 security: [] paths: /textItems/linkFigmaNodes: post: tags: - Text Items summary: Link Figma nodes to a text item description: >- 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). requestBody: content: application/json: schema: type: object properties: projectId: type: string description: >- Developer ID of the Ditto project linked to the Figma file containing these nodes. textItemId: type: string description: >- Developer ID of the existing Ditto text item to link these Figma nodes to. figma: type: object properties: nodeIds: type: array items: type: string minItems: 1 maxItems: 50 description: Figma text node IDs to link. Max 50 per request. branchId: type: string nullable: true description: >- Provide the Figma branch ID (obtained from the branch file's Figma URL) of the branch file linked to Ditto, to link nodes within that branch file. If omitted, the file searched for linking will always be the main Figma file. required: - nodeIds description: Figma nodes and branch context to link. required: - projectId - textItemId - figma example: projectId: project-id-1 textItemId: greeting figma: nodeIds: - '1:23' - '1:24' branchId: null responses: '200': description: >- Returns the resolved project, text item, and branch context, plus 1 result per distinct Figma node ID content: application/json: schema: type: object properties: projectId: type: string textItemId: type: string branchId: type: string nullable: true results: type: array items: type: object properties: figmaNodeId: type: string outcome: type: string enum: - linked - already_linked - not_found - not_text_node - wrong_file_or_branch - main_component_text_node linkedTextItemId: type: string message: type: string required: - figmaNodeId - outcome required: - projectId - textItemId - branchId - results example: 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. '400': description: Returned when the project is not linked to Figma content: application/json: schema: type: object properties: message: type: string description: Error message describing the validation failure required: - message example: message: Project "project-id-1" is not linked to Figma. '404': description: >- Returned when the project doesn't exist, or the text item doesn't exist in that project content: application/json: schema: type: object properties: message: type: string description: Error message describing what was not found required: - message example: message: Text item "greeting" was not found in project "project-id-1". security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ````