Schemas¶

These schemas are product contracts, not documentation artifacts.

Deckrun is schema-driven at every layer. The schemas below define the wire formats for requests, responses, and generated artifacts. They are versioned, stable, and served at permanent URLs.

Agents and tools should reference these schemas directly for validation, generation, and reasoning.

Public schemas¶

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

Slide Format

Markdown surface syntax for presentation decks: layout directives, two-column regions, notes blocks, timers, attributes, and inline images.

deckrun-slide-format.json

Slide (Parsed)

Renderer-independent intermediate representation (IR). Use to validate a JSON deck after markdown parsing.

deckrun-slide.json

Theme Profile

Theme resource describing branding, colors, typography, layout hints, and contact metadata for PDF and video outputs.

deckrun-theme-profile.json

Narration Voice

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

deckrun-voice.json

Notes Audio Manifest

Manifest generated alongside .notes.mp3 and .notes.cue. Provides per-slide timing for video pipelines and chapter markers.

deckrun-notes-audio-manifest.json

Job Status

Response schema for synchronous and asynchronous jobs. Includes queue position, estimated wait time, and terminal states.

deckrun-job-status.json

User Account

Account shape returned by GET /me. Includes plan tier, RU balance, subscription status, and usage cap.

deckrun-user-account.json

OpenAPI Specification

Complete REST API definition: endpoints, request and response schemas, authentication, and error models.

deckrun-openapi.yaml

Schema conventions¶

Each schema’s $id is its canonical, permanent URL
(e.g. https://agenticdecks.com/schemas/v1/deckrun-voice.json)
All schemas conform to JSON Schema 2020-12
The version appears in the URL path (/v1/)
Breaking changes increment the major version
Internal-only schemas (e.g. connector internals, TTS engines) 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 and stable integration with the Deckrun API
Support validation, tooling, and agent reasoning
Serve as the canonical reference for Deckrun execution behavior

You may use these schemas to build applications and agents 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.