Agent/API Protocol for Multiplication Chart Printable

Status

Live today: shareable URL parameters on the homepage, live preview, browser-side PDF generation, and multi-page tile controls.

Planned contract: server-readable JSON config validation, preview metadata, and direct PDF file endpoints.

This page is intentionally explicit about the difference. Agents should rely on the URL contract today, and treat the REST endpoints below as the recommended v1 design rather than a production guarantee.

Live URL Contract

Every chart should be representable as a single canonical URL. This is the most important Agent integration point currently available on the site.

Parameter	Type	Allowed values	Meaning
`size`	integer	5, 10, 12, 15, 20, 25, 30, 50, 100	Inclusive upper bound of the multiplication grid.
`start`	integer	0 to `size - 1`	Inclusive lower bound of the grid.
`orient`	enum	`portrait`, `landscape`	Paper orientation for preview and export.
`mode`	enum	`reference`, `blank`, `practice`	Chart type.
`missing`	integer	10 to 90, step 5	Practice-mode blank percentage.
`focus`	string	Comma-separated integers	Optional practice-mode focus numbers.
`theme`	enum	`bw`, `rows`, `squares`, `rainbow`, `contrast`	Visual theme.
`font`	enum	`standard`, `nunito`, `dyslexic`	Display font for preview and export.
`rpp`	integer	0, 10, 12, 15, 20, 25, 50	Rows per page. `0` means all rows.
`cpp`	integer	0, 10, 12, 15, 20, 25, 50	Columns per page. `0` means all columns.
`title`	string	Optional	Custom chart title.
`subtitle`	string	Optional	Optional student name/date line or note.

Normalization rules

Unknown parameters should be ignored.
Unknown enum values should fall back to defaults.
Invalid numbers should clamp to the nearest allowed value or default.
If start >= size, normalize start to size - 1.
If mode is not practice, missing and focus may be accepted but should not affect output holes.

Canonical examples

/
?size=20&start=1&orient=landscape&mode=reference&theme=bw&font=standard&rpp=10&cpp=10

/
?size=30&start=11&orient=landscape&mode=practice&missing=40&focus=7,8,9&theme=rows&font=nunito&rpp=10&cpp=10

Proposed v1 REST Contract

The following endpoints are recommended for server-side Agent integration. They are not yet guaranteed as live production endpoints.

Endpoint	Method	Purpose
`/api/v1/config`	GET	Validate and normalize a request, return pagination metadata and canonical links.
`/api/v1/preview`	GET	Return lightweight preview metadata for inspection without generating a final PDF.
`/api/v1/pdf`	GET	Return the final PDF file directly.

Recommended response: `/api/v1/config`

{
  "version": "1.0",
  "requestId": "req_01hxyz...",
  "normalized": {
    "size": 20,
    "start": 1,
    "orient": "landscape",
    "mode": "reference",
    "missing": 50,
    "focus": [],
    "theme": "bw",
    "font": "standard",
    "rpp": 10,
    "cpp": 10,
    "title": "Multiplication Chart",
    "subtitle": "Name: _________________________  Date: _______________"
  },
  "derived": {
    "rowCount": 20,
    "columnCount": 20,
    "pageCount": 4,
    "tiles": [
      { "page": 1, "rStart": 1, "rEnd": 10, "cStart": 1, "cEnd": 10 },
      { "page": 2, "rStart": 1, "rEnd": 10, "cStart": 11, "cEnd": 20 },
      { "page": 3, "rStart": 11, "rEnd": 20, "cStart": 1, "cEnd": 10 },
      { "page": 4, "rStart": 11, "rEnd": 20, "cStart": 11, "cEnd": 20 }
    ],
    "filename": "multiplication-chart-landscape-1-20-r10-c10.pdf"
  },
  "links": {
    "share": "https://multiplicationchartprintable.app/?size=20&start=1&orient=landscape&mode=reference&theme=bw&font=standard&rpp=10&cpp=10",
    "preview": "https://multiplicationchartprintable.app/api/v1/preview?...",
    "pdf": "https://multiplicationchartprintable.app/api/v1/pdf?..."
  },
  "warnings": []
}

Recommended response: `/api/v1/pdf`

Return application/pdf with Content-Disposition: attachment. The filename should reflect orientation, range, and page tiling to stay deterministic for Agents and users.

Error Model

Even a simple educational generator should return structured errors for Agents. Keep the shape stable.

{
  "error": {
    "code": "invalid_parameter",
    "message": "Parameter 'size' must be one of 5, 10, 12, 15, 20, 25, 30, 50, 100.",
    "details": {
      "parameter": "size",
      "received": 14,
      "allowed": [5, 10, 12, 15, 20, 25, 30, 50, 100]
    }
  },
  "requestId": "req_01hxyz..."
}

invalid_parameter invalid_enum out_of_range unsupported_combination rate_limited export_failed internal_error

Multiplication Chart Printable Agent/API Protocol