Decks

8 endpoints for working with decks.

List skrolls

get/deckslist_decks

Lists skrolls in the organization. Use scope=mine for those the API key's owner created.

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

Responses

200Skrolls, newest first

Array of Deck

Field	Type	Description
id*	string (uuid)	n/a
title*	string	n/a
brandId*	string (uuid)	Brand whose look and feel the skroll uses
format*	"slides" \| "webpage"	Fixed at creation: paged 16:9 slides, or a scrolling web page
visibility*	"private" \| "org" \| "public"	n/a
publicSlug*	string \| null	Share slug; set on first publish and stable afterwards
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 API key

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 skroll against one of the organization's brands. Call generate_deck afterwards to fill it in.

Example request

curl

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

Request body

Field	Type	Description
brandId*	string (uuid)	Brand to style the skroll with. See list_brands
title	string	n/a
format	"slides" \| "webpage"	n/a

Responses

201The created skroll

Deck

Field	Type	Description
id*	string (uuid)	n/a
title*	string	n/a
brandId*	string (uuid)	Brand whose look and feel the skroll uses
format*	"slides" \| "webpage"	Fixed at creation: paged 16:9 slides, or a scrolling web page
visibility*	"private" \| "org" \| "public"	n/a
publicSlug*	string \| null	Share slug; set on first publish and stable afterwards
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 API key

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, compiled module and theme tokens).

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 API key

403The key's creator lacks access

404Resource not found

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error

Rename or publish a skroll

patch/decks/{id}update_deck

Updates title and/or visibility. Only the key creator's own skrolls can be modified. Setting visibility to 'public' mints a stable share slug.

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
visibility	"private" \| "org" \| "public"	'public' publishes the skroll at /d/{publicSlug}

Responses

200The updated skroll

Deck

Field	Type	Description
id*	string (uuid)	n/a
title*	string	n/a
brandId*	string (uuid)	Brand whose look and feel the skroll uses
format*	"slides" \| "webpage"	Fixed at creation: paged 16:9 slides, or a scrolling web page
visibility*	"private" \| "org" \| "public"	n/a
publicSlug*	string \| null	Share slug; set on first publish and stable afterwards
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 API key

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 the key creator's own skrolls.

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 API key

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

Writes a deck-tsx module (TSX source, optionally theme tokens) as the skroll's newest version, compiled and validated server-side. History is append-only, so this never overwrites an earlier version. Consumes one version edit.

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 API key

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

Generate skroll content with AI

post/decks/{id}/generategenerate_deck

Runs the skroll generator against a brief and saves the result as a new version. Synchronous and slow (typically 60-180 seconds). Consumes one version edit in 'revise' mode.

Example request

curl

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

Parameters

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

Request body

Field	Type	Description
brief*	string	What the skroll should contain or how to change it
mode	"create" \| "revise"	'create' writes the first version; 'revise' edits the latest one

Responses

200The generated version

VersionWriteResult

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

401Missing, malformed, unknown or revoked API key

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

Edit skroll content with AI

post/decks/{id}/editedit_deck

Applies a targeted AI edit (copy tweaks, restyling a slide or beat, adding/removing/reordering a few slides or beats) and saves the result as a new version. Works for both slides and webpage skrolls. Faster and cheaper than generate_deck; use generate_deck for a full restructure. Consumes one version edit.

Example request

curl

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

Parameters

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

Request body

Field	Type	Description
instruction*	string	Precise, self-contained edit instructions for a targeted change. Works for both formats: reference each slide (slides skrolls) or beat (webpage skrolls) by its outline label/number and quote the exact copy being changed. Faster and cheaper than generate_deck; use generate_deck for a full restructure.

Responses

200The edited version

VersionWriteResult

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

401Missing, malformed, unknown or revoked API key

402Out of allowance for a metered feature

403The key's creator lacks access

404Resource not found

409The skroll changed while the edit was being prepared. Retry

422Input failed validation

429Rate limit exceeded. See the Retry-After header

500Unexpected server error