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 -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}'

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 deleting cities.

Endpoints

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,
  "total": 3
}

Each action in the batch supports the same 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. Supports diagonals (Bresenham line).

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:

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. Use batch and line/rect actions to do more within the limit.