update_design_reference
Changes a design reference of a project in part.
Change a design reference by design_reference_id with any of title, url, kind, referenceable_type with referenceable_id, version and notes (HTML). A field left out keeps its value; a field sent as null is cleared. The change goes through the same action the Designs page runs and design_reference.updated goes out with what moved. A staff token with design-reference:update on the project is needed.
Requires ability
The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.
Runs the same action as
The REST endpoint and this tool share one action, so validation, permissions and events are identical.
Fires one event
Delivered to every endpoint subscribed to it once the change is made.
Annotations
A client that honours annotations asks a person before running it.
Arguments
design_reference_id*stringUUID of the design reference.
titlestringoptionalWhat the reference is called, 2 to 160 characters.
urlstringoptionalWhere the design lives, as a full URL.
kindstringoptionalWhat the link points at; other by default.
figmawireframeprototypescreenshotapi_contractsequence_diagramerddocumentotherreferenceable_typestringoptionalWhat the reference hangs off: project by default, or component.
projectcomponentreferenceable_idstringoptionalUUID of the component when the target is a component.
versionstringoptionalThe version or revision of the design, as the designer labels it.
notesstringoptionalWhat to look at and why, as HTML.
What it returns
{ "data": { "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d6e", "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13", "referenceable_type": "component", "referenceable_id": "c0a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b", "kind": "figma", "title": "Order flow", "url": "https://www.figma.com/file/abc123/order-flow", "version": "v2", "notes": "<p>The payment step is now designed; the slot picker moved to its own screen.</p>", "added_by": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e", "position": 1, "created_at": "2026-10-28T09:40:00+00:00", "updated_at": "2026-10-29T10:05:00+00:00" }}How it fails
VALIDATION_FAILEDa field outside its limits, a url that is not an address, a kind or target outside its set, or a component target without a component of the project.
RESOURCE_NOT_FOUNDunknown design_reference_id, or a reference outside the token's scope or the person's visibility.
FORBIDDENthe token is a client guest's, or the holder's role on the project does not carry design-reference:update.
TOKEN_MISSING_ABILITYtoken lacks design-reference:update.
How is this guide?
Last updated on