Quickstart

Get from zero to a generated PDF in five steps.

Prerequisites

Step 1: Get the slide format schema

curl https://agenticdecks.com/schemas/v1/deckrun-slide-format.json

This schema defines the markdown surface syntax Deckrun expects: slide boundaries, layout directives, notes blocks, timing hints, and inline attributes.

You can also fetch it dynamically via the API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.agenticdecks.com/schema?category=slide

Agents should cache this schema and validate markdown before submission.

Step 2: Write a minimal deck

<!-- <title-slide /> -->
# My Deck

A presentation generated by Deckrun.

---

<!-- <title-content-slide /> -->

## Slide 2: What this is

Deckrun turns markdown into PDFs.

<!-- <slide-notes> -->
This slide explains what Deckrun is.
<!-- </slide-notes> -->

---
<!-- <title-content-slide /> -->
## Slide 3: How it works

Markdown in. PDF, video, audio out.

Step 3: Submit a generation job

curl -X POST https://api.agenticdecks.com/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "<your markdown here>",
    "slide_theme_id": "deckrun-default",
    "output_types": ["pdf"]
  }'

Response

Lightweight jobs (PDF-only, small decks) may complete synchronously:

{
  "job_id": "j_abc123",
  "status": "success",
  "result": {
    "pdf_url": "https://artifacts.agenticdecks.com/j_abc123/deck.pdf"
  }
}

For heavier outputs (video, audio, premium voice), the API responds with 202 Accepted with status: "queued" (queues the job):

{
  "job_id": "j_abc123",
  "status": "queued"
}

Step 4: Poll for status (async jobs)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.agenticdecks.com/jobs/j_abc123

Response:

{
  "job_id": "j_abc123",
  "status": "success",
  "result": {
    "pdf_url": "https://artifacts.agenticdecks.com/j_abc123/deck.pdf",
    "video_url": "https://artifacts.agenticdecks.com/j_abc123/deck.mp4"
  }
}

Poll until status is one of:

For in-progress jobs, the response includes queue_position and estimated_wait_seconds.

Step 5: Download or deliver

Retrieve the artifact URL directly, or configure an output_destination in the POST /generate request to push artifacts to S3, Google Drive, Slack, or another supported connector.

Next steps