get_project

Read a project: its name, canvas backgroundColor and rootContainerId (the canvas container - what the create tools use when parentId is omitted), plus its items. Start with summary=true for a cheap first look - item counts per kind, the bounding box of the content and the first item texts, no item list - then fetch only what you need: kinds, parentId (direct children of one container), bbox (items intersecting a canvas rectangle) and textContains (case-insensitive) combine with AND; offset/limit page through the result (default 200 items), which reports total and hasMore. By default each item has id, kind, position (relative to its container), size (plus estimatedSize, the box the clients draw, for a label that grows with its text) and plain text cut to 200 characters (textTruncated marks a cut). fields picks others: style (fillColor, backgroundColor, strokeColor, strokeThickness, textColor, fontSize, fontFamily, horizontalTextAlignment, verticalTextAlignment, shapeType), a shape's cornerRadius (round-corner rectangles, world units) and adjustmentValues, connector lineType/start/end, zIndex (stacking order in the container, 0 = back-most), autoSize, parentId, angle, fileId, fullText (no cut), html (stored markup), or all. Item ids are stable, so after a write re-fetch only what changed, not the whole board. Ids feed update_item_property, style_item, arrange_item, delete_item and connect_items.

A board can hold hundreds of items, and an agent tends to re-read it after every write. To keep that cheap:

1. Start with summary: true — item counts per kind, the bounding box of the content and the first item texts, without an item list.
2. Then fetch only what you need, with kinds, parentId, bbox or textContains.
3. Item ids are stable, so after a write re-fetch only what changed, not the whole board.

Tool name: get_project

Parameters

Parameter	Type	Required	Default	Description
projectId	string	Yes	—	The project (map) id, e.g. from list_projects.
fields	enum[]	No	["id", "kind", "position", "size", "text"]	Item fields to return — see Fields.
kinds	enum[]	No	All	Only items of these kinds: label, sticky, shape, connector, image, svg, web, document, video, drawing, comment, group, other.
parentId	string	No	—	Only the direct children of this container, e.g. a group id — or rootContainerId for the items directly on the canvas.
bbox	object	No	—	{ x, y, width, height } — only items whose bounding box intersects this rectangle in canvas coordinates.
textContains	string	No	—	Only items whose text contains this, case-insensitive. The plain text is searched, not the stored markup.
summary	boolean	No	false	Return a summary instead of the item list — see Summary.
offset	number	No	0	Matching items to skip.
limit	number	No	200	Items to return, 1–1000.

Filters combine with AND.

Returns

backgroundColor is the color the canvas shows. When the board has no background of its own, it is the web client's dark default #080A10 and backgroundIsDefault is true; pick text colors against that. A gradient or image background has no single color and is omitted.

{
  "projectId": "a1b2c3d4-...",
  "name": "Product Roadmap",
  "backgroundColor": "#F2F2F2",
  "backgroundIsDefault": false,
  "rootContainerId": "f0e1d2c3-...",
  "total": 214,
  "hasMore": true,
  "items": [
    {
      "id": "11aa22bb-...",
      "kind": "label",
      "position": { "x": 100, "y": 200 },
      "size": { "width": 240, "height": 0 },
      "text": "Q3 Goals"
    },
    {
      "id": "33cc44dd-...",
      "kind": "shape",
      "position": { "x": 400, "y": 180 },
      "size": { "width": 160, "height": 80 }
    }
  ]
}

• rootContainerId is the canvas container. The create tools use it when parentId is omitted, and it works as the parentId filter for the items directly on the canvas.
• total counts the items that match the filters; hasMore says whether another page follows. offset is echoed back when it is not 0.
• position is relative to the item's container — the canvas for top-level items, the group for items inside one — so it can be written back with update_item_property unchanged. bbox and the summary bounds use canvas coordinates.
• A connector is drawn between its ends, so for bbox and the summary bounds it spans the items it is attached to (and the position of a free end), not its own stored position and size.
• On a board that still uses an older client's rotation handling, a quarter-turned item (90° or 270°) has that client's position: the top-left of its turned box. The web app converts such a board the first time someone opens it to edit. When create_shape or create_items turn a shape a quarter on a board without quarter-turned items, they switch the board to the current handling in the same change; on a board that has some, they write the shape so that it lands at the position you asked for once the board is converted.
• Numbers are rounded to one decimal.

Fields

Field	Applies to	Value
id, kind, position, size	all	Default fields. A connector has no position or size: start and end place it.
estimatedSize	labels, stickies	Comes with size when the label grows with its text (autoSize other than "none"): the box the clients draw it in, estimated from the text, in world units and including the label's scale (which size does not). The stored size of a growing axis is a placeholder, often 0. render_view measures the drawn box exactly (items[].rect).
text	labels, stickies	Default. The plain text — markup removed, paragraphs as line breaks — cut to 200 characters; "textTruncated": true marks a cut.
fullText	labels, stickies	The text without the cut.
html	labels, stickies	The stored markup. Only returned when asked for by name.
parentId	all	The container holding the item.
zIndex	all	Stacking order within the container, 0 = back-most. Change it with arrange_item.
angle	all	Rotation in degrees.
autoSize	labels, stickies	"none", "width", "height" or "both" — see create_item sizing.
fillColor	shapes	Fill, hex.
backgroundColor	labels, stickies	Background, hex (#00000000 = none).
strokeColor, strokeThickness	shapes, connectors	Outline / line.
textColor, fontSize, fontFamily	labels, stickies	Text style.
horizontalTextAlignment, verticalTextAlignment	labels, stickies	"Left", "Center", "Right" and "Top", "Center", "Bottom", as the create tools take them.
shapeType	shapes	The shape name.
cornerRadius	round-corner shapes	The radius the corners are drawn with, in world units (see corner radius).
adjustmentValues	shapes	The stored shape proportions, as the REST API reads and writes them.
lineType, start, end	connectors	"Straight", "Angled" or "Curved"; each end as { itemId, decorator } (a free end has a position instead of an itemId).
fileId	images, vector images	The stored file id for get_image_data (which also accepts the item id).
all	—	Every field except html. Text is still cut unless fullText is added too.

A field that does not apply to an item is left out. id is always included, whichever fields you ask for.

{ "projectId": "a1b2c3d4-...", "kinds": ["shape"], "fields": ["id", "shapeType", "fillColor"] }

Summary

{
  "projectId": "a1b2c3d4-...",
  "name": "Product Roadmap",
  "backgroundColor": "#F2F2F2",
  "backgroundIsDefault": false,
  "rootContainerId": "f0e1d2c3-...",
  "summary": {
    "total": 214,
    "kinds": { "label": 90, "connector": 50, "shape": 40, "sticky": 20, "image": 12, "group": 2 },
    "bounds": { "x": 34, "y": 45.5, "width": 4467.9, "height": 3181.2 },
    "texts": [
      { "id": "11aa22bb-...", "kind": "label", "text": "Q3 Goals" }
    ]
  }
}

texts holds the first 20 item texts, each cut to 100 characters. The summary covers the items that match the filters, so summary combines with kinds, bbox and the rest. Auto-sized labels store no measured size, so bounds is approximate for them.

Example

"What's on the Product Roadmap board?"

{ "projectId": "a1b2c3d4-...", "summary": true }

"Which stickies mention the launch?"

{ "projectId": "a1b2c3d4-...", "kinds": ["sticky"], "textContains": "launch" }