> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryablo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Layers API — Create, Update, Apply Ops, & Delete
> Add and manage layers on a slide. Use typed ops for read-modify-write edits to chart, table, and text layers without overwriting unrelated fields.
The `ablo.layers` namespace manages the individual content elements — text, charts, tables, images, shapes, and icons — that live on a slide. Layers are addressed by id; capture the id returned by `create` and pass it directly to `update`, `applyOp`, or `delete` without an intermediate lookup. For read-modify-write edits to chart, table, or text content, use `applyOp` rather than `update` — it applies a typed operation against the current stored content so only the targeted fields change.
***
## `ablo.layers.create(slideId, layer, options?)`
Adds a single layer to a slide. The `layer` argument is a flat, discriminated-union object; the SDK validates and compiles it before committing.
### Parameters
The id of the slide to add the layer to.
A flat object describing the layer to create. The `type` field discriminates the union. Common fields shared by all layer types:
Layer type. One of `"text"`, `"bullets"`, `"numbered"`, `"bar"`, `"donut"`, `"chart"`, `"table"`, `"image"`, `"shape"`, `"icon"`.
Position and size in the 1920×1080 slide coordinate space.
Z-index integer. Higher values appear in front.
Visual effects: opacity, corner radius, CSS filter, vertical alignment, drop shadows.
AI brief — a plain-language instruction for what the AI should generate in this slot.
Sample outputs that guide AI generation for this slot.
Text content. Pass an array for multi-paragraph text.
Theme text style. CSS variables from the applied theme resolve the visual appearance.
Explicit font size in points.
Text color hex.
Font family name.
Bold weight shorthand.
Italic style shorthand.
Horizontal text alignment.
Chart data series. At least one datum is required.
Chart title.
Bar chart orientation (bar only).
D3-style format string for axis/label values.
Show data labels on bars/segments.
Overlay a CAGR arrow annotation (bar only).
Full chart structure for any chart family. Validated by `createChartDocument()` against the canonical `ChartDocumentSchema`.
Column headers. Pass strings for simple headers or `ColumnDef` objects for typed columns with widths and styles.
Table rows, each an array of cells matching the column count.
Number of leading rows to treat as header rows. Defaults to `1`.
Absolute URL of the image. Supported MIME types: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/svg+xml`, `image/avif`.
How the image fills its bounding box.
`'confirmed'` (default) waits for the durable acknowledgement. `'queued'` returns as soon as the server accepts the write.
Idempotency key for safe retries.
### Returns
Client-minted UUID for the new layer.
The parent slide id.
The layer type, e.g. `"text"`, `"bar"`, `"table"`.
### Example
```typescript theme={null}
import { Decks } from '@abloatai/decks';
const ablo = new Decks(process.env.ABLO_API_KEY!);
const layer = await ablo.layers.create('slide_xyz789', {
type: 'bar',
data: [
{ label: 'Q1', value: 120 },
{ label: 'Q2', value: 180 },
{ label: 'Q3', value: 252 },
],
orientation: 'vertical',
at: { x: 160, y: 300, w: 900, h: 600 },
});
console.log(layer.id); // save this to update the chart data later
```
***
## `ablo.layers.createRaw(params, options?)`
Advanced escape hatch for creating a layer from raw `CreateLayerParams`. Use this when you need to supply a fully-constructed `data` or `contentJson` payload that the higher-level `LayerInput` builders do not expose.
### Parameters
The parent slide id.
The layer type.
Geometry in the slide coordinate space: `{ x, y, width, height, rotation? }`.
Z-index integer.
Initial visibility.
Lock the layer against accidental edits in the editor.
Plain-text shorthand for text layers. The SDK converts this to the layer's rich text representation. Ignored when `contentJson` is also present.
Rich content document for text-bearing layers. When provided, takes precedence over `text`.
Type-specific payload: `{ chartDocument }` for charts, `TableData` for tables, `{ shapeType, ... }` for shapes.
Layer-level style overrides.
Picture fill for shape layers: `{ url, objectFit?, width?, height? }`.
Acknowledgement level to wait for.
Idempotency key for safe retries.
### Returns
Client-minted UUID for the new layer.
The parent slide id.
The layer type.
### Example
```typescript theme={null}
const layer = await ablo.layers.createRaw({
slideId: 'slide_xyz789',
type: 'text',
position: { x: 160, y: 120, width: 1600, height: 160 },
contentJson: myPrebuiltContentDoc,
});
console.log(layer.id);
```
***
## `ablo.layers.retrieve(id)`
Fetches the full stored record for a layer by id. Requires a readable client.
### Parameters
The layer id.
### Returns
The layer UUID.
The parent slide id.
The layer type.
Geometry: `{ x, y, width, height, rotation? }` in the 1920×1080 coordinate space.
Type-specific payload (chart document, table data, shape descriptor).
Rich text content for text-bearing layers. `null` for non-text types.
Layer-level style overrides.
Stacking order.
Whether the layer is visible.
Picture fill, or `null`.
The layout layer this slide layer is bound to, or `null` for free layers.
### Example
```typescript theme={null}
const layer = await ablo.layers.retrieve('layer_def456');
console.log(layer.type, layer.position);
```
***
## `ablo.layers.list({ slideId })`
Returns all layers on a slide. Requires a readable client.
### Parameters
The slide whose layers you want to list.
### Returns
An array of `LayerRecord` objects. Each entry has the same shape as the return value of `retrieve`.
### Example
```typescript theme={null}
const layers = await ablo.layers.list({ slideId: 'slide_xyz789' });
for (const layer of layers) {
console.log(layer.zIndex, layer.type, layer.position);
}
```
***
## `ablo.layers.update(params, options?)`
Applies a field-level patch to an existing layer. Each field you include overwrites the entire stored value for that field; fields you omit are left unchanged. Use `applyOp` instead when you want to surgically modify chart series, table cells, or text styles.
### Parameters
The layer id to update.
Geometry patch. Provide only the sub-fields you want to change (`x`, `y`, `width`, `height`, `rotation`).
New stacking order.
Show or hide the layer.
Lock or unlock the layer in the editor.
Replacement rich text content for text-bearing layers. Overwrites the entire stored content.
Replacement type-specific payload. Overwrites the entire `data` object.
Replacement style overrides. Overwrites the entire `style` object.
Replacement picture fill: `{ url, attachmentId?, objectFit?, width?, height? }`.
AI brief and placeholder metadata. Pass `null` to clear. Contains `prompt`, `examples`, and placeholder slot fields used by the Ablo generation pipeline.
Acknowledgement level to wait for.
Idempotency key for safe retries.
### Returns
The commit UUID.
The acknowledgement level reached.
Monotonic sync cursor for real-time clients.
### Example
```typescript theme={null}
// Move a layer and hide it in one commit
const receipt = await ablo.layers.update({
id: 'layer_def456',
position: { x: 320, y: 200 },
visible: false,
});
console.log(receipt.status); // 'confirmed'
```
***
## `ablo.layers.applyOp(id, op, options?)`
Applies a typed operation to a chart, table, or text layer using a read-modify-write cycle. The SDK reads the layer's current document from the server, applies the op through the same reducers used by the editor and the AI, and writes only the changed fields back — so unrelated parts of the document are never overwritten.
This method requires a readable client. If your client is commit-only, it throws with a clear error.
### Parameters
The layer id to modify.
A typed operation. The op type must match the layer type:
A `ChartOperation` from the charts toolkit. Examples: add or remove a series, change chart type, update axis labels, set a color palette.
A `TableOperation` from the tables toolkit. Examples: set a cell value, add or remove a row/column, apply cell styles, merge cells.
A `TextStyleOperation` from the text-style toolkit. Examples: change font size, toggle bold, update text color, set alignment.
Acknowledgement level to wait for.
Idempotency key for safe retries.
### Returns
The commit UUID.
The acknowledgement level reached.
Monotonic sync cursor for real-time clients.
### Example
```typescript theme={null}
// On first run, create the deck and capture the layer id
const deck = await ablo.decks.create({
title: 'Live Dashboard',
slides: [
{
title: 'Revenue',
layers: [
{
type: 'table',
columns: ['Quarter', 'Revenue'],
rows: [['Q1', '$1.2M']],
at: { x: 160, y: 300, w: 1200, h: 400 },
},
],
},
],
});
const tableLayerId = deck.slides[0].layers[0].id;
// On subsequent runs, apply a typed op to add a row — no full rewrite needed
const receipt = await ablo.layers.applyOp(tableLayerId, {
type: 'insertRow',
index: 1,
cells: [{ value: 'Q2' }, { value: '$1.5M' }],
});
console.log(receipt.status); // 'confirmed'
```
***
## `ablo.layers.delete(id, options?)`
Permanently deletes a layer from its slide.
### Parameters
The layer id to delete.
Acknowledgement level to wait for.
Idempotency key for safe retries.
### Returns
The commit UUID.
The acknowledgement level reached.
Monotonic sync cursor.
### Example
```typescript theme={null}
const receipt = await ablo.layers.delete('layer_def456');
console.log(receipt.status); // 'confirmed'
```