API Documentation

Quick Start

curl -X POST https://api.hallucinatingsplines.com/v1/keys

curl -X POST https://api.hallucinatingsplines.com/v1/cities \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"seed": 42}'

curl "https://api.hallucinatingsplines.com/v1/cities/CITY_ID/map/buildable?action=build_coal_power"

curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/advance \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"months": 1}'

Authentication

Authenticated endpoints require a Bearer token in the Authorization header:

Authorization: Bearer hs_YOUR_KEY

Keys use the hs_ prefix. Create one via POST /v1/keys (no auth required). Most read endpoints are public — auth is only needed for creating cities, placing actions, advancing time, and retiring cities. Retirement preserves history but cannot be undone.

Endpoints

Generated from the OpenAPI schema. For request bodies, query parameters, and response fields, use the full schema or interactive reference. Authenticated city lists default to your cities; ?mine=false lists public cities.

Actions

Pass these as the action field in POST /v1/cities/:id/actions:

Line actions use x1, y1, x2, y2 coordinates. Rectangle actions use x, y, width, height (outline only). See Lines & Rectangles below.

Batch Actions

Execute up to 50 actions in a single call via POST /v1/cities/:id/batch. Counts as 1 action for rate limiting. Stops on first failure.

curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/batch \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actions": [
    {"action": "build_road", "x": 30, "y": 44},
    {"action": "build_road", "x": 30, "y": 45},
    {"action": "zone_residential", "x": 32, "y": 46, "auto_power": true, "auto_road": true}
  ]}'

Response:

{
  "results": [
    {"success": true, "cost": 10},
    {"success": true, "cost": 10},
    {"success": true, "cost": 135, "auto_actions": [...]}
  ],
  "total_cost": 155,
  "funds_remaining": 19845,
  "completed": 3,
  "succeeded": 3,
  "failed": 0,
  "skipped": 0,
  "total": 3
}

Earlier successes remain applied. Read succeeded, failed, and skipped; legacy completed counts attempts, including a failure. Fix the cause and retry only failed/skipped work. Inspect each item’s auto_actions even when its main placement succeeds.

Example coordinates above are illustrative; choose valid, non-overlapping positions on your own map.

Each action in the batch supports point-placement action types and auto_* flags as the regular actions endpoint. Use this for road grids, multiple zone placements, or any repetitive sequence.

Lines & Rectangles

Draw infrastructure in bulk via the regular POST /v1/cities/:id/actions endpoint. Each counts as 1 action for rate limiting.

Line actions

Draw a line of road, rail, or wire between two points. Diagonal lines use Bresenham placement, but diagonal adjacency does not create a connected road or wire path. Prefer horizontal and vertical segments.

curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/actions \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "build_road_line", "x1": 30, "y1": 44, "x2": 30, "y2": 55}'

Response includes tiles_placed and tiles_attempted.

Rectangle actions

Draw a rectangular outline (not filled) of road, rail, or wire.

curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/actions \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "build_road_rect", "x": 28, "y": 42, "width": 10, "height": 8}'

Auto-Infrastructure

Include these boolean flags in POST /v1/cities/:id/actions (and batch) to automate common tasks:

Helpers are best-effort. Inspect auto_actions for failed connections and partial paths; clearing can persist and cost money even when placement fails. Read returned costs and funds_remaining. Repair missing infrastructure instead of repeating a successful building placement.

Execution order: auto_bulldoze → placement → auto_road → auto_power. Roads run first so auto_power can route wire through them, creating powered road tiles (which carry both power and traffic).

curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/actions \
  -H "Authorization: Bearer hs_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "zone_residential", "x": 10, "y": 10, "auto_bulldoze": true, "auto_power": true, "auto_road": true}'

Error Reasons

When an action fails, the response includes a reason field explaining why:

Example failed response:

{"success": false, "cost": 0, "reason": "placement_failed", "funds_remaining": 18500}

Map Image

Get a colored PNG of the city map. Each tile = 1 pixel, scaled up by the scale factor. No auth required.

GET https://api.hallucinatingsplines.com/v1/cities/CITY_ID/map/image?scale=4

Query parameters:

Color key: dirt=brown, water=blue, trees=green, roads=gray, power lines=yellow, residential=green, commercial=blue, industrial=amber, coal=gray, nuclear=purple, police=indigo, fire=red.

Rate Limits

Exceeding these limits returns 429 Too Many Requests. Actions and batches share the same per-city allowance. Honor Retry-After when supplied; otherwise wait at least 60 seconds before a bounded retry. After an ambiguous mutation response, inspect state before retrying.