HEADLESS_API_QUICKSTART.md

ProDeck Headless API - Quick Start Guide

Get your ProDeck API running in under 5 minutes!

🎯 Prerequisites

• Node.js 18+ installed
• Google Gemini API key (Get one here)

⚡ Quick Start

1. Set up your API key

# Copy the environment template
cp server/.env.example server/.env

# Edit server/.env and add your API key
# Replace 'your_google_api_key_here' with your actual key

Your server/.env should look like:

GOOGLE_API_KEY=AIzaSyC_your_actual_key_here
PORT=8787

2. Start the server

npm run server:dev

You should see:

✅ ProDeck Headless API running on port 8787
📁 Output directory: /path/to/server/storage/jobs
🔐 Auth: Disabled (no token set)

3. Test it!

Open a new terminal and run:

# Health check
curl http://localhost:8787/api/health

# Generate a simple deck
curl -X POST http://localhost:8787/api/deck/generate \
  -F "prompt=Introduction to Quantum Computing" \
  -F "slideCount=5"

You'll get a response like:

{
  "jobId": "deck_2026-02-16T21-00-00-abc123",
  "status": "queued",
  "statusUrl": "/api/deck/jobs/deck_2026-02-16T21-00-00-abc123",
  "resultUrl": "/api/deck/jobs/deck_2026-02-16T21-00-00-abc123/result"
}

4. Check progress

Use the jobId from the response:

curl http://localhost:8787/api/deck/jobs/deck_2026-02-16T21-00-00-abc123

5. Download your deck

When status is "done":

curl -o my-deck.pptx http://localhost:8787/api/deck/jobs/deck_2026-02-16T21-00-00-abc123/pptx

Then open my-deck.pptx in PowerPoint!

🚀 Using the CLI Tool

For easier usage, use the provided CLI wrapper:

# Make it executable (first time only)
chmod +x scripts/prodeck-generate.sh

# Generate a deck
./scripts/prodeck-generate.sh \
  --prompt "Company Q2 Results" \
  --slides 8 \
  --output ./my-presentations

The script will automatically:

• Submit the job
• Poll for completion
• Download the final PPTX
• Save it to your output directory

📚 Next Steps

Add context files

curl -X POST http://localhost:8787/api/deck/generate \
  -F "prompt=Q2 Financial Review" \
  -F "contextFiles=@./data/q2-report.pdf" \
  -F "contextFiles=@./data/metrics.csv"

Add style references

curl -X POST http://localhost:8787/api/deck/generate \
  -F "prompt=Product Launch" \
  -F "styleImages=@./brand/logo.png" \
  -F "styleImages=@./brand/colors.png"

Using the CLI with files

./scripts/prodeck-generate.sh \
  --prompt "Board Meeting Deck" \
  --docs ./reports/q2.pdf,./notes.md \
  --style ./brand/logo.png,./brand/kit.png \
  --slides 10

🔒 Enable Authentication (Optional)

Add to your server/.env:

PRODECK_API_TOKEN=my-secret-token-12345

Then include it in requests:

curl -H "Authorization: Bearer my-secret-token-12345" \
  -X POST http://localhost:8787/api/deck/generate \
  -F "prompt=Test"

Or with the CLI:

export PRODECK_API_TOKEN=my-secret-token-12345
./scripts/prodeck-generate.sh --prompt "Test"

🐛 Troubleshooting

"Missing GOOGLE_API_KEY"

Make sure you've:

1. Created server/.env (copy from server/.env.example)
2. Added your actual API key
3. Restarted the server

"Port already in use"

Change the port in server/.env:

PORT=8788

Then update your API URL when calling:

curl http://localhost:8788/api/health

Job stuck in "queued"

Check the server logs for errors. Common issues:

• Invalid API key
• Rate limiting
• Network issues

Can't find generated file

Check server/storage/jobs/<jobId>/outputs/ directory.

📖 Full Documentation

• Complete API Documentation
• API Specification
• Main Project README

💡 Example Use Cases

1. Automated Report Generation

Generate weekly reports from CSV data:

./scripts/prodeck-generate.sh \
  --prompt "Weekly Sales Report" \
  --docs ./data/week-$(date +%U).csv

2. Batch Processing

Generate multiple decks:

for topic in "Product A" "Product B" "Product C"; do
  ./scripts/prodeck-generate.sh --prompt "$topic Overview" --slides 6
done

3. CI/CD Integration

Add to your deployment pipeline:

- name: Generate Release Deck
  run: |
    ./scripts/prodeck-generate.sh \
      --prompt "Release Notes v$VERSION" \
      --docs ./CHANGELOG.md \
      --output ./artifacts/

🎓 Tips

1. Slide Count: Start with 5-8 slides for faster generation
2. Context Files: PDFs work best for structured content
3. Style Images: Include 1-2 brand reference images for consistent styling
4. Prompts: Be specific about the presentation audience and purpose
5. Brand Profiles: Create custom profiles in server/brandProfiles/ for your organization

🆘 Need Help?

• Check SERVER_README.md for detailed documentation
• Review prodeck-headless-api-spec.md for API details
• Look at example brand profile: server/brandProfiles/gus-default.json

---

Happy presenting! 🎉