{ "openapi": "3.0.3", "info": { "title": "PaperLesson — Official Public REST & MCP API", "version": "1.0.0", "description": "PaperLesson generates razor-sharp, true-vector printable PDF worksheets for K-12 classrooms, homeschooling parents, and occupational therapy handwriting practice. Unlike blurry bitmap screenshot generators, PaperLesson renders crisp vector paths on US Letter and A4 sheets with exact primary Zaner-Bloser / D’Nealian ruled line heights, seeded reproducible math drills with answer keys, and classroom roster batching. Accessible free in the browser and via MCP and OpenAPI curriculum helpers.", "contact": { "name": "PaperLesson", "url": "https://paperlesson.com", "email": "admin@paperlesson.com" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "externalDocs": { "description": "PaperLesson Official Web Workbench", "url": "https://paperlesson.com" }, "servers": [ { "url": "https://paperlesson.com", "description": "Production Cloudflare Global Edge" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Optional API Key for Albato / automation tracking (e.g. pk_live_paperlesson_2026)" }, "BearerAuth": { "type": "http", "scheme": "bearer" } } }, "paths": { "/api/v1/me": { "get": { "operationId": "verifyApiConnection", "summary": "Verify PaperLesson API Key & Service Health", "description": "Authentication test and metadata endpoint for Albato App Integrator, RapidAPI, Make, and custom workflows.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "responses": { "200": { "description": "Authenticated connection status and tool count", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "example": true }, "authenticated": { "type": "boolean", "example": true }, "service": { "type": "string", "example": "PaperLesson" }, "domain": { "type": "string", "example": "paperlesson.com" }, "version": { "type": "string", "example": "1.0.0" }, "toolsCount": { "type": "integer", "example": 8 } } } } } } } } }, "/api/v1/tools": { "get": { "operationId": "listAvailableTools", "summary": "List All PaperLesson Read-Only Tools & Schemas", "responses": { "200": { "description": "Array of available read-only tools" } } } }, "/api/mcp": { "get": { "operationId": "getMcpServerMetadata", "summary": "Get PaperLesson MCP Server Metadata", "responses": { "200": { "description": "MCP Server metadata and Grade-A tool annotations" } } }, "post": { "operationId": "invokeMcpJsonRpc", "summary": "Execute Streamable HTTP JSON-RPC 2.0 MCP Request", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "id", "method" ], "properties": { "jsonrpc": { "type": "string", "example": "2.0" }, "id": { "type": "integer", "example": 1 }, "method": { "type": "string", "enum": [ "initialize", "tools/list", "tools/call" ], "example": "tools/list" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response envelope" } } } }, "/api/v1/tools/generate_seeded_math_drill_set": { "post": { "operationId": "generate_seeded_math_drill_set", "summary": "Deterministic Seeded K-12 Math Drill & Answer Key Generator", "description": "Generate a reproducible set of K-12 arithmetic, fraction, or order-of-operations practice problems with exact answer keys using deterministic mulberry32 PRNG.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": "string", "enum": [ "addition", "multiplication", "dividing_fractions", "rounding", "pemdas" ], "description": "Math skill topic" }, "count": { "type": "integer", "description": "Number of problems (5-20)", "default": 10 }, "seed": { "type": "integer", "description": "Classroom variant seed integer", "default": 101 } }, "required": [ "topic" ] } } } }, "responses": { "200": { "description": "Deterministic JSON output from generate_seeded_math_drill_set" } } } }, "/api/v1/tools/lookup_handwriting_ruling_specs": { "post": { "operationId": "lookup_handwriting_ruling_specs", "summary": "Zaner-Bloser & D’Nealian Grade-Level Handwriting Line Height Specs", "description": "Look up exact physical millimeter and PostScript point (72 pt/inch) baseline, midline (x-height), and descender spacing for Pre-K through Grade 5 handwriting paper.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "gradeLevel": { "type": "string", "enum": [ "Pre-K", "Kindergarten", "Grade 1", "Grade 2", "Grade 3", "Grade 4-5" ], "description": "Student grade level" } }, "required": [ "gradeLevel" ] } } } }, "responses": { "200": { "description": "Deterministic JSON output from lookup_handwriting_ruling_specs" } } } }, "/api/v1/tools/build_name_tracing_worksheet_config": { "post": { "operationId": "build_name_tracing_worksheet_config", "summary": "Custom Student Name & Classroom Roster Tracing Configurator", "description": "Configure custom student name tracing repetition rows, progressive fade-out scaffolding (solid guide -> dashed trace -> independent baseline), and paper orientation.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "studentName": { "type": "string", "description": "Student full or first name" }, "style": { "type": "string", "enum": [ "manuscript_print", "cursive" ], "default": "manuscript_print", "description": "Letterform handwriting style (\"manuscript_print\" or \"cursive\")" } }, "required": [ "studentName" ] } } } }, "responses": { "200": { "description": "Deterministic JSON output from build_name_tracing_worksheet_config" } } } }, "/api/v1/tools/lookup_cursive_stroke_group_progression": { "post": { "operationId": "lookup_cursive_stroke_group_progression", "summary": "Cursive Handwriting Pedagogical Stroke Family Sequence", "description": "Retrieve the optimal stroke-family teaching order for cursive lowercase and uppercase letters (undercurve, downcurve, overcurve, slant connectors) rather than alphabetical order.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "caseType": { "type": "string", "enum": [ "lowercase", "uppercase" ], "default": "lowercase", "description": "Letter case group (\"lowercase\" or \"uppercase\")" } } } } } }, "responses": { "200": { "description": "Deterministic JSON output from lookup_cursive_stroke_group_progression" } } } }, "/api/v1/tools/generate_fraction_number_line_coordinates": { "post": { "operationId": "generate_fraction_number_line_coordinates", "summary": "Fractions on a Number Line Tick & Partition Calculator", "description": "Compute exact vector tick coordinates and benchmark labels for teaching proper fractions, improper fractions, and equivalent fractions on a 0-to-1 or 0-to-2 number line.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "denominator": { "type": "integer", "description": "Fraction denominator (2, 3, 4, 5, 6, 8, 10, 12)" } }, "required": [ "denominator" ] } } } }, "responses": { "200": { "description": "Deterministic JSON output from generate_fraction_number_line_coordinates" } } } }, "/api/v1/tools/explain_order_of_operations_step_tree": { "post": { "operationId": "explain_order_of_operations_step_tree", "summary": "PEMDAS / BODMAS Order of Operations Step-by-Step Evaluator", "description": "Break down multi-step arithmetic expressions with parentheses, exponents, multiplication/division, and addition/subtraction for Grade 5-6 worksheet answer keys.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "difficulty": { "type": "string", "enum": [ "grade5_no_exponents", "grade6_with_exponents" ], "default": "grade5_no_exponents", "description": "Curriculum complexity tier (Grade 5 parentheses only vs Grade 6 with exponents)" } } } } } }, "responses": { "200": { "description": "Deterministic JSON output from explain_order_of_operations_step_tree" } } } }, "/api/v1/tools/calculate_us_letter_vs_a4_printable_margins": { "post": { "operationId": "calculate_us_letter_vs_a4_printable_margins", "summary": "US Letter vs ISO A4 Vector Printable Safe-Margin Calculator", "description": "Calculate exact PostScript vector coordinates (pt) and safe classroom printer margins (0.5 in / 12.7 mm) to prevent edge clipping across US Letter and ISO A4.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "paperSize": { "type": "string", "enum": [ "US_LETTER", "ISO_A4" ], "default": "US_LETTER", "description": "Physical paper standard (\"US_LETTER\" 8.5x11 in or \"ISO_A4\" 210x297 mm)" } } } } } }, "responses": { "200": { "description": "Deterministic JSON output from calculate_us_letter_vs_a4_printable_margins" } } } }, "/api/v1/tools/list_paperlesson_printable_generators": { "post": { "operationId": "list_paperlesson_printable_generators", "summary": "PaperLesson K-12 Printable Worksheet Generator Directory", "description": "List all free true-vector PDF worksheet generators on PaperLesson with direct pre-configured landing URLs.", "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "all", "handwriting", "math" ], "default": "all", "description": "Curriculum subject filter (\"all\", \"handwriting\", or \"math\")" } } } } } }, "responses": { "200": { "description": "Deterministic JSON output from list_paperlesson_printable_generators" } } } } } }