Element Operations

Your AI assistant uses these tools to add, modify, and remove the shapes, text, and lines that make up each slide — or each layout. You don't call them directly — just describe what you want and your assistant handles the rest.

Every slide is made of elements — the individual pieces of content your audience sees. There are four element types you can create:

• Shape — rectangle, ellipse, diamond, triangle, arrow, hexagon, or star. Rectangles take an optional cornerRadius. Shapes support text directly inside them — use the text property on a shape instead of layering a separate text element on top.
• Text — a standalone text block for titles, body content, captions, or any text that doesn't need a background shape.
• Line — a connector between two points, with optional arrow heads. Lines can anchor to other elements so they stay connected when elements move.
• Chart — data visualizations (bar, line, pie, scatter, and more). Placed with elementType: "chart" like any other element, then populated with element_update_chart.

Images need a tool of their own, and a chart needs a second call to fill in its data — see Images and Charts. For design guidance on combining these elements, see Visual Design Techniques.

Slides or Layouts

These tools write to two surfaces. Anywhere one takes a slide id, it also takes a layout id (“layout-…”, from layout_list or layout_get), and the element lands on the deck's layout instead of on one slide. That is how your assistant adds something that should appear on every slide built from a layout — a logo, a footer rule, a side accent bar — rather than pasting it onto each slide in turn.

The tools that address an element rather than a surface — element_bulk_update, element_delete, element_group and element_ungroup — need no surface at all: they look an elementId up on both. Layout element ids are dle- prefixed and come from layout_get.

What Changes on a Layout

• New elements are decorative — they carry no role and they are not placeholders. A role you pass is dropped and reported back under ignored.
• Charts are not available — layouts have no chart type. Put the chart on a slide.
• A placeholder's text is its prompt — updating text on a placeholder sets the wording shown for that slot while it is empty — in the editor's Layouts view, and on every empty placeholder of the slides built from that layout. It is ghost text, never content.
• Groups cannot span surfaces — every member must be on one slide, or on one layout.

Example — Editing a Layout

// An accent bar on the layout, not on one slide.
// Every slide built on this layout shows it.
element_bulk_create({
  deckId: "deck_abc123",
  slideId: "layout-Qc9Wb3Xn",   // a layout id, where a slide id would go
  elements: [
    {
      elementType: "shape",
      shapeType: "rectangle",
      x: 0, y: 0,
      width: 14, height: 720,
      fillColor: "#1A1A2E"
    }
  ]
})

// Response:
// {
//   slides: [
//     {
//       slideId: "layout-Qc9Wb3Xn",
//       surface: "layout",
//       layoutName: "Title and Content",
//       elementIds: ["dle-shape-Ka1bZ9mQ"]
//     }
//   ],
//   ignored: ["role"]
// }

Creating a Single Element

When you ask to “add a title to this slide” or “put a blue rectangle behind the heading,” your assistant uses element_create to place one element at a time. For adding several elements at once, the assistant will typically use element_bulk_create (below) instead.

Parameters

* Always set role on text elements with semantic meaning (titles, body, etc.). Decorative shapes like accent bars or background rectangles don't need a role. See the full list of styling properties in the Common Properties Reference below.

What It Returns

• elementId — the new element's ID (use this for updates and line anchors)
• type — the element type that was created
• position — { x, y } in pixels
• size — { width, height } in pixels
• overflow — if the text doesn't fit, includes overflow info with suggestions for fixing it

Example — Shape with Text

element_create({
  deckId: "deck_abc123",
  slideId: "slide_001",
  elementType: "shape",
  shapeType: "rectangle",
  x: 60, y: 40,
  width: 500, height: 80,
  fillColor: "#1C2833",
  text: "**Q4 Business Review**",
  fontSize: 36,
  fontFamily: "Inter",
  textColor: "#FFFFFF",
  textAlign: "left",
  verticalAlign: "middle",
  role: "title"
})

// Response:
// {
//   id: "j97x...",
//   elementId: "elem_abc123",
//   type: "shape",
//   slideId: "slide_001",
//   position: { x: 60, y: 40 },
//   size: { width: 500, height: 80 },
//   zIndex: 0
// }

Example — Text Element

element_create({
  deckId: "deck_abc123",
  slideId: "slide_001",
  elementType: "text",
  x: 60, y: 150,
  width: 600, height: 300,
  text: "- Revenue up 18% QoQ\n- 340 new customers\n- Expanded to 3 new markets",
  fontSize: 16,
  fontFamily: "Inter",
  textColor: "#AAB7B8",
  role: "body"
})

Example — Line

// Line with an arrow from point A to point B
element_create({
  deckId: "deck_abc123",
  slideId: "slide_001",
  elementType: "line",
  startX: 60, startY: 130,
  endX: 560, endY: 130,
  strokeColor: "#5EA8A7",
  strokeWidth: 3,
  arrowHead: false
})

// Anchored line — connects to an existing element
element_create({
  deckId: "deck_abc123",
  slideId: "slide_001",
  elementType: "line",
  startAnchor: {
    type: "connected",
    elementId: "elem_abc",
    connectionPointId: "right"
  },
  endAnchor: {
    type: "connected",
    elementId: "elem_def",
    connectionPointId: "left"
  },
  strokeColor: "#2E4053",
  arrowHead: true
})

Creating Multiple Elements

