Skroll API: Decks

6 endpoints for working with decks.

List skrolls

get/deckslist_decks

Lists skrolls in the organization. Use kind=template for the design starting points the team shares, which is how you find one to build on. Use scope=mine for those you created. When visibility is public, publicUrl is the viewer (https://skrollai.com/d/{publicSlug}). Share publicUrl, not a URL built from the deck id.

Example request

curl

curl -X GET https://skrollai.com/api/v1/decks \
  -H "Authorization: Bearer sk_..."

Parameters

Parameter	In	Type	Description
scope	query	"mine" \| "org"	n/a
kind	query	"deck" \| "template"	n/a
includeArchived	query	"true" \| "false"	n/a

Responses

200Skrolls, newest first

Array of Deck

Field	Type	Description
id*	string (uuid)	n/a
title*	string	n/a
brandId*	string (uuid) \| null	Brand whose look and feel the skroll uses, if it has one
kind*	"deck" \| "template"	'template' means the organization starts new skrolls from this one. A template is an ordinary skroll otherwise: same versions, same editing, same export
description*	string	What it is for. Mainly used by templates, where it is how the team picks one
archived*	boolean	A retired template: still named by skrolls built from it, no longer offered
startedFromDeckId*	string (uuid) \| null	The skroll (often a template) this one's design was built on
format*	"slides" \| "webpage"	Fixed at creation: paged 16:9 slides, or a scrolling web page. Only 'slides' can be created through this API; 'webpage' appears on skrolls made in the app.
visibility*	"private" \| "org" \| "public"	n/a
publicSlug*	string \| null	Share slug used in /d/{publicSlug}; set on first publish and stable afterwards
publicUrl*	string (uri) \| null	Absolute viewer URL when visibility is public (https://skrollai.com/d/{publicSlug}). Share this with humans. Null otherwise. Never build a link from the deck id.
organizationId*	string	n/a
ownerId*	string	n/a
createdAt*	string (date-time)	n/a
updatedAt*	string (date-time)	n/a

401Missing, malformed, unknown or revoked credentials

403The key's creator lacks access

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error

Create a skroll

post/deckscreate_deck

Creates an empty slides skroll. Write it yourself and save it with set_deck_content. brandId is optional (omit to create without a brand). Pass fromDeckId to build on an existing skroll's design, usually a template. Webpage starting points are refused: this API only authors slides. Pass kind='template' to create a template directly rather than making a skroll and converting it afterwards. ALWAYS READ THIS FIRST. Call get_authoring_instructions before you write anything. It is essential: it defines the format. Do not skip it.

Example request

curl

curl -X POST https://skrollai.com/api/v1/decks \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "format": "slides"
  }'

Request body

Field	Type	Description
brandId	string (uuid) \| null	Brand to style the skroll with. See list_brands. Omit to create a skroll without a brand
fromDeckId	string (uuid) \| null	Build on this skroll's design. Usually a template (list_decks with kind=template), but any skroll you can read will do. A starting point, not a copy: the content is written fresh into its design. This API only authors slides, so a webpage starting point is refused. Brand comes from it unless you name one
kind	"deck" \| "template"	Pass 'template' to create it AS a template, rather than making a skroll and converting it later. Defaults to 'deck'
description	string	What it is for. Worth writing for a template: it is how the team picks one
title	string	n/a
format	"slides"	Paged 16:9 slides, the only format this API can author. The app's scroll-native 'webpage' engine has a different component vocabulary that get_authoring_instructions does not cover, and format cannot be changed later.

Responses

201The created skroll

Deck

Field	Type	Description
id*	string (uuid)	n/a
title*	string	n/a
brandId*	string (uuid) \| null	Brand whose look and feel the skroll uses, if it has one
kind*	"deck" \| "template"	'template' means the organization starts new skrolls from this one. A template is an ordinary skroll otherwise: same versions, same editing, same export
description*	string	What it is for. Mainly used by templates, where it is how the team picks one
archived*	boolean	A retired template: still named by skrolls built from it, no longer offered
startedFromDeckId*	string (uuid) \| null	The skroll (often a template) this one's design was built on
format*	"slides" \| "webpage"	Fixed at creation: paged 16:9 slides, or a scrolling web page. Only 'slides' can be created through this API; 'webpage' appears on skrolls made in the app.
visibility*	"private" \| "org" \| "public"	n/a
publicSlug*	string \| null	Share slug used in /d/{publicSlug}; set on first publish and stable afterwards
publicUrl*	string (uri) \| null	Absolute viewer URL when visibility is public (https://skrollai.com/d/{publicSlug}). Share this with humans. Null otherwise. Never build a link from the deck id.
organizationId*	string	n/a
ownerId*	string	n/a
createdAt*	string (date-time)	n/a
updatedAt*	string (date-time)	n/a

401Missing, malformed, unknown or revoked credentials

402Out of allowance for a metered feature

403The key's creator lacks access

404Resource not found

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error

Get a skroll

get/decks/{id}get_deck

Returns a skroll's metadata plus the content of its latest version (deck-tsx source and theme tokens). When visibility is public, publicUrl is the live viewer (https://skrollai.com/d/{publicSlug}). Share that field. Do not invent a link from the deck id.

Example request

curl

curl -X GET https://skrollai.com/api/v1/decks/0b1e0f7c-1c3f-4a0e-9f5a-1a2b3c4d5e6f \
  -H "Authorization: Bearer sk_..."

Parameters

Parameter	In	Type	Description
id*	path	string (uuid)	n/a

Responses

200The skroll

401Missing, malformed, unknown or revoked credentials

403The key's creator lacks access

404Resource not found

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error

Rename, publish, or make a skroll a template

patch/decks/{id}update_deck

Updates title, visibility, description, archived, and kind. Set kind='template' to promote a skroll the team should start from, or kind='deck' to demote it. Only skrolls you own can be modified. Setting visibility to 'public' mints a stable publicSlug and returns publicUrl as https://{host}/d/{publicSlug} (example: https://skrollai.com/d/f4zqohxo7d). Share publicUrl. Do not invent a link from the deck id.

Example request

curl

curl -X PATCH https://skrollai.com/api/v1/decks/0b1e0f7c-1c3f-4a0e-9f5a-1a2b3c4d5e6f \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Parameters

Parameter	In	Type	Description
id*	path	string (uuid)	n/a

Request body

Field	Type	Description
title	string	n/a
kind	"deck" \| "template"	Promote a skroll the team should start from to 'template', or demote it back to 'deck'
description	string	n/a
archived	boolean	Retire a template. Skrolls built from it keep naming it; it stops being offered
visibility	"private" \| "org" \| "public"	'public' publishes the skroll. The response publicUrl is the viewer link (https://skrollai.com/d/{publicSlug}). Share publicUrl, not a URL built from the deck id.

Responses

200The updated skroll

Deck

Field	Type	Description
id*	string (uuid)	n/a
title*	string	n/a
brandId*	string (uuid) \| null	Brand whose look and feel the skroll uses, if it has one
kind*	"deck" \| "template"	'template' means the organization starts new skrolls from this one. A template is an ordinary skroll otherwise: same versions, same editing, same export
description*	string	What it is for. Mainly used by templates, where it is how the team picks one
archived*	boolean	A retired template: still named by skrolls built from it, no longer offered
startedFromDeckId*	string (uuid) \| null	The skroll (often a template) this one's design was built on
format*	"slides" \| "webpage"	Fixed at creation: paged 16:9 slides, or a scrolling web page. Only 'slides' can be created through this API; 'webpage' appears on skrolls made in the app.
visibility*	"private" \| "org" \| "public"	n/a
publicSlug*	string \| null	Share slug used in /d/{publicSlug}; set on first publish and stable afterwards
publicUrl*	string (uri) \| null	Absolute viewer URL when visibility is public (https://skrollai.com/d/{publicSlug}). Share this with humans. Null otherwise. Never build a link from the deck id.
organizationId*	string	n/a
ownerId*	string	n/a
createdAt*	string (date-time)	n/a
updatedAt*	string (date-time)	n/a

401Missing, malformed, unknown or revoked credentials

403The key's creator lacks access

404Resource not found

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error

Delete a skroll

delete/decks/{id}delete_deck

Permanently deletes a skroll and all of its versions. Only skrolls you own.

Example request

curl

curl -X DELETE https://skrollai.com/api/v1/decks/0b1e0f7c-1c3f-4a0e-9f5a-1a2b3c4d5e6f \
  -H "Authorization: Bearer sk_..."

Parameters

Parameter	In	Type	Description
id*	path	string (uuid)	n/a

Responses

200Deleted

Deleted

Field	Type	Description
deleted*	true	n/a

401Missing, malformed, unknown or revoked credentials

403The key's creator lacks access

404Resource not found

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error

Replace skroll content

put/decks/{id}/contentset_deck_content

Saves a deck-tsx module (TSX source, optionally theme tokens) as the skroll's newest version, compiled and validated server-side. This is how a skroll gets written: you author the module, this stores it. Pass it in full, since it replaces the whole thing. A module that does not compile is rejected with the compiler's message and nothing is saved. History is append-only. Consumes one version edit. ALWAYS READ THIS FIRST. Call get_authoring_instructions before you write anything. It is essential: it defines the format. Do not skip it.

Example request

curl

curl -X PUT https://skrollai.com/api/v1/decks/0b1e0f7c-1c3f-4a0e-9f5a-1a2b3c4d5e6f/content \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source": "<source>"
  }'

Parameters

Parameter	In	Type	Description
id*	path	string (uuid)	n/a

Request body

Field	Type	Description
source*	string	Deck-tsx module source (TSX) that default-exports the deck root, importing only the player's component vocabulary. Compiled server-side.
tokensCss	string	Theme tokens (:root CSS block, optionally preceded by Google Fonts @imports). Defaults to the latest version's tokens.
prompt	string	Note recorded alongside the version

Responses

200The created version

VersionWriteResult

Field	Type	Description
id*	string (uuid)	n/a
version*	integer	n/a

401Missing, malformed, unknown or revoked credentials

402Out of allowance for a metered feature

403The key's creator lacks access

404Resource not found

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error