Annotations

读取和管理设计标注及标注分类。

Type reference

// Annotations are designer-authored notes attached to nodes — specs, intent, constraints.
// Every node-returning endpoint includes an annotation brief: { label, properties?, categoryId? }.
// Use this endpoint for full CRUD and to manage annotation categories.
// Workflow: read annotations on a node with get, add new ones with add, manage categories with categories/create_category.
// Batch: get/set/add/remove accept items:[{id, ...}] for multi-node operations, or single-item params (id, label, etc).
// properties: measurement indicators Figma displays on the canvas — validated per node type and state.
// labelMarkdown: rich text label supporting **bold**, *italic*, `code`, [links](url).
// categoryId: group annotations by category (e.g. "Spacing", "Typography"). Create categories first.
// ---
// AnnotationPropertyType values (node-type-dependent — invalid ones are rejected with the available list):
//   Dimension: width, height, maxWidth, minWidth, maxHeight, minHeight
//   Paint: fills, strokes, effects, strokeWeight, cornerRadius, opacity
//   Text (TEXT nodes only): textStyleId, textAlignHorizontal, fontFamily, fontStyle, fontSize, fontWeight, lineHeight, letterSpacing
//   Layout (auto-layout only): itemSpacing, padding, layoutMode, alignItems
//   Instance (INSTANCE only): mainComponent
//   Grid (grid layout only): gridRowGap, gridColumnGap, gridRowCount, gridColumnCount, gridRowAnchorIndex, gridColumnAnchorIndex, gridRowSpan, gridColumnSpan
// AnnotationCategoryColor values: yellow, orange, red, pink, violet, blue, teal, green.

9 methods available.

get

read

Read all annotations on a node (full detail with resolved category names)

Parameter	Type	Required	Description
id	string	✗	Node ID
categoryId	string	✗	Filter — only return annotations in this category
items	object[]	✗	Batch: [{id, categoryId?}, ...]
↳ id	string	✓
↳ categoryId	string	✗

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ name	string
↳ annotations	object[]
↳ index	number
↳ label	string
↳ labelMarkdown	string
↳ properties	string[]
↳ category	object
↳ id	string
↳ label	string
↳ color	string

list

read

Search annotations across a subtree, optionally filtered by category

Parameter	Type	Required	Description
parentId	string	✗	Root node to search within (default: current page)
categoryId	string	✗	Filter by category ID
limit	number	✗	Max items per page (default 100) (default: 100)

Response

Field	Type	Description
results	object[]	Annotations found across the subtree
↳ nodeId	string
↳ nodeName	string
↳ nodeType	string
↳ index	number
↳ label	string
↳ labelMarkdown	string
↳ properties	string[]
↳ category	object
↳ id	string
↳ label	string
↳ color	string
count	number
_truncated	boolean

set

edit

Replace all annotations on a node

Parameter	Type	Required	Description
id	string	✗	Node ID
annotations	object[]	✗	Array of annotation objects to set (replaces all existing)
↳ label	string	✗	Plain text label
↳ labelMarkdown	string	✗	Rich text label (Markdown)
↳ properties	string[]	✗	Measurement property types to display
↳ categoryId	string	✗	Category ID
items	object[]	✗	Batch: [{id, annotations: [...]}, ...]
↳ id	string	✓
↳ annotations	array	✓	Annotations to set on this node

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ count	number

add

edit

Add an annotation to a node

Parameter	Type	Required	Description
id	string	✗	Node ID
label	string	✗	Plain text label (use label or labelMarkdown, not both)
labelMarkdown	string	✗	Rich text label with Markdown formatting
properties	string[]	✗	Measurement property types to display on canvas
categoryId	string	✗	Category ID to group this annotation
items	object[]	✗	Batch: [{id, label?, labelMarkdown?, properties?, categoryId?}, ...]
↳ id	string	✓
↳ label	string	✗
↳ labelMarkdown	string	✗
↳ properties	string[]	✗
↳ categoryId	string	✗

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ index	number
↳ count	number

remove

edit

Remove an annotation from a node by index

Parameter	Type	Required	Description
id	string	✗	Node ID
index	number	✗	Annotation index to remove (from get response)
items	object[]	✗	Batch: [{id, index}, ...]
↳ id	string	✓
↳ index	number	✓

Response

Field	Type	Description
results	object[]	One entry per input item
↳ id	string
↳ removed	boolean
↳ count	number

categories

read

List all annotation categories in the file

No parameters.

Response

Field	Type	Description
categories	object[]
↳ id	string
↳ label	string
↳ color	string
↳ isPreset	boolean

create_category

create

Create a new annotation category

Parameter	Type	Required	Description
label	string	✓	Category label
color	"yellow" | "orange" | "red" | "pink" | "violet" | "blue" | "teal" | "green"	✓	Category color

Response

Field	Type	Description
id	string
label	string
color	string

update_category

edit

Update an annotation category’s label or color

Parameter	Type	Required	Description
id	string	✓	Category ID
label	string	✗	New label
color	"yellow" | "orange" | "red" | "pink" | "violet" | "blue" | "teal" | "green"	✗	New color

Response

Field	Type	Description
id	string
label	string
color	string

delete_category

edit

Delete an annotation category

Parameter	Type	Required	Description
id	string	✓	Category ID to delete

Response

Field	Type	Description
deleted	boolean