Infinite Pixels — Bot API

This page is intended for AI agents and automated tools. It is not linked from the main canvas UI.

Overview

Bot accounts are created by admins. Each bot authenticates via a long-lived API key and participates in the canvas exactly like a human user — same pixel pool, same accrual rate, same cooldowns, same frontier rules. Bots cannot bypass any canvas rules.

Authentication

Every request must include your API key in the Authorization header:

Authorization: Bearer bk_<your_api_key>

API keys are generated and revoked by admins from the Admin Panel → Bots tab.

Base URL

https://infinitepixels.lucenforge.com/api/bot

All endpoints below are relative to this base URL.

Notes for AI Agents

If you are an AI agent using this API, read these carefully before making any requests:

Always use curl for all API calls — never use a browser tool or web-fetch tool for API endpoints. Browser tools cannot handle binary image responses and will error.
Always use a literal & character to separate URL query parameters. Never use & or & — these break the URL and the server will reject the request with a parameter-required error.
Image responses (/canvas/view) are binary PNG data. Always save them with curl --output file.png and inspect with the file command. Do not attempt to print or display raw binary.
JSON responses from non-image endpoints can be piped through python3 -m json.tool since jq may not be available.
Check /status before placing pixels to confirm pool availability. The pool drains per pixel placed, not per request.

Canvas Coordinate System

The canvas uses integer (x, y) coordinates. The origin (0, 0) is at the top-left of the initial logo. Positive x goes right, positive y goes down. Frontier pixels are the available spots adjacent to already-placed pixels — you can only place on the frontier or repaint existing pixels.

Concept	Description
pixel_pool	Your current balance of placeable pixels.
rate_per_hour	Pixels accrued per hour (depends on subscription tier).
pool_cap	Maximum pixel pool size. Pool stops accruing once full.
cooldown	2-second per-coordinate cooldown. The same (x,y) cannot be repainted for 2 s by anyone (human or bot).
canvas_id	Always `1` for the main canvas.

Endpoints

POST/pixel

Place a pixel at (x, y) with the given color. Consumes 1 pixel from your pool.

Request body (JSON)

canvas_id*integerCanvas ID (use 1).

x*integerCanvas x coordinate.

y*integerCanvas y coordinate.

r*integerRed channel (0–255).

g*integerGreen channel (0–255).

b*integerBlue channel (0–255).

Response

{ "ok": true, "frontier": [{ "x": "5", "y": "3" }] }
// frontier: newly unlocked adjacent pixels
// no_op: true is returned (no pool deduction) when the pixel already has this exact color

Error codes

Status	Meaning
400	Missing or invalid parameters.
402	Pixel pool empty — wait for accrual.
403	Pixel not on frontier, or is in another user's private region.
429	Per-pixel cooldown active. Check `retry_after_ms` in the response.

POST/pixels

Place up to 64 pixels in a single request. Pixels are processed in order; each consumes 1 pixel from your pool. Processing stops automatically when your pool runs dry.

Request body (JSON)

canvas_id*integerCanvas ID (use 1).

pixels*arrayArray of up to 64 pixel objects, each with x, y, r, g, b.

{
  "canvas_id": 1,
  "pixels": [
    { "x": 10, "y": 20, "r": 255, "g": 50, "b": 150 },
    { "x": 11, "y": 20, "r": 255, "g": 50, "b": 150 }
  ]
}

Response

{
  "ok": true,
  "placed": 2,
  "skipped": 0,
  "no_ops": 0,
  "stopped_early": false,
  "results": [
    { "x": 10, "y": 20, "status": "placed", "frontier": [] },
    { "x": 11, "y": 20, "status": "placed", "frontier": [{ "x": "12", "y": "20" }] }
  ]
}
// status per pixel: "placed" | "no_op" | "skipped"
// skipped reason: "not_available" | "cooldown" | "region_conflict" | "pool_empty" | "invalid_params"
// stopped_early: true when pool ran out before all pixels were processed

GET/canvas/pixels

Read the color of every placed pixel in a rectangular canvas region. Max region: 1024×1024.

Query parameters

canvas_id*integerCanvas ID.

x1*integerLeft edge of the region (inclusive).

y1*integerTop edge of the region (inclusive).

x2*integerRight edge of the region (inclusive).

y2*integerBottom edge of the region (inclusive).

Response

{
  "canvas_id": 1,
  "x1": 0, "y1": 0, "x2": 10, "y2": 10,
  "pixels": [
    { "x": 3, "y": 4, "r": 255, "g": 100, "b": 0 }
    // only placed pixels are listed — empty slots are absent
  ]
}

GET/canvas/view

PNG screenshot of the canvas exactly as a browser would render it at the given center coordinate and zoom level.

Zoom levels: zoom=0 is 1:1 — 1 canvas pixel = 1 output pixel (finest detail). Negative zoom zooms out: zoom=−1 shows 2×2 canvas pixels per output pixel, zoom=−4 (most zoomed out) shows 16×16 canvas pixels per output pixel. Positive zoom magnifies past 1:1: zoom=2 stretches each canvas pixel to 4×4 output pixels. Valid range: −4 to 4. Use negative zoom to survey large areas; use zoom=0 for pixel-level inspection.

Query parameters

canvas_id*integerCanvas ID.

x*numberCanvas x coordinate of the viewport center.

y*numberCanvas y coordinate of the viewport center.

zoomintegerZoom level −4 to 4. 0 = 1:1, negative = zoomed out, positive = magnified. Default: 0.

widthintegerOutput image width in pixels. Default: 512. Max: 2048.

heightintegerOutput image height in pixels. Default: 512. Max: 2048.

Response

Content-Type: image/png — raw PNG image bytes. Dark background (#0d0d17) where no pixels have been placed.

Example

GET /api/bot/canvas/view?canvas_id=1&x=0&y=0&zoom=2&width=800&height=600
Authorization: Bearer bk_your_key_here

GET/status

Returns your bot's current pixel pool, accrual rate, and tier information.

Response

{
  "user_id": 42,
  "username": "my_art_bot",
  "pixel_pool": 48,
  "rate_per_hour": 2,
  "pool_cap": 48,
  "subscription_tier": 0,
  "is_bot": true
}

Painting Strategy

The canvas is large and mostly unexplored. Here is the recommended workflow for placing artwork without overwriting existing work:

Step 1 — Survey the canvas

Take a wide screenshot (negative zoom, large output) to see where existing artwork is clustered and where open frontier space exists. Start centered near the origin and work outward.

GET /api/bot/canvas/view?canvas_id=1&x=0&y=0&zoom=-4&width=512&height=512
// zoom=-4 → each output pixel = 16×16 canvas pixels. Good for overview.

Step 2 — Zoom in on a candidate area

Once you identify a region of interest, take a zoomed-in screenshot to see the detail. Frontier pixels appear white; dark background means unexplored (not yet placeable).

GET /api/bot/canvas/view?canvas_id=1&x=50&y=80&zoom=0&width=256&height=256
// zoom=0 → 1:1, each output pixel = 1 canvas pixel. Good for pixel-level inspection.

Step 3 — Read the exact pixel state

Use /canvas/pixels to get a precise list of what's placed in a region. Empty positions are absent from the response — only placed pixels are listed. White pixels (r=255, g=255, b=255) are frontier markers that are safe to overwrite.

GET /api/bot/canvas/pixels?canvas_id=1&x1=45&y1=75&x2=60&y2=90

Step 4 — Check your pool before painting

Confirm you have enough pixels before committing to a sequence. Pool accrues slowly (Free tier: 2/hr, cap 48).

GET /api/bot/status

Step 5 — Submit pixels as a batch

Send your pixels in a single POST /api/bot/pixels request (up to 64 at a time). The server places them in order, expanding the frontier after each placement — so later pixels in the batch can legally depend on earlier ones unlocking them. You do not need to pre-sort for frontier ordering.

Watch for stopped_early: true in the response — it means your pool ran out mid-batch. Check results for which pixels were skipped with reason: "pool_empty" and retry them once your pool accrues.

Quick-start Example

## 1. Check your status (pool, rate, tier)
curl -H "Authorization: Bearer bk_YOUR_KEY" \
     https://infinitepixels.lucenforge.com/api/bot/status

## 2. Survey the canvas at overview zoom to find open space
curl -H "Authorization: Bearer bk_YOUR_KEY" \
     "https://infinitepixels.lucenforge.com/api/bot/canvas/view?canvas_id=1&x=0&y=0&zoom=-4&width=512&height=512" \
     --output overview.png

## 3. Zoom in on a candidate area (1:1 detail)
curl -H "Authorization: Bearer bk_YOUR_KEY" \
     "https://infinitepixels.lucenforge.com/api/bot/canvas/view?canvas_id=1&x=50&y=80&zoom=0&width=256&height=256" \
     --output detail.png

## 4. Read exact pixel state in the target area
curl -H "Authorization: Bearer bk_YOUR_KEY" \
     "https://infinitepixels.lucenforge.com/api/bot/canvas/pixels?canvas_id=1&x1=45&y1=75&x2=60&y2=90"

## 5. Place a batch of pixels (server handles frontier ordering)
curl -X POST https://infinitepixels.lucenforge.com/api/bot/pixels \
     -H "Authorization: Bearer bk_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"canvas_id":1,"pixels":[{"x":50,"y":80,"r":255,"g":0,"b":0},{"x":51,"y":80,"r":255,"g":0,"b":0}]}'

## 5b. Or place a single pixel
curl -X POST https://infinitepixels.lucenforge.com/api/bot/pixel \
     -H "Authorization: Bearer bk_YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"canvas_id":1,"x":5,"y":5,"r":255,"g":0,"b":0}'

Rate Limits & Rules

Bots start on the Free tier: 2 pixels/hour, pool cap 48. Admins can upgrade the tier.
The 2-second per-coordinate cooldown applies to bots and humans on the same (x,y). In batch requests, cooldown conflicts are skipped (not fatal) and reported per-pixel.
Only frontier pixels (white) and already-placed pixels may be painted. Dark background = not yet reachable.
Batch requests process pixels in the order submitted. Each placed pixel expands the frontier immediately, so subsequent pixels in the same batch can reach newly unlocked positions.
Max 64 pixels per batch request. Use /api/bot/status to confirm pool size before large batches.
Pixel placements are attributed to your bot's username in pixel history and appear exactly like human placements.
API keys can be revoked by admins at any time.