Schemas¶

These schemas are product contracts, not documentation artifacts.

Deckrun is schema-driven at every layer. The schemas below define the wire format for requests, responses, and artifacts. They are versioned, stable, and served at permanent URLs. Agents and tools should reference them directly for validation and reasoning.

Public schemas¶

All schemas are served at /schemas/v1/. Source files are in the Deckrun server repository. These URLs are permanent.

Slide Format

Markdown surface syntax for presentation decks: layout tags, two-column, notes, timer, attributes, inline images.

deckrun-slide-format.json

Slide (Parsed)

Renderer-independent intermediate representation (IR). Validate a JSON deck after parsing markdown.

deckrun-slide.json

Theme Profile

Theme resource: branding, colors, typography, layout hints, and contact info for PDF and video output.

deckrun-theme-profile.json

Narration Voice

Voice resource: tier (system or premium), status, capabilities. Referenced by voice_id in POST /generate.

deckrun-voice.json

Notes Audio Manifest

Manifest produced alongside .notes.mp3 and .notes.cue. Per-slide timing for video pipeline and chapter markers.

deckrun-notes-audio-manifest.json

Job Status

Response shape for sync and async jobs. Includes queue position, estimated wait, and terminal statuses.

deckrun-job-status.json

User Account

Account shape returned by GET /me. Plan tier, credits, seats for team and enterprise plans.

deckrun-user-account.json

OpenAPI Spec

Full REST API specification. All endpoints, request shapes, response shapes, and error codes.

deckrun-openapi.yaml

Schema conventions¶

$id fields are the canonical, permanent URL for each schema (e.g. https://agenticdecks.com/schemas/v1/deckrun-voice.json)
All schemas use JSON Schema 2020-12
Version is in the URL path (/v1/). Breaking changes increment the version.
Internal schemas (e.g. TTS connector internals) are not published

Schema usage and license¶

The Deckrun schemas published on this site are publicly readable but not open source.

These schemas are provided to:

Enable correct integration with the Deckrun API
Allow validation, tooling, and agent reasoning
Serve as the canonical reference for Deckrun execution

You may use these schemas to build applications that call the Deckrun service. You may not copy, modify, or use these schemas to build or offer a competing document execution, rendering, or narration service.

A machine-readable NOTICE.txt is served alongside the schema files at /schemas/v1/NOTICE.txt.