Jigsaw puzzles API reference
Jigsaw puzzles: 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": "jigsaw", "title": "Mountain puzzle", "options": { "tilesX": 5, "tilesY": 5, "shape": "rectangle" } }'Modes
normal
Page presets
Browser export formats
svg · pdf · png · dxf · zip · stl
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.lineColor | text | No |
| appearance.lineWidth | number; minimum 0; maximum 20 | No |
| appearance.strokeOutline | true/false | No |
| appearance.outlineColor | text | No |
| appearance.outlineWidth | number; minimum 0; maximum 10 | 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.thicknessMm | number; minimum 1; maximum 10 | No |
| export.gapMm | number; minimum 0.1; maximum 1 | No |
| input.imageAssetId | text | No |
| options.seed | number; integer; minimum 0; maximum 2147483647 | No |
| options.tilesX | number; integer; minimum 1; maximum 100 | No |
| options.tilesY | number; integer; minimum 1; maximum 100 | No |
| options.sizeX | number; minimum 1; maximum 10000 | No |
| options.sizeY | number; minimum 1; maximum 10000 | No |
| options.tabSize | number; minimum 10; maximum 35 | No |
| options.jitter | number; minimum 0; maximum 10 | No |
| options.cornerRadius | number; minimum 0; maximum 100 | No |
| options.shape | text; minimum 1; maximum 50 | No |
| options.hexRings | number; integer; minimum 1; maximum 20 | 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.