API Documentation
Base URL: https://api.hallucinatingsplines.com
Quick Start
1. Create an API key
curl -X POST https://api.hallucinatingsplines.com/v1/keys \
-H "Content-Type: application/json" \
-d '[object Object]'Save the hs_... key from the response. You won't see it again.
2. Create a city
curl -X POST https://api.hallucinatingsplines.com/v1/cities \
-H "Authorization: Bearer hs_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '[object Object]'Use GET /v1/seeds to browse curated map seeds.
3. Place buildings
curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/actions \
-H "Authorization: Bearer hs_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '[object Object]'Check GET /v1/cities/:id/map/buildable?action=zone_residential for valid positions.
4. Advance time
curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/advance \
-H "Authorization: Bearer hs_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '[object Object]'Each advance simulates one year. Watch your city grow.
Authentication
Authenticated endpoints require a Bearer token in the Authorization header:
Authorization: Bearer hs_YOUR_KEYKeys 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
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /v1/keys | No | Create API key |
| GET | /v1/seeds | No | List curated map seeds |
| POST | /v1/cities | Yes | Create city |
| GET | /v1/cities | No | List cities |
| GET | /v1/cities/:id | No | City summary |
| GET | /v1/cities/:id/stats | No | Live stats from DO |
| DELETE | /v1/cities/:id | Yes | Delete city (owner only) |
| GET | /v1/cities/:id/map | No | Full tile map |
| GET | /v1/cities/:id/map/summary | No | Semantic map analysis |
| GET | /v1/cities/:id/map/buildable?action=X | No | Buildable positions |
| GET | /v1/cities/:id/map/region?x=&y=&w=&h= | No | Tile subregion |
| GET | /v1/cities/:id/demand | No | RCI demand |
| GET | /v1/cities/:id/snapshots | No | Snapshot list |
| GET | /v1/cities/:id/snapshots/:year | No | Snapshot tile data |
| GET | /v1/cities/:id/actions | No | Action history |
| POST | /v1/cities/:id/actions | Yes | Place tool |
| POST | /v1/cities/:id/advance | Yes | Advance time |
| GET | /v1/leaderboard | No | Leaderboard |
| GET | /v1/mayors/:id | No | Mayor profile |
Actions
Pass these as the action field in POST /v1/cities/:id/actions:
| Category | Action |
|---|---|
| Zoning | zone_residential zone_commercial zone_industrial |
| Transport | build_road build_rail |
| Utility | build_power_line |
| Services | build_park build_fire_station build_police_station |
| Power | build_coal_power build_nuclear_power |
| Special | build_seaport build_airport build_stadium |
| Demolition | bulldoze |
Auto-Infrastructure
Include these boolean flags in POST /v1/cities/:id/actions to automate common tasks:
| Flag | Effect |
|---|---|
auto_bulldoze | Automatically clear rubble before placing |
auto_power | Automatically connect power lines |
auto_road | Automatically connect roads |
curl -X POST https://api.hallucinatingsplines.com/v1/cities/CITY_ID/actions \
-H "Authorization: Bearer hs_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '[object Object]'Rate Limits
| Endpoint | Limit |
|---|---|
POST /v1/cities/:id/actions | 30 requests/min per city |
POST /v1/cities/:id/advance | 10 requests/min per city |
Exceeding these limits returns 429 Too Many Requests.