{
  "openapi": "3.1.1",
  "info": {
    "title": "Nonogram Maker (Picross from a Picture) API",
    "version": "1.0.0",
    "summary": "Nonograms from a drawing or an image, checked for one solution and fixed with givens.",
    "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://printshopnonogram.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Nonograms from a drawing or an image, checked for one solution and fixed with givens.",
        "description": "Turn a pixel drawing, a built-in picture or a PNG image into a printable nonogram (picross, griddler) with row and column clues. A line solver checks that the puzzle can be solved without guessing; if not, it adds as few given cells as it can until it can. Answer key included.\n\nMethodology:\n- Clues are the lengths of the runs of filled cells in each row and column. Images are reduced to the chosen grid by averaging the Rec. 709 luminance of each cell (transparent parts count as white) and comparing with the threshold.\n- Line solver: for one row or column, a dynamic programme over (cell, block) from both ends marks every cell that is filled in all placements of the blocks consistent with the known cells, or empty in all of them. Rows and columns are repeated until nothing changes. If that solves the grid, the solution is unique.\n- Fix: while cells stay undecided, the undecided cell that settles the most other cells when revealed is printed as a given (filled square or a cross) and the line solver runs again.\n\nPhotos rarely make good nonograms; simple shapes with clear outlines work best. Without givens, a puzzle that is not line-solvable may have several solutions.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "printshop_nonogram",
        "x-owner-app": "printshop",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PrintshopNonogramInput"
              },
              "examples": {
                "example1": {
                  "summary": "Built-in cat",
                  "value": {
                    "source": "picture",
                    "picture": "cat"
                  }
                },
                "example2": {
                  "summary": "Your own drawing",
                  "value": {
                    "source": "grid",
                    "grid": "..####..\n.#....#.\n#.#..#.#\n#......#\n#.#..#.#\n#..##..#\n.#....#.\n..####..",
                    "seed": "smile"
                  }
                },
                "example3": {
                  "summary": "Rocket without automatic givens",
                  "value": {
                    "source": "picture",
                    "picture": "rocket",
                    "fix": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintshopNonogramResult"
                }
              }
            }
          },
          "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"
                }
              }
            }
          }
        }
      },
      "PrintshopNonogramInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "source": {
            "title": "Picture from",
            "type": "string",
            "enum": [
              "picture",
              "grid",
              "image"
            ],
            "default": "picture"
          },
          "picture": {
            "title": "Built-in picture",
            "type": "string",
            "enum": [
              "heart",
              "house",
              "cat",
              "tree",
              "fish",
              "rocket"
            ],
            "default": "cat"
          },
          "grid": {
            "title": "Drawing (# = filled, . = empty)",
            "description": "One line per row, up to 50 × 50.",
            "type": "string",
            "maxLength": 4000,
            "default": ""
          },
          "image": {
            "title": "PNG image",
            "type": "object",
            "description": "Upload as {filename, contentType?, contentBase64}. Max 7813 KiB. Accepts image/png.",
            "additionalProperties": false,
            "required": [
              "filename",
              "contentBase64"
            ],
            "properties": {
              "filename": {
                "type": "string"
              },
              "contentType": {
                "type": "string"
              },
              "contentBase64": {
                "type": "string"
              }
            }
          },
          "cols": {
            "title": "Columns (image)",
            "type": "integer",
            "minimum": 2,
            "maximum": 50,
            "default": 20
          },
          "rows": {
            "title": "Rows (image)",
            "type": "integer",
            "minimum": 2,
            "maximum": 50,
            "default": 20
          },
          "threshold": {
            "title": "Darkness threshold (image, 0–255)",
            "description": "Cells darker than this are filled.",
            "type": "integer",
            "minimum": 1,
            "maximum": 254,
            "default": 128
          },
          "invert": {
            "title": "Invert (light cells filled)",
            "type": "boolean",
            "default": false
          },
          "fix": {
            "title": "Add givens until it solves line by line",
            "type": "boolean",
            "default": true
          },
          "seed": {
            "title": "Seed",
            "description": "The same seed and settings always give the same puzzles. Change it for new ones.",
            "type": "string",
            "maxLength": 80,
            "default": "nonogram-1"
          },
          "title": {
            "title": "Title on the page (optional)",
            "type": "string",
            "maxLength": 120,
            "default": ""
          },
          "answers": {
            "title": "Answer-key pages",
            "type": "boolean",
            "default": true
          },
          "header": {
            "title": "Name and date line",
            "type": "boolean",
            "default": true
          },
          "paper": {
            "title": "Paper size",
            "type": "string",
            "enum": [
              "a3",
              "a4",
              "a5",
              "a6",
              "b5",
              "letter",
              "legal",
              "tabloid",
              "halfletter"
            ],
            "default": "a4"
          },
          "orientation": {
            "title": "Orientation",
            "type": "string",
            "enum": [
              "portrait",
              "landscape"
            ],
            "default": "portrait"
          }
        },
        "required": []
      },
      "PrintshopNonogramResult": {
        "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": [
              "rows",
              "cols",
              "rowClues",
              "colClues",
              "lineSolvable",
              "givens",
              "filledCells",
              "solution",
              "seed",
              "pages",
              "puzzlePages",
              "answerPages",
              "pageWidthMm",
              "pageHeightMm",
              "warnings",
              "files",
              "openInApp"
            ],
            "properties": {
              "rows": {
                "type": "integer"
              },
              "cols": {
                "type": "integer"
              },
              "rowClues": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  }
                }
              },
              "colClues": {
                "type": "array",
                "items": {
                  "type": "array",
                  "items": {
                    "type": "integer"
                  }
                }
              },
              "lineSolvable": {
                "type": "boolean"
              },
              "givens": {
                "type": "integer"
              },
              "filledCells": {
                "type": "integer"
              },
              "solution": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "seed": {
                "type": "string"
              },
              "pages": {
                "type": "integer"
              },
              "puzzlePages": {
                "type": "integer"
              },
              "answerPages": {
                "type": "integer"
              },
              "pageWidthMm": {
                "type": "number"
              },
              "pageHeightMm": {
                "type": "number"
              },
              "warnings": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "files": {
                "type": [
                  "object",
                  "null"
                ],
                "additionalProperties": false,
                "required": [
                  "pdf",
                  "svg",
                  "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)."
                      }
                    }
                  },
                  "svg": {
                    "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"
              }
            }
          }
        }
      }
    }
  }
}