Deck API

Generate deck layouts with multiple cards

GET /api/v1/deck/svg Available

GET /api/v1/deck/png Available

Playground

Test the Deck API in real-time by editing the URL below. The deck layout will update automatically as you type.

API URL:

Quick Presets:

Full URL:

/api/v1/deck/svg?cardType=poker

Description

The Deck API generates deck layouts containing multiple cards arranged for printing. It supports different card types, pagination, and print production features like bleed areas and guard lines.

Parameters

Parameter	Type	Required	Description	Example
`cardType`	string	❌	Type of cards to include in deck	`poker`, `standard`
`bleed`	boolean	❌	Include bleed areas for printing	`true`, `false`
`guard`	boolean	❌	Include guard/cut lines	`true`, `false`
`page`	JSON array	❌	Page range to generate [start, end]	`[0, 1]`, `[2, 5]`
`duod`	string	❌	Glyph identifier for cards	`0`, `5`, `A`
`height`	number	❌	Height value for glyphs	`100`
`border`	number	❌	Border width for glyphs	`5`
`thiccness`	number	❌	Thickness of glyph elements	`10`
`bar`	JSON array	❌	Fraction array for bar elements	`[1,2]`
`color`	string	❌	Primary color for glyphs	`blue`, `#FF0000`
`fill`	JSON array	❌	Fill colors array	`["red", "blue"]`
`viewBox`	string	❌	SVG viewBox attribute	`0 0 100 100`
`colorized`	boolean	❌	Enable colorization	`true`, `false`
`borderColor`	string	❌	Border color for cards	`black`, `#000000`
`backgroundColor`	string	❌	Background color for cards	`white`, `#FFFFFF`

Deck-Specific Parameters

`cardType`

Specifies the type of cards to include in the deck. Different card types may have different layouts and arrangements.

`bleed`

When enabled, adds bleed areas around cards for professional printing. Bleed areas ensure no white edges appear after trimming.

`guard`

Adds guard lines (cut lines) to show where cards should be trimmed. Essential for print production.

`page`

Specifies which pages of the deck to generate. Useful for large decks that need to be printed in batches.

Response

Headers

Content-Type: image/svg+xml
Cache-Control: public, max-age=31536000, immutable

Body

Valid SVG markup representing the generated deck layout with multiple cards

Examples

Basic Deck

GET /api/v1/deck/svg

Poker Deck

GET /api/v1/deck/svg?cardType=poker

Deck with Bleed

GET /api/v1/deck/svg?cardType=poker&bleed=true

Deck with Guard Lines

GET /api/v1/deck/svg?cardType=poker&guard=true

Deck with Specific Pages

GET /api/v1/deck/svg?cardType=poker&page=[0,1]

Complete Print-Ready Deck

GET /api/v1/deck/svg?cardType=poker&bleed=true&guard=true&duod=5&colorized=true

Print Production

The Deck API is designed specifically for print production workflows:

Bleed Areas

Enable bleed=true to add extra area around each card that extends beyond the final trim size. This ensures no white edges appear after cutting.

Guard Lines

Enable guard=true to add cut lines that show printers exactly where to trim each card. These lines are essential for professional printing.

Pagination

Use the page parameter to generate specific pages of large decks. This is useful for printing in batches or for quality control.

Usage Examples

HTML Integration

<!-- Embed deck directly -->
<img src="/api/v1/deck/svg?cardType=poker&bleed=true" alt="Poker deck" />

<!-- For print preview -->
<iframe src="/api/v1/deck/svg?cardType=poker&bleed=true&guard=true" 
        width="100%" height="600"></iframe>

Print Workflow

// Generate print-ready deck
GET /api/v1/deck/svg?cardType=poker&bleed=true&guard=true&colorized=true

// Generate specific pages for batch printing
GET /api/v1/deck/svg?cardType=poker&bleed=true&page=[0,4]  // Pages 0-4
GET /api/v1/deck/svg?cardType=poker&bleed=true&page=[5,9]  // Pages 5-9

Card Arrangement

Decks arrange cards in an optimal layout for printing:

Grid Layout: Cards are arranged in a grid pattern to maximize paper usage
Consistent Spacing: Equal spacing between cards for clean cutting
Print Margins: Appropriate margins for most commercial printers
Scalable: Vector format ensures crisp printing at any size

Error Handling

The API handles invalid parameters gracefully:

Invalid JSON in page parameter will be ignored
Invalid boolean values default to false
Invalid cardType values use default layout
Out-of-range page numbers are clamped to valid range
All glyph parameters follow the same error handling as individual endpoints

Performance Considerations

Deck generation involves rendering multiple cards:

Caching: Responses are cached for 1 year for identical parameters
Pagination: Use page parameter for large decks to reduce generation time
Simplified Parameters: Complex parameters (like bar and fill) increase generation time

PNG Endpoint

Available: PNG endpoints are now fully functional and ready for production use!

PNG endpoints accept all the same parameters as SVG endpoints, plus additional PNG-specific options:

PNG-Specific Parameters

Parameter	Type	Description	Example
`scale`	number	Scale factor for higher resolution	`1`, `2`, `3`
`pngWidth`	number	Target width in pixels	`1200`, `2400`
`pngHeight`	number	Target height in pixels	`800`, `1600`
`pngBackground`	string	Background color or "transparent"	`white`, `transparent`, `#F5F5F5`

PNG endpoints are particularly useful for:

High-resolution print production
Print preview thumbnails and web interfaces
Quality control and proofing workflows
Social media sharing of deck layouts
Email marketing and promotional materials
Integration with print-on-demand services