{ "openapi": "3.1.1", "info": { "title": "Printable Flashcards (Double-sided PDF) API", "version": "1.0.0", "summary": "Print flashcards on both sides: questions on the front, answers exactly behind them, as a PDF.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://deckwrightprintcards.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Print flashcards on both sides: questions on the front, answers exactly behind them, as a PDF.", "description": "Lays out flashcards on card or label sheets (business-card size 90 × 54 mm, 99 × 68 mm, 70 × 37 mm and US Letter 4 × 2 in, among others): questions on the front pages, answers on the back pages mirrored for long-edge or short-edge duplex printing, cut lines, registration crosses and a card number on both sides. Text shrinks to fit (down to 6 pt). Also prints questions only, or question and answer side by side for folding. Vector PDF with embedded fonts for Latin, Greek, Cyrillic, Arabic, Devanagari, Chinese, Japanese and Korean.\n\nMethodology:\n- Sheet geometry (paper, columns × rows, card size, margins, pitch) comes from Printshop’s label sheets. Fronts are on odd pages, backs on even pages. For a long-edge flip the back of the card in column c sits in column (columns − 1 − c), x′ = page width − x − card width; for a short-edge flip the rows are mirrored, y′ = page height − y − card height.\n- Text is shaped with embedded Noto fonts and wrapped like slide text (Chinese, Japanese and Korean by characters); it starts at the chosen size and shrinks in 8 % steps down to 6 pt. Cards that still do not fit are cut and listed. Pictures (data URLs) are placed above the text.\n- Reverse cards are not printed separately: a printed card already has the answer on its back.\n- Registration crosses sit 7 mm from each page corner on both sides; hold a printed sheet against the light to check that the printer keeps front and back aligned. Every card carries its number on both sides.\n\nPrinters shift the back side by up to a few millimetres; print one test sheet on plain paper first. Choose “actual size” (100 %) in the print dialog.", "tags": [ "apps" ], "x-mcp-tool": "deckwright_print_cards", "x-owner-app": "deckwright", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckwrightPrintCardsInput" }, "examples": { "example1": { "summary": "Spanish phrases, business-card size, double-sided", "value": { "text": "# Greetings\nhola ::: hello\nbuenos días ::: good morning\ngracias ::: thank you\n\n# Getting around\nQ: How do you ask where the station is?\nA: ¿Dónde está la estación?\n\nla estación :: the station\nel billete :: the ticket\n\n# At the café\nun café con leche :: a coffee with milk\n\nQ: How do you ask for the bill?\nA: la cuenta, por favor\n\nMadrid's main station is {{c1::Atocha}}; the fast train to Barcelona takes about {{c2::two and a half::how long?}} hours.\n", "lang": "es" } }, "example2": { "summary": "Lesson cards from slides, 2 × 4 per A4, short-edge flip", "value": { "text": "---\ntitle: How plants make food\nlang: en\ntheme: harbor\nfooter: Biology · lesson 4\n---\n\n# How plants make food\n\nPhotosynthesis in five slides\n\n---\n\n## The idea in one sentence\n\n\u003e Plants use the energy of light to turn carbon dioxide and water into sugar and oxygen.\n\n---\n\n## What goes in, what comes out\n\n| In | Out |\n|---|---|\n| Carbon dioxide from the air | Sugar (glucose) |\n| Water from the roots | Oxygen |\n| Light energy | |\n\n6 CO₂ + 6 H₂O + light gives C₆H₁₂O₆ + 6 O₂\n\n---\n\n## Where it happens\n\n```mermaid\n%% alt: Photosynthesis happens in the leaf (chloroplasts, stomata) in two stages: light reactions split water and release oxygen; the Calvin cycle fixes carbon dioxide into sugar.\nmindmap\n Photosynthesis\n Leaf\n Chloroplasts\n Stomata\n Light reactions\n Split water\n Release oxygen\n Calvin cycle\n Fix CO₂\n Build sugar\n```\n\n---\n\n## Try it yourself\n\n- Put a water plant under a lamp\n- Count the oxygen bubbles per minute\n- Move the lamp closer and count again\n\nNotes:\nAsk the class to predict the result before moving the lamp.\n\n---\n\n## Bubbles and light\n\n```chart\ntype: line\ntitle: Bubbles per minute (example class data)\nx: Distance (cm)\ny: Bubbles\nalt: The closer the lamp, the more bubbles: from 4 per minute at 50 cm to 31 per minute at 10 cm.\n\nDistance (cm),Bubbles\n10,31\n20,19\n30,11\n40,7\n50,4\n```\n", "format": "deck", "sheet": "a4-2x4-99x68", "flip": "short" } }, "example3": { "summary": "Chemistry formulas on US Letter, side by side for folding", "value": { "text": "front,back\nH2O,water\nNaCl,table salt\nCO2,carbon dioxide\nNH3,ammonia\nCH4,methane\n", "format": "csv", "sheet": "letter-2x5", "sides": "fold" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeckwrightPrintCardsResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "DeckwrightPrintCardsInput": { "type": "object", "additionalProperties": false, "properties": { "text": { "title": "Cards", "description": "Markdown: “Q:” and “A:” lines, “term :: definition” (“:::” also makes the reverse card), {{c1::cloze}} gaps, # headings as tags. Or CSV/TSV rows (front, back, tag), an Anki plain-text export, or a slide deck.", "type": "string", "maxLength": 200000, "default": "# Greetings\nhola ::: hello\nbuenos días ::: good morning\ngracias ::: thank you\n\n# Getting around\nQ: How do you ask where the station is?\nA: ¿Dónde está la estación?\n\nla estación :: the station\nel billete :: the ticket\n\n# At the café\nun café con leche :: a coffee with milk\n\nQ: How do you ask for the bill?\nA: la cuenta, por favor\n\nMadrid's main station is {{c1::Atocha}}; the fast train to Barcelona takes about {{c2::two and a half::how long?}} hours.\n" }, "format": { "title": "Format", "type": "string", "enum": [ "auto", "markdown", "csv", "tsv", "anki", "deck" ], "default": "auto" }, "reverse": { "title": "Also make reverse cards (answer → question)", "type": "boolean", "default": false }, "sheet": { "title": "Card sheet", "type": "string", "enum": [ "a4-2x5-90x54", "a4-2x4-99x68", "a4-3x8-70x37", "a4-2x7-99x38", "letter-2x5", "letter-3x10" ], "default": "a4-2x5-90x54" }, "sides": { "title": "Sides", "type": "string", "enum": [ "both", "front", "fold" ], "default": "both" }, "flip": { "title": "Duplex flip edge", "type": "string", "enum": [ "long", "short" ], "default": "long" }, "cutLines": { "title": "Cut lines around the cards", "type": "boolean", "default": true }, "sizePt": { "title": "Largest text size", "type": "number", "minimum": 8, "maximum": 28, "default": 14, "x-unit": "pt" }, "lang": { "title": "Card language (BCP 47, e.g. en, es, ja)", "description": "Used for answer checks and fonts; empty = English.", "type": "string", "maxLength": 20, "default": "" } }, "required": [] }, "DeckwrightPrintCardsResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "cards", "pages", "sheets", "perSheet", "sheet", "sides", "flip", "cardSizeMm", "cutCards", "warnings", "files", "openInApp" ], "properties": { "cards": { "type": "integer" }, "pages": { "type": "integer" }, "sheets": { "type": "integer" }, "perSheet": { "type": "integer" }, "sheet": { "type": "string" }, "sides": { "enum": [ "both", "front", "fold" ] }, "flip": { "enum": [ "long", "short" ] }, "cardSizeMm": { "type": "object", "additionalProperties": false, "required": [ "w", "h" ], "properties": { "w": { "type": "number" }, "h": { "type": "number" } } }, "cutCards": { "type": "array", "items": { "type": "integer" } }, "warnings": { "type": "array", "items": { "type": "string" } }, "files": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "pdf", "png" ], "properties": { "pdf": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } }, "png": { "type": "object", "additionalProperties": false, "required": [ "artifactId", "filename", "mime", "bytes", "sha256", "path" ], "properties": { "artifactId": { "type": "string" }, "filename": { "type": "string" }, "mime": { "type": "string" }, "bytes": { "type": "integer" }, "sha256": { "type": "string" }, "path": { "type": "string", "description": "Download path on the same site (valid for about 2 hours)." } } } } }, "openInApp": { "type": [ "string", "null" ] } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }