Pixel Place API¶
Status¶
Active — optional backend used by Pixel Place for shared canvas state, quotas, and live updates.
Description¶
Small Node/Express API used by one or more frontends to share a single pixel board. Supports snapshot fetch, pixel placement, optimistic version checks, and SSE updates.
Base URLs¶
- Production example:
https://canvas.kiefermenard.com - Generic production pattern:
https://your-nas.example.com - Local dev:
http://127.0.0.1:3001
CORS¶
Set PLACE_ALLOWED_ORIGINS to exact, comma-separated origins allowed from browsers.
Example:
If unset, all origins are allowed (acceptable for local dev; not ideal for production).
API endpoints¶
| Endpoint | Purpose |
|---|---|
GET /api/place/config |
Canvas dimensions and limits |
GET /api/place/state |
Full board snapshot |
POST /api/place/pixels |
Place 1..N pixels with quota and optional version check |
GET /api/place/events |
SSE stream of delta updates (place events) |
GET /health |
Basic health check |
Key request/response behavior¶
POST /api/place/pixelsuses:userId(stable client ID, 8..128 chars,[a-zA-Z0-9_-]+)expectedVersion(optional optimistic concurrency)pixelslist (cmust be#RRGGBB)- Duplicate coordinates in one request are deduplicated (last wins).
- Common responses:
200success withversion,nextAllowedAt, quota remaining429quota exceeded withretryAfterMs409stale version conflict with latestversion
Rate limits¶
POST /api/place/pixels is limited per IP by default (60 requests / 60s), controlled by:
PLACE_RATE_LIMIT_MAXPLACE_RATE_WINDOW_MS
Environment variables¶
| Variable | Default | Description |
|---|---|---|
PLACE_PORT |
3001 |
Listen port |
PLACE_WIDTH |
200 |
Canvas width |
PLACE_HEIGHT |
200 |
Canvas height |
PLACE_COOLDOWN_SECONDS |
10 |
Quota window length (seconds) |
PLACE_MAX_PIXELS_PER_TURN |
5 |
Max pixels per window per userId |
PLACE_DATA_PATH |
./server/data |
Directory containing place.json |
PLACE_ALLOWED_ORIGINS |
empty | CORS allowlist (empty = allow all) |
PLACE_TRUST_PROXY |
unset | Set to 1 behind reverse proxy |
PLACE_RATE_WINDOW_MS |
60000 |
IP rate-limit window |
PLACE_RATE_LIMIT_MAX |
60 |
Max POSTs per IP per window |
Deployment (Leviathon / reverse proxy)¶
Production runs in Docker on the Synology (Leviathon) from /volume1/docker/personal-website-server/docker-compose.yml, with PLACE_TRUST_PROXY=1. Without it, rate limiting sees the Synology reverse proxy’s internal IP instead of the real client, so limits apply incorrectly. Set PLACE_ALLOWED_ORIGINS to the exact browser origins that may call the API (e.g. https://kiefermenard.com,https://www.kiefermenard.com). Public URL: https://canvas.kiefermenard.com (Cloudflare → Synology 443). See also projects/Self-Hosted-Services.
Watchtower: the API image is built locally, so the service carries a label so Watchtower skips it and does not error on registry lookups:
(See projects/Self-Hosted-Services#watchtower-monitor-only.)
Known issues¶
- None documented in this wiki yet.
Raw sources¶
raw/API.md
Related work¶
- projects/Personal-Website — frontend that consumes this API for Pixel Place.
- projects/Pixel-Place-Friend-Integration — external-site integration playbook.
- projects/Self-Hosted-Services — reverse proxy, DNS, and hosting context.