Decks API — Create, Retrieve, Update & Delete Decks

The ablo.decks namespace is the entry point for managing presentation decks. Every method resolves to a single atomic commit on the server, so a create call that includes slides and layers either succeeds completely or fails without partial state. Deck ids are minted client-side before the commit is sent, so you can capture the id immediately and use it in subsequent calls without an extra round-trip.

`ablo.decks.create(input?, options?)`

Creates a new deck. Pass input.slides to include the complete slide and layer tree in one commit. When omitted, an empty deck is created and slides can be added later via ablo.slides.create.

Parameters

CreateDeckInput

The deck configuration. All fields are optional; omit entirely to create a blank deck.

Show input fields

string

Human-readable name shown in the workspace. Defaults to "Untitled" when omitted.

string

Id of the parent Layout container (design system) the deck inherits chrome from.

string

Id of a Theme to apply. Controls the :root CSS variables used by all slides.

string

Icon key displayed alongside the deck title in the workspace.

string

Hex accent color for the deck, for example "#4F46E5".

SlideSpec[]

Full slide and layer tree to create atomically with the deck. Each SlideSpec may itself carry a layers array. Slides are ordered by their position in the array (index 0 → order: 0).

Show SlideSpec fields

string

Slide title.

string

SlideLayout id to attach a layout template to this slide.

LayerInput[]

Flat layer descriptors. Each object is a discriminated union on type ("text", "bar", "donut", "chart", "table", "image", "shape", "icon", "bullets", "numbered").

SlideBackgroundInput

Solid color, gradient, image, or raw CSS background.

'16:9' | '16:10' | 'a4-portrait'

Size preset. '16:9' expands to 1920×1080, '16:10' to 1920×1200, 'a4-portrait' to 2480×3508.

number

Explicit slide width in pixels (overrides size).

number

Explicit slide height in pixels (overrides size).

'16:9' | '16:10' | '4:3' | 'custom'

Aspect ratio constraint.

boolean

Toggle the snap grid overlay.

number

Grid cell size in pixels.

boolean

When false, opt this slide out of master compositing from the parent layout.

RequestOptions

Per-call commit controls.

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. Repeated calls with the same key are deduplicated server-side.

Returns

string

Client-minted UUID for the new deck.

string

The deck title ("Untitled" when not supplied).

string | null

The layout container id, or null if none was specified.

string | null

The theme id, or null if none was specified.

SlideResult[]

One entry per slide passed in input.slides, in order.

Show SlideResult fields

string

Client-minted UUID for the slide.

string

The parent deck id.

string

The slide title.

number

Zero-based integer position in the deck.

LayerResource[]

One entry per layer, each carrying { id, slideId, type }.

Example

import { Decks } from '@abloatai/decks';

const ablo = new Decks(process.env.ABLO_API_KEY!);

// Create a deck with two slides and a layer on each
const deck = await ablo.decks.create({
  title: 'Q3 Market Update',
  color: '#4F46E5',
  slides: [
    {
      title: 'Key Metrics',
      layers: [
        {
          type: 'text',
          text: 'Revenue up 40%',
          style: 'h1',
          at: { x: 160, y: 120, w: 1600, h: 160 },
        },
        {
          type: 'bar',
          data: [
            { label: 'Q1', value: 120 },
            { label: 'Q2', value: 180 },
            { label: 'Q3', value: 252 },
          ],
          at: { x: 160, y: 340, w: 900, h: 600 },
        },
      ],
    },
    {
      title: 'Summary',
      layers: [
        {
          type: 'text',
          text: 'Thank you',
          style: 'title',
          at: { x: 400, y: 460, w: 1120, h: 160 },
        },
      ],
    },
  ],
});

console.log(deck.id);                    // deck UUID
console.log(deck.slides[0].layers[0].id); // first layer UUID — save this for later updates

`ablo.decks.retrieve(id)`

Fetches the stored record for a deck by id. Requires a readable client.

Parameters

string

required

The deck id returned by create.

Returns

string

The deck UUID.

string

The deck title.

string | null

The attached layout container id, or null.

string | null

The attached theme id, or null.

Example

const deck = await ablo.decks.retrieve('deck_abc123');
console.log(deck.title, deck.themeId);

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

Applies a field-level patch to an existing deck. Only the fields you include are changed; omitted fields are left untouched.

Parameters

UpdateDeckParams

required

Show params fields

string

required

The deck id to update.

string

New deck title.

string

Short description or AI-generated summary stored on the deck.

string | null

Replace or clear the attached theme. Pass null to detach.

string | null

Replace or clear the attached layout container. Pass null to detach.

string

New icon key.

string

New hex accent color.

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 — use this to wait for a specific state in a real-time client.

Example

const receipt = await ablo.decks.update({
  id: 'deck_abc123',
  title: 'Q3 Market Update — Final',
  color: '#10B981',
});

console.log(receipt.status); // 'confirmed'

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

Permanently deletes a deck and all of its slides and layers in one atomic commit.

Parameters

string

required

The deck 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.decks.delete('deck_abc123');
console.log(receipt.status); // 'confirmed'

Resources

Types

Decks API — Create, Retrieve, Update & Delete Decks

`ablo.decks.create(input?, options?)`

Parameters

Returns

Example

`ablo.decks.retrieve(id)`

Parameters

Returns

Example

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

Parameters

Returns

Example

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

Parameters

Returns

Example

​ablo.decks.create(input?, options?)

​Parameters

​Returns

​Example

​ablo.decks.retrieve(id)

​Parameters

​Returns

​Example

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

​Parameters

​Returns

​Example

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

​Parameters

​Returns

​Example

`ablo.decks.create(input?, options?)`

Parameters

Returns

Example

`ablo.decks.retrieve(id)`

Parameters

Returns

Example

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

Parameters

Returns

Example

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

Parameters

Returns

Example