Layers API — Create, Update, Apply Ops, & Delete

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

string

required

The id of the slide to add the layer to.

LayerInput

required

A flat object describing the layer to create. The type field discriminates the union. Common fields shared by all layer types:

Show Shared fields (all types)

string

required

Layer type. One of "text", "bullets", "numbered", "bar", "donut", "chart", "table", "image", "shape", "icon".

{ x, y, w, h, rotation? }

required

Position and size in the 1920×1080 slide coordinate space.

number

Z-index integer. Higher values appear in front.

object

Visual effects: opacity, corner radius, CSS filter, vertical alignment, drop shadows.

string

AI brief — a plain-language instruction for what the AI should generate in this slot.

string[]

Sample outputs that guide AI generation for this slot.

Show type: 'text'

string | string[]

required

Text content. Pass an array for multi-paragraph text.

Theme text style. CSS variables from the applied theme resolve the visual appearance.

number

Explicit font size in points.

string

Text color hex.

string

Font family name.

boolean

Bold weight shorthand.

boolean

Italic style shorthand.

'left' | 'center' | 'right'

Horizontal text alignment.

Show type: 'bar' | 'donut'

Array<{ label: string; value: number }>

required

Chart data series. At least one datum is required.

string

Chart title.

'vertical' | 'horizontal'

Bar chart orientation (bar only).

string

D3-style format string for axis/label values.

boolean

Show data labels on bars/segments.

boolean

Overlay a CAGR arrow annotation (bar only).

Show type: 'chart'

CreateChartDocumentInput

required

Full chart structure for any chart family. Validated by createChartDocument() against the canonical ChartDocumentSchema.

Show type: 'table'

string[] | ColumnDef[]

required

Column headers. Pass strings for simple headers or ColumnDef objects for typed columns with widths and styles.

TableCell[][]

required

Table rows, each an array of cells matching the column count.

number

Number of leading rows to treat as header rows. Defaults to 1.

Show type: 'image'

string

required

Absolute URL of the image. Supported MIME types: image/jpeg, image/png, image/gif, image/webp, image/svg+xml, image/avif.

'cover' | 'contain' | 'fill'

How the image fills its bounding box.

RequestOptions

Show options fields

'queued' | 'confirmed'

default:"confirmed"

'confirmed' (default) waits for the durable acknowledgement. 'queued' returns as soon as the server accepts the write.

string

Idempotency key for safe retries.

Returns

string

Client-minted UUID for the new layer.

string

The parent slide id.

string

The layer type, e.g. "text", "bar", "table".

Example

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

CreateLayerParams

required

Show params fields

string

required

The parent slide id.

required

The layer type.

LayerPosition

required

Geometry in the slide coordinate space: { x, y, width, height, rotation? }.

number

Z-index integer.

boolean

Initial visibility.

boolean

Lock the layer against accidental edits in the editor.

string

Plain-text shorthand for text layers. The SDK converts this to the layer’s rich text representation. Ignored when contentJson is also present.

unknown

Rich content document for text-bearing layers. When provided, takes precedence over text.

Record<string, unknown>

Type-specific payload: { chartDocument } for charts, TableData for tables, { shapeType, ... } for shapes.

Record<string, unknown>

Layer-level style overrides.

LayerImageFill

Picture fill for shape layers: { url, objectFit?, width?, height? }.

RequestOptions

Show options fields

'queued' | 'confirmed'

default:"confirmed"

Acknowledgement level to wait for.

string

Idempotency key for safe retries.

Returns

string

Client-minted UUID for the new layer.

string

The parent slide id.

string

The layer type.

Example

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

string

required

The layer id.

Returns

string

The layer UUID.

string

The parent slide id.

string

The layer type.

LayerPosition

Geometry: { x, y, width, height, rotation? } in the 1920×1080 coordinate space.

unknown

Type-specific payload (chart document, table data, shape descriptor).

unknown

Rich text content for text-bearing layers. null for non-text types.

Record<string, unknown> | null

Layer-level style overrides.

number

Stacking order.

boolean

Whether the layer is visible.

LayerImageFill | null

Picture fill, or null.

string | null

The layout layer this slide layer is bound to, or null for free layers.

Example

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

string

required

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

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

UpdateLayerParams

required

Show params fields

string

required

The layer id to update.

Partial<LayerPosition>

Geometry patch. Provide only the sub-fields you want to change (x, y, width, height, rotation).

number

New stacking order.

boolean

Show or hide the layer.

boolean

Lock or unlock the layer in the editor.

unknown

Replacement rich text content for text-bearing layers. Overwrites the entire stored content.

Record<string, unknown>

Replacement type-specific payload. Overwrites the entire data object.

Record<string, unknown>

Replacement style overrides. Overwrites the entire style object.

LayerImageFill

Replacement picture fill: { url, attachmentId?, objectFit?, width?, height? }.

LayerCompositionMetadata | null

AI brief and placeholder metadata. Pass null to clear. Contains prompt, examples, and placeholder slot fields used by the Ablo generation pipeline.

RequestOptions

Show options fields

'queued' | 'confirmed'

default:"confirmed"

Acknowledgement level to wait for.

string

Idempotency key for safe retries.

Returns

string

The commit UUID.

'queued' | 'confirmed'

The acknowledgement level reached.

number

Monotonic sync cursor for real-time clients.

Example

// 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

string

required

The layer id to modify.

LayerOp

required

A typed operation. The op type must match the layer type:

Show ChartOp — for chart layers

A ChartOperation from the charts toolkit. Examples: add or remove a series, change chart type, update axis labels, set a color palette.

Show TableOp — for table layers

A TableOperation from the tables toolkit. Examples: set a cell value, add or remove a row/column, apply cell styles, merge cells.

Show TextOp — for text layers

A TextStyleOperation from the text-style toolkit. Examples: change font size, toggle bold, update text color, set alignment.

RequestOptions

Show options fields

'queued' | 'confirmed'

default:"confirmed"

Acknowledgement level to wait for.

string

Idempotency key for safe retries.

Returns

string

The commit UUID.

'queued' | 'confirmed'

The acknowledgement level reached.

number

Monotonic sync cursor for real-time clients.

Example

// 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

string

required

The layer id to delete.

RequestOptions

Show options fields

'queued' | 'confirmed'

default:"confirmed"

Acknowledgement level to wait for.

string

Idempotency key for safe retries.

Returns

string

The commit UUID.

'queued' | 'confirmed'

The acknowledgement level reached.

number

Monotonic sync cursor.

Example

const receipt = await ablo.layers.delete('layer_def456');
console.log(receipt.status); // 'confirmed'

Resources

Types

Layers API — Create, Update, Apply Ops, & Delete

`ablo.layers.create(slideId, layer, options?)`

Parameters

Returns

Example

`ablo.layers.createRaw(params, options?)`

Parameters

Returns

Example

`ablo.layers.retrieve(id)`

Parameters

Returns

Example

`ablo.layers.list({ slideId })`

Parameters

Returns

Example

`ablo.layers.update(params, options?)`

Parameters

Returns

Example

`ablo.layers.applyOp(id, op, options?)`

Parameters

Returns

Example

`ablo.layers.delete(id, options?)`

Parameters

Returns

Example

​ablo.layers.create(slideId, layer, options?)

​Parameters

​Returns

​Example

​ablo.layers.createRaw(params, options?)

​Parameters

​Returns

​Example

​ablo.layers.retrieve(id)

​Parameters

​Returns

​Example

​ablo.layers.list({ slideId })

​Parameters

​Returns

​Example

​ablo.layers.update(params, options?)

​Parameters

​Returns

​Example

​ablo.layers.applyOp(id, op, options?)

​Parameters

​Returns

​Example

​ablo.layers.delete(id, options?)

​Parameters

​Returns

​Example

`ablo.layers.create(slideId, layer, options?)`

Parameters

Returns

Example

`ablo.layers.createRaw(params, options?)`

Parameters

Returns

Example

`ablo.layers.retrieve(id)`

Parameters

Returns

Example

`ablo.layers.list({ slideId })`

Parameters

Returns

Example

`ablo.layers.update(params, options?)`

Parameters

Returns

Example

`ablo.layers.applyOp(id, op, options?)`

Parameters

Returns

Example

`ablo.layers.delete(id, options?)`

Parameters

Returns

Example