Most of the time, your assistant builds a slide by placing several elements at once — a title, an accent bar, body text, and so on. element_bulk_create creates up to 50 elements in a single atomic call. All elements succeed or all fail — you won't end up with a half-built slide.

You can also target multiple slides at once using slideIds — the same elements are replicated on each slide. This is useful for adding consistent footers, logos, or accent bars across your entire presentation.

Parameters

* Exactly one of slideId or slideIds must be provided.

What It Returns

• slides — array of results grouped by slide, each containing the created elements with their IDs, types, positions, and sizes
• Each element includes overflow info if text doesn't fit

Example — Build a Slide Layout

element_bulk_create({
  deckId: "deck_abc123",
  slideId: "slide_002",
  elements: [
    {
      elementType: "shape",
      shapeType: "rectangle",
      x: 0, y: 0,
      width: 12, height: 720,
      fillColor: "#5EA8A7"
    },
    {
      elementType: "text",
      x: 60, y: 40,
      width: 600, height: 60,
      text: "Revenue Highlights",
      fontSize: 40,
      fontFamily: "Inter",
      textColor: "#FFFFFF",
      role: "title"
    },
    {
      elementType: "line",
      startX: 60, startY: 110,
      endX: 400, endY: 110,
      strokeColor: "#5EA8A7",
      strokeWidth: 3
    },
    {
      elementType: "text",
      x: 60, y: 130,
      width: 600, height: 400,
      text: "- Total revenue: **$4.2M**\n- Growth: +18% QoQ\n- New customers: 340",
      fontSize: 16,
      fontFamily: "Inter",
      textColor: "#AAB7B8",
      role: "body"
    }
  ]
})

// Response:
// {
//   slides: [
//     {
//       slideId: "slide_002",
//       elements: [
//         { elementId: "elem_001", type: "shape", ... },
//         { elementId: "elem_002", type: "text", ... },
//         { elementId: "elem_003", type: "line", ... },
//         { elementId: "elem_004", type: "text", ... }
//       ]
//     }
//   ]
// }

Example — Add Footers Across Slides

// Add a footer to every slide at once
element_bulk_create({
  deckId: "deck_abc123",
  slideIds: ["slide_001", "slide_002", "slide_003"],
  elements: [
    {
      elementType: "text",
      x: 60, y: 680,
      width: 300, height: 24,
      text: "Confidential — Acme Corp",
      fontSize: 10,
      textColor: "#666666",
      role: "footer"
    }
  ]
})

// The same footer element is created on all 3 slides

Updating Elements

When you ask to “change the title color to white” or “make the body text bigger,” your assistant uses element_bulk_update to modify existing elements. Only the fields you provide are changed — everything else stays the same. You can update up to 50 elements across any slides in the deck in one atomic call.

Parameters

Updatable Properties

Each update object must include elementId and at least one of these properties:

What It Returns

• results — array of results, one per updated element
• Each result includes elementId, updatedFields (list of field names that changed), and overflow info if applicable

Example

element_bulk_update({
  deckId: "deck_abc123",
  updates: [
    {
      elementId: "elem_002",
      textColor: "#FFFFFF",
      fontSize: 44,
      fontFamily: "Playfair Display"
    },
    {
      elementId: "elem_004",
      text: "- Total revenue: **$5.1M**\n- Growth: +22% QoQ\n- New customers: 410",
      textColor: "#F4F6F6"
    },
    {
      elementId: "elem_001",
      fillColor: "#2E4053",
      width: 16
    }
  ]
})

// Response:
// {
//   results: [
//     { elementId: "elem_002",
//       updatedFields: ["textColor", "fontSize", "fontFamily"] },
//     { elementId: "elem_004",
//       updatedFields: ["text", "textColor"] },
//     { elementId: "elem_001",
//       updatedFields: ["fillColor", "width"] }
//   ]
// }

Deleting an Element

When you say “remove that subtitle” or “delete the divider line,” your assistant uses element_delete to permanently remove an element from a slide. This cannot be undone, so your assistant will typically inspect the slide first with slide_get to find the right element ID.

Parameters

What It Returns

• success — whether the deletion succeeded
• elementId, type, slideId — confirmation of what was removed

Example

element_delete({
  deckId: "deck_abc123",
  elementId: "elem_003"
})

// Response:
// {
//   success: true,
//   elementId: "elem_003",
//   type: "line",
//   slideId: "slide_002"
// }

Common Properties Reference

These properties can be set when creating or updating elements. Not all properties apply to all element types.

Position & Size

Shape Styling

Text Formatting

Line Properties

Which Tool Will My Assistant Use?

Your AI assistant picks the right tool based on what you ask:

• “Add a title to this slide” → element_create or element_bulk_create to add one or more elements
• “Build a slide with a title bar, accent line, and bullets” → element_bulk_create to create all elements in one step
• “Add a footer to every slide” → element_bulk_create with slideIds to replicate across slides
• “Change the title color to white” → element_bulk_update to modify the existing title element
• “Remove the subtitle” → element_delete to permanently remove it
• “Put our logo on every slide that uses this layout” → element_bulk_create with a layout id in place of the slide id

Related

• Deck Operations — Create and manage presentations
• Slide Operations — Add, inspect, duplicate, and delete individual slides
• Images — Add images from URLs with automatic sizing
• Styling — Colors, fonts, sizes, markdown formatting, and design techniques
• Slide Rules & Roles — Element roles, visual hierarchy, and per-deck rules
• Design Techniques — Color blocks, accent lines, split backgrounds, and more