How to batch svg pattern generation with the jad api and runner
- Step 1Get an API key and pair a runner — Generate an API key in your account, then install and pair
@jadapps/runner(see the runner docs). The runner listens onhttp://127.0.0.1:9789. The public API is upload-free; all actual tiling runs through the runner locally. - Step 2Fetch the tool schema — Call
GET /api/v1/tools/svg-pattern-tilerwith your key. The response includesinput.options(the four-option schema with min/max),output.type,execution.runnerMode(engine), andminTier. Use it to build valid payloads programmatically. - Step 3Build the payload — Provide the motif SVG as the input text plus an
optionsobject:tileSize,tileSpacing,tileRotation,patternBg. Numeric options must fall within the schema ranges;patternBgis any CSS colour string and is not range-validated. - Step 4Dispatch to the local runner — POST the payload to
http://127.0.0.1:9789/v1/tools/svg-pattern-tiler/run. The runner runs the in-process engine and returns the generated SVG. Sending content to the cloud/runinstead returns400 Runner requiredwith the runner endpoint to use. - Step 5Loop over your variant matrix — Iterate motifs x sizes x rotations x backgrounds, calling the runner for each combination. Name outputs by token (e.g.
surface-dense-dark.svg). Because output is deterministic, re-runs only change when inputs change. - Step 6Respect rate limits and tiers — The cloud API rate-limits per hour per key (
X-RateLimit-*headers);429means back off. The runner enforces your plan's SVG file limit (free 5 MB, Pro 50 MB, Developer 2 GB). Batch counts scale by tier — Pro 20, pro_media 100, Developer unlimited.
svg-pattern-tiler option schema (as served by the API)
These four options are validated by the engine. Only numeric options are range-checked; patternBg is a free-text colour string. Omit any option to use its default.
| Option | Type | Min / Max | Default | Notes |
|---|---|---|---|---|
| tileSize | number | 10 / 300 | 60 | Nominal tile cell width/height in user units before spacing |
| tileSpacing | number | 0 / 100 | 10 | Added to tileSize to form the repeat cell (cell = tileSize + tileSpacing) |
| tileRotation | number | 0 / 360 | 0 | Degrees; rotates each tile around (tileSize/2, tileSize/2). Omitted from output when 0 |
| patternBg | string | n/a | transparent | Any CSS colour; paints the per-cell background rect. Not range-validated |
Endpoint behaviour and tier limits
The cloud API is auth + schema + rate-limit only. Real tiling runs on the paired runner. File limits are the SVG-category per-tier limits.
| Concern | Cloud /api/v1 | Local runner |
|---|---|---|
| Accepts file content? | No — returns 400 Runner required | Yes — runs the in-process engine |
| Run endpoint | /api/v1/tools/svg-pattern-tiler/run (upload-free) | http://127.0.0.1:9789/v1/tools/svg-pattern-tiler/run |
| Schema endpoint | GET /api/v1/tools/svg-pattern-tiler | (uses the same schema) |
| Auth | API key required; org keys carry per-tool scopes | Paired to your account |
| Rate limit | Per-hour per key (X-RateLimit-* headers, 429 on exceed) | Local — no cloud rate limit on execution |
| File size limit | n/a (no uploads) | free 5 MB / Pro 50 MB / Developer 2 GB |
| Batch files | n/a | free 1 / Pro 20 / pro_media 100 / Developer unlimited |
Cookbook
Patterns shown as conceptual request payloads sent to the local runner. The motif SVG is passed as the input; options drive the variant. Adapt to your HTTP client of choice.
Fetch the schema before building payloads
Always read the schema so your client knows the option ranges and output type rather than hard-coding them.
GET /api/v1/tools/svg-pattern-tiler
Authorization: Bearer <API_KEY>
200 OK (abridged):
{
"input": { "isGenerative": false, "acceptsMultiple": false,
"options": [
{ "name": "tileSize", "type": "number", "min": 10, "max": 300, "default": 60 },
{ "name": "tileSpacing", "type": "number", "min": 0, "max": 100, "default": 10 },
{ "name": "tileRotation", "type": "number", "min": 0, "max": 360, "default": 0 },
{ "name": "patternBg", "type": "string", "default": "transparent" } ] },
"output": { "type": "svg" },
"execution": { "runnerMode": "engine" },
"minTier": "free"
}Cloud /run is upload-free (expect a 400)
Posting content to the cloud endpoint never tiles — it returns pairing instructions. This is the intended security boundary, not an error in your code.
POST /api/v1/tools/svg-pattern-tiler/run
Authorization: Bearer <API_KEY>
{ "input": "<svg>...</svg>", "options": { } }
400 Runner required:
{
"error": "Runner required",
"runnerEndpoint": "http://127.0.0.1:9789/v1/tools/svg-pattern-tiler/run",
"schemaEndpoint": ".../api/v1/tools/svg-pattern-tiler"
}Dispatch one variant to the local runner
The runner runs the same engine the browser uses and returns the generated <pattern> SVG.
POST http://127.0.0.1:9789/v1/tools/svg-pattern-tiler/run
{
"input": "<svg viewBox='0 0 20 20'><circle cx='10' cy='10' r='4' fill='#6366f1'/></svg>",
"options": { "tileSize": 40, "tileSpacing": 20, "tileRotation": 0, "patternBg": "transparent" }
}
-> SVG with <pattern width=60 height=60> (cell = 40 + 20)Generate a density x background matrix
A real design-system pattern set: one motif, three densities, two backgrounds. Loop and name by token.
for size in [30, 50, 80]: # dense / medium / sparse
for bg in ['transparent', '#0f172a']:
POST runner /run with
{ input: motif,
options: { tileSize: size, tileSpacing: round(size*0.25),
tileRotation: 0, patternBg: bg } }
save as surface-{size}-{bg}.svg
# 6 deterministic, diffable pattern tokens from one motifValidation rejects out-of-range numbers
The engine enforces the schema min/max on numeric options so bad input fails loudly instead of producing a broken tile.
options: { tileSize: 5 } # below min of 10
-> Error: Option "tileSize" must be >= 10 (received 5).
options: { tileRotation: 400 } # above max of 360
-> Error: Option "tileRotation" must be <= 360 (received 400).Edge cases and what actually happens
POSTing content to the cloud /run endpoint
400By design, /api/v1/tools/svg-pattern-tiler/run never accepts uploads. It returns 400 Runner required with the localhost runner endpoint. Send your payload to the paired runner instead.
No runner paired
failWith no @jadapps/runner running on 127.0.0.1:9789, there is nowhere to execute the tile. Install and pair the runner first; the cloud API alone cannot process content.
tileSize below 10 or above 300
rejectedNumeric options are validated against the schema. tileSize outside 10-300 throws Option "tileSize" must be >= 10 / <= 300. Clamp values in your client to the schema range.
tileRotation outside 0-360
rejectedRotation is validated to 0-360 degrees. A value like 400 is rejected with a descriptive error. Normalise angles (modulo 360) before sending.
Invalid patternBg colour string
By designpatternBg is not range- or format-validated — whatever string you send is written into the fill attribute. A nonsense value yields an invalid colour the browser ignores (effectively transparent). Validate colour strings client-side.
Missing API key on the cloud endpoints
401Both GET /api/v1/tools/svg-pattern-tiler and the /run endpoint require a valid API key. Without one you get an auth error before any tool logic runs.
Hourly rate limit exceeded
429The cloud API rate-limits per key per hour. A 429 includes the reset time in X-RateLimit-Reset; back off until then. Schema fetches count against the same limit, so cache the schema.
Org key lacks the SVG tool scope
403Org-issued keys carry per-tool scopes. If the key is not granted the SVG category / this tool, the request is denied. Grant the scope in the org settings.
Motif file exceeds the tier limit
rejectedThe runner enforces SVG file limits: 5 MB free, 50 MB Pro, 2 GB Developer. Motif SVGs are normally tiny; an oversized one is blocked. Minify the motif first with the pro minifier.
Expecting batch in one request
Not supportedEach /run call tiles a single motif. There is no multi-motif endpoint — loop over your variant matrix and call the runner per combination. Batch *file count* limits govern how many you can run on your tier.
Frequently asked questions
Can I call the pattern tiler over HTTP with my SVG?
Not against the cloud API directly — /api/v1/tools/svg-pattern-tiler/run is upload-free and returns 400 with pairing instructions. You send content to a paired @jadapps/runner on http://127.0.0.1:9789, which runs the same engine locally.
Why doesn't the cloud endpoint accept files?
JAD's API never receives file content by design — it keeps your data on your machine. The cloud layer handles auth, scopes, rate limiting, and schema; the runner does the work locally.
Where do I get the option schema?
GET /api/v1/tools/svg-pattern-tiler returns input.options (the four options with min/max), output.type (svg), execution.runnerMode (engine), and minTier. Cache it to avoid burning rate-limit budget.
What are the valid option ranges?
tileSize 10-300 (default 60), tileSpacing 0-100 (default 10), tileRotation 0-360 (default 0), and patternBg (any CSS colour string, default transparent). Numeric options are server-validated; out-of-range values are rejected.
Is the output deterministic for CI?
Yes. The same motif plus the same options produces byte-identical SVG, apart from the tile-<stem> id derived from the filename. That makes generated pattern libraries diffable in version control.
How do I generate a whole pattern set?
Loop over your variant matrix (motif x tileSize x rotation x background) and call the runner once per combination, naming each output by its design token. There is no single multi-variant request.
What runner mode does this tool use?
engine — the tiler is server-safe and runs in-process. It does not need a headless browser (unlike Canvas-based SVG tools like the favicon or app-icon generators).
What are the file-size and batch limits?
SVG file limits are 5 MB (free), 50 MB (Pro), 2 GB (Developer). Batch file counts are 1 (free), 20 (Pro), 100 (pro_media), and unlimited (Developer). Motifs are tiny, so size is rarely the constraint.
How does rate limiting work?
The cloud API rate-limits per key per hour and returns X-RateLimit-Limit/Remaining/Reset headers. A 429 carries the reset time. Local runner execution is not cloud-rate-limited, but schema fetches are.
Can an MCP agent use this tool?
Yes — the same runner-backed contract powers the MCP tool. An agent reads the schema, builds the payload, and dispatches to the local runner, so pattern generation can be one step in a larger asset pipeline.
Does the API recolour the motif?
No. The only colour control is patternBg. To recolour the motif in a pipeline, run it through svg-hex-swapper or svg-to-tailwind first, then tile the result.
What's the output format?
Inline SVG containing a single <pattern> definition and a painting rect, on a 300x300 canvas. To deliver it as a CSS background, post-process with svg-css-data-uri.
Privacy first
Every JAD SVG tool runs entirely in your browser using the DOM API and Canvas. Your SVG files never leave your device — verified by zero outbound network requests during processing.