Bingo cards API reference
Bingo cards: This reference reads modes, presets, formats and accepted fields from the same registry and input contract as the API.
Example request
curl -X POST https://puzzlegenio.com/api/v1/puzzles \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Idempotency-Key: task-000000000001' \
-H 'Content-Type: application/json' \
-d '{ "type": "bingo", "title": "Party bingo", "input": { "words": [ "APPLE", "BANANA", "CHERRY", "DATE", "FIG", "GRAPE", "KIWI", "LEMON", "MANGO" ] }, "options": { "gridSize": 3, "cardCount": 1 } }'Modes
classic · signature · number · blank
Page presets
Browser export formats
pdf · caller-pdf
Formats reflect the puzzle configuration and account plan. The creation response gives viewUrl and exportPageUrl for browser downloads; it does not contain PDF, PNG or STL bytes. The saved export policy is fixed when published and is checked again on republish.
Common request fields
| Field | Accepted value | Required |
|---|---|---|
| preset | text | No |
| mode | text | No |
| locale | one of; en | zh | es | de | fr | pt | it | id | ja | ko | No |
| contentLanguage | one of; en | zh | es | de | fr | pt | it | id | ja | ko | No |
| title | text | Yes |
| retentionDays | number; integer | No |
| appearance.themeColor | text | No |
| appearance.title.fontFamily | one of; sans | serif | handwriting | playful | mono | No |
| appearance.title.fontWeight | one of; normal | medium | semibold | bold | extrabold | No |
| appearance.title.color | text | No |
| appearance.title.align | one of; left | center | right | No |
| appearance.title.maxFontSize | number; minimum 6; maximum 120 | No |
| appearance.grid.shape | one of; square | circle | No |
| appearance.grid.corners | one of; sharp | sm | md | lg | No |
| appearance.grid.gap | one of; none | sm | md | lg | No |
| appearance.grid.colorMode | one of; mono | checker | No |
| appearance.grid.bg | one of; text | transparent | object | No |
| appearance.grid.textFontFamily | one of; sans | serif | handwriting | playful | mono | No |
| appearance.grid.textFontWeight | one of; normal | medium | semibold | bold | extrabold | No |
| appearance.grid.textColor | text | No |
| appearance.grid.borderWidth | number; integer; minimum 0; maximum 3 | No |
| appearance.grid.borderColor | text | No |
| appearance.grid.borderStyle | one of; solid | dashed | dotted | No |
| appearance.card.bgColor | one of; text | transparent | object | No |
| appearance.card.borderRadius | one of; sharp | rounded | No |
| appearance.card.borderWidth | number; integer; minimum 0; maximum 3 | No |
| appearance.card.borderColor | text | No |
| appearance.header.bgColor | one of; text | transparent | object | No |
| appearance.header.fontFamily | one of; sans | serif | handwriting | playful | mono | No |
| appearance.header.fontWeight | one of; normal | medium | semibold | bold | extrabold | No |
| appearance.header.color | text | No |
| appearance.header.maxFontSize | number; minimum 6; maximum 120 | No |
| appearance.footer.enabled | true/false | No |
| appearance.footer.text | text; maximum 200 | No |
| appearance.footer.fontFamily | one of; sans | serif | handwriting | playful | mono | No |
| appearance.footer.fontWeight | one of; normal | medium | semibold | bold | extrabold | No |
| appearance.footer.color | text | No |
| appearance.footer.align | one of; left | center | right | No |
| appearance.footer.maxFontSize | number; minimum 6; maximum 120 | No |
| appearance.columnHeaders | list; maximum 5 | No |
| appearance.columnHeaders[] | text; minimum 1; maximum 8 | No |
| appearance.showColumnHeaders | true/false | No |
| appearance.randomization | one of; full | column | No |
| appearance.freeSpaceLabel | text; maximum 40 | No |
| appearance.signatureLines | true/false | No |
| appearance.fontFamily | one of; sans | serif | handwriting | playful | mono | No |
| appearance.fontSize | one of; small | medium | large | No |
| appearance.headerBgColor | text | No |
| appearance.showGridLines | true/false | No |
| appearance.outerBorder | true/false | No |
| appearance.borderStyle | one of; solid | dashed | dotted | No |
| export.paperSize | one of; A3 | A4 | A4-landscape | A5 | B5 | Letter | Letter-landscape | Legal | Half-Letter | Tabloid | custom | No |
| export.widthMm | number; minimum 50; maximum 2000 | No |
| export.heightMm | number; minimum 50; maximum 2000 | No |
| export.unit | one of; mm | cm | in | px | No |
| export.quality | one of; standard | high | print | No |
| export.layout | one of; 1x1 | 1x2 | 2x2 | 2x4 | No |
| input.words | list; minimum 1; maximum 200 | No |
| input.words[] | text; minimum 1; maximum 50 | No |
| input.numbers | list | No |
| input.numbers[] | number; integer; minimum 0; maximum 9999 | No |
| options.seed | number; integer; minimum 0; maximum 2147483647 | No |
| options.gridSize | one of; 3 | 4 | 5 | No |
| options.cardCount | number; integer; minimum 1; maximum 100 | No |
| options.freeSpace | true/false | No |
| options.minNumber | number; integer; minimum 0; maximum 9999 | No |
| options.maxNumber | number; integer; minimum 0; maximum 9999 | No |
| options.ballCount | one of; 30 | 75 | 80 | No |
| options.signatureLine | true/false | No |
Templates and themes
Query /api/v1/capabilities for currently available template IDs, themes and account-specific limits. A template selection still creates one saved puzzle.
Images and files
Image input uses a previously uploaded or imported assetId owned by the API key account. Downloads are performed on the result page in a browser; a result URL is not a direct file URL.
Failure cases
Unknown fields or incompatible type, mode and preset combinations return 422. Inputs that cannot produce a complete puzzle also return 422. Available formats depend on configuration and account rights.