yoshida yoshida DEV
Open the editor

Docs Contribute

Server API

On this page

yoshida-server serves the editor and a small HTTP API. See Server and Docker for running it.

Method and pathRequestResponse
GET /api/capabilities{ "version", "channel", "format", "render", "max_cards", "max_body_mb", "limits": { "layers", "repeat", "canvas", "image_mp", "set_cards" } }; a limit is a number or null for unlimited, see Limits
POST /api/render{ "files": { path: base64 }, "set", "date", "now", "utc_offset", "format": "png" | "png16" | "pdf" | "svg", "vector", "scale", "crop_marks", "compression" }application/zip with <set>/<card id>.png (.svg for svg), or application/pdf for pdf, or 422 with { "error", "diagnostics" }
GET /api/render/progress?job=<id>{ "found", "stage", "done", "total" } for a render sent with x-yoshida-job: <id>
POST /api/telemetry/ping{ "level": "basic" | "advanced" }204. See Usage Statistics
POST /api/telemetry/events{ "events": [{ "k": "feature" | "export" | "error", "n": name }] }204
GET /api/stats?days=NThe stats the admin marked public, per day
GET /api/stats/pageThe same public stats as a page for people
GET /api/admin/stats, PUT /api/admin/publicwith Authorization: Bearer <admin token>All stats; replace the public flags
GET /*Static files from --web

The API also answers under /editor/api/, where the editor's calls land when it is served from /editor/. A folder asked for without its trailing slash (/editor) redirects to /editor/. A missing static file answers 404 with --web's 404.html when there is one, otherwise with a JSON error.

The editor shows the Render on server switch only when capabilities.render is true.

GET /api/capabilities

{
	"version": "0.8.0",
	"channel": "",
	"format": 1,
	"render": true,
	"max_cards": 1000,
	"max_body_mb": 200,
	"telemetry": {
		"enabled": true,
		"default": "basic",
		"force": null,
		"retention_days": 90
	}
}

telemetry is { "enabled": false } when the server runs with --no-telemetry; force is null, "off" or "basic" and retention_days is null when nothing is deleted. The editor reads it to decide whether to show the usage statistics notice.

POST /api/render

Request body (JSON):

FieldMeaning
filesObject of project path to base64-encoded file content. The whole project: manifest, designs, card files, images, fonts. Paths must stay inside the project
setName of the set to render. Required in practice: an omitted or unknown name is 404
dateUsed when now is not sent: render.date is this date, render.time is 00:00:00 and render.now is that date at midnight UTC. With neither date nor now, the server's current UTC instant is used. Format YYYY-MM-DD
nowUTC instant YYYY-MM-DDTHH:MM:SSZ: render.now. render.date and render.time are it shifted by utc_offset. Overrides date. A malformed value is 400
utc_offsetHours from UTC, -14 to 14, fractions allowed. Replaces the project's utc_offset. Outside that range is 400
formatpng (8-bit, default), png16, pdf (one PDF, one page per card) or svg (one SVG file per card)
vectorOptional. true with "format": "pdf" draws the pages as vectors instead of images (see Command Line: PDF). Default false. Not a boolean, or true with another format, is 400
scaleOptional, a number from 1 to 4. For png, png16 and the image pdf: render at this many times the canvas size (default 1); the PNG dpi grows with it and PDF pages keep their size, and a side over 10000 pixels is a 422 with error 5001. For svg and the vector pdf: pixels per canvas pixel for the parts that stay pixels (layers with a convolution filter), default 2. Anything else is 400
crop_marksOptional, pdf only (image or vector). true puts each page on a white sheet with crop marks at the trim line, like --crop-marks; default false. Not a boolean is 400
sheetOptional, png only. { "cols": 10, "rows": 7 } (1 to 100 each) tiles the cards into sheets like --sheet: the ZIP then holds <set>.png, or <set>-1.png, <set>-2.png and so on when the set takes several, in place of one file per card. Another shape, another format or crop_marks with it is 400; a sheet over 20000 pixels on a side is 422
compressionOptional, PNG only. fast, default (default) or smallest: the deflate effort. The pixels are the same. Anything else is 400

Response:

  • 200 application/zip (stored, not compressed) with one <set>/<card id>.png per card (<set>/<card id>.svg with "format": "svg"; the sheets with "sheet") and Content-Disposition: attachment; filename="<set>.zip". With "format": "pdf": application/pdf, filename="<set>.pdf", one page per card (see Command Line: PDF).
  • 422 application/json { "error": "the project has errors", "diagnostics": [...] } when loading or rendering reported errors. No zip is produced. Diagnostics are described in Diagnostics.

Other statuses (all with { "error": "..." }):

StatusWhen
400Body is not JSON, files is missing or not an object, a file is not base64, a path leaves the project, or now, utc_offset, vector, scale, crop_marks, sheet or compression is invalid
403Rendering is disabled (--no-render)
404Unknown set, unknown /api/... path
405POST /api/render with another method; non-GET/HEAD for static files
413Request body above --max-body-mb, or the set has more cards than --max-cards
500Out of memory while rendering

The server renders cards in parallel (--threads); a vector PDF is drawn on one thread, since vector pages are quick to make. It never downloads images from URLs; an unreachable URL is error 4001, so include the images in files.

An optional x-yoshida-job: <id> header (up to 16 hex digits, not 0) makes the request's progress readable with GET /api/render/progress. Every request is logged on stderr, see Server and Docker.

GET /api/render/progress

?job=<id> names a render sent with x-yoshida-job: <id>. The answer is never cached:

{ "found": true, "stage": "rendering", "done": 12, "total": 120 }
stageMeaning
receivingReading the request body
loadingDecoding the files and loading the project
renderingDrawing the cards; done of total are drawn
packingBuilding the zip or the PDF
finishedThe response was sent
failedThe request ended with an error (see its reply)

An unknown id answers { "found": false }. The server keeps the last 32 renders; a finished one stays readable until its slot is reused.

Example

python3 - <<'EOF' > request.json
import base64, json, pathlib
root = pathlib.Path("examples/poker")
files = {str(p.relative_to(root)): base64.b64encode(p.read_bytes()).decode()
         for p in root.rglob("*") if p.is_file()}
print(json.dumps({"files": files, "set": "courts", "date": "2026-10-08"}))
EOF

curl -sS -X POST --data-binary @request.json http://localhost:8080/api/render -o cards.zip

Static files

Everything else is served from --web. The server maps / to index.html, sends Cache-Control: no-cache, and sets the content type from the file extension.

↑↓ to moveEnter to openEsc to close