A House Divided - Public API v1

Base URL: https://ahousedividedgame.com

Use the API to build tools that read game data or automate fund transfers and forex trades. Generate keys in Settings -> API Keys in-game.

This document is canonical. The old in-app /api-guide page redirects here.

Authentication#

All API requests require a personal API key in the X-API-Key header:

X-API-Key: ahd_pub_...   # public scope (read-only)
X-API-Key: ahd_priv_...  # private scope (read + write)

Key scopes:

You can have up to 3 active keys per scope type. The full token is shown only once at creation.

Rate limits#

Rate-limited responses return HTTP 429 with a Retry-After header (seconds).

Usage guidelines#

• Cache responses when possible. Game state turns over every few minutes; polling faster than once per minute is unnecessary.
• Do not create multiple keys to circumvent limits. All requests under your account count toward the same quota regardless of which key you use.
• Never commit keys to source control or embed them in client-side code. Revoke compromised keys immediately in Settings.
• Automated fund transfers respect all in-game rules (cooldowns, minimums, same-country restrictions, admin pauses). Attempting to bypass them revokes API access.
• Abuse (repeated rate-limit violations, key sharing) results in key revocation and possibly account-level API restrictions.

Response envelope#

Success:

{ "ok": true, ... }

Error:

{ "ok": false, "error": "Human-readable message", "code": "ERROR_CODE" }

Stability contract#

/v1/ endpoints are additive-only. Fields may be added; existing fields will not be removed or renamed. Breaking changes will be released under /v2/.

All timestamps are UTC ISO 8601.

Error responses#

Public read endpoints#

All accessible with any personal API key via X-API-Key.

GET /api/public/v1/game#

Current game state and turn timing.

GET /api/public/v1/character#

Search characters. Requires name or discordId query param. Alias: GET /api/public/v1/characterSearch (same params and response).

Response: ok, found, characters[] with fields:

GET /api/public/v1/character/[id]#

Full character details by public sequential id (e.g. 75) or ObjectId. Same field shape as the characters array above, wrapped as { ok, found, character } with additional detail fields.

GET /api/public/v1/character/[id]/career#

Character career history.

GET /api/public/v1/character/[id]/achievements#

Achievements earned by a character.

GET /api/public/v1/party?id=ID&country=CODE#

Party details. Both id and country params required.

GET /api/public/v1/country#

List every registered country in runtime order.

Response rows: countries[].id, name, governmentType, status, enabledForPlayers, economyPreview, currencyCode, regionCount, population, and gdpMillions.

GET /api/public/v1/country/[code]#

Country details by code (e.g. US, GB).

GET /api/public/v1/country/[code]/legislature#

Legislature details for a country.

GET /api/public/v1/country/[code]/economy#

Economic indicators for a country.

GET /api/public/v1/country/[code]/economy/history#

Bounded historical monetary, growth, inflation, fiscal, and sovereign debt data for one country. Points are returned oldest to newest.

Response:

• series.primeRate[], series.inflation[], and series.gdpGrowth[] contain { turn, value } points from the per-turn monetary history.
• fiscalYears[] contains annual snapshots with fiscalYear, turn, recordedAt, currencyCode, gdp, revenue, spending, surplus, debtPrincipal, debtToGdpRatio, creditRating, and inflation.
• range echoes the effective filters. found is false when the country is valid but its current world has not accumulated history yet.

Internal policy drivers, actor ids, tax bases, and enacted-law implementation details are not exposed.

GET /api/public/v1/country/[code]/regions#

All regions for a country in one request, ordered by name.

Response: countryId, countryName, count, and regions[] with id, name, regionType, parentRegionId, region, population, votingEligiblePopulation, workingAgePopulation, gdpMillions, gdpPerCapita, houseDistricts, stateSenateSeats, votingSystem, economicLean, socialLean, sectorSpecializations, topSectors, and metricsUpdatedAt.

GET /api/public/v1/country/[code]/metrics?category=CATEGORY#

National quality-of-life and economic metrics with regional context. category is optional and accepts economic, education, healthcare, infrastructure, publicSafety, environment, social, governance, population, or mediaInformation.

Policy tick rates, demographic drivers, and modifier ledgers are not exposed.

GET /api/public/v1/country/[code]/budget#

Current national fiscal position. Money fields are in currencyCode units. Sensitive defence accounts and player data are not included.

GET /api/public/v1/forex#

Current currency-market snapshot without history. Returns currencies[] with countryId, currencyCode, rate, baseRate, macroTarget, percentage changes, 24-turn buy/sell/net volume, declared regime, intervention band, cycle pressure, spread strength, and updatedAt.

Rates are local currency units per one internal anchor unit.

GET /api/public/v1/forex/[currency]?history=N#

One active currency plus trailing rate history. history defaults to 48 and must be from 1 to 240. Response shape: { ok, found, currency }; the currency object has the collection fields above plus history: [{ turn, rate }].

GET /api/public/v1/trade/tariffs?country=CODE[&targetCountry=CODE][&scope=SCOPE][&limit=N]#

Active tariff layers. country filters the country imposing the tariff; targetCountry filters origin-country targets. scope accepts economy_wide, sector, origin_country, or corporation. limit defaults to 100 and must be from 1 to 200.

Response rows include id, countryId, scopeType, targetSectorType, targetOriginCountryId, resolved targetCorporation: { id, name }, rate, sourceBillId, createdAt, and updatedAt.

GET /api/public/v1/trade/embargoes?country=CODE[&includePending=true]#

Active ministerial, legislative, and organization trade restrictions. country matches either the imposing or target country. The response includes currentTurn and embargoes[] with source and target countries, commodity, direction, mode, cap, origin, lifecycle turns, and public bill or organization resolution provenance.

Pass includePending=true to add embargo and end-embargo bills still moving through a legislature under pending[]. Internal acting-character IDs are not returned.

GET /api/public/v1/trade/flows?country=CODE[&commodity=KEY][&fromTurn=N][&toTurn=N][&limit=N]#

Historical inter-country commodity trade, returned oldest to newest. limit defaults to 48 and accepts 1-240. fromTurn and toTurn are inclusive.

Every point contains turn, recordedAt, and world grossVolume, clearedVolume, and unclearedSurplus. Passing country adds that country's exports, imports, net balance, and largest surplus and deficit partners. Passing commodity adds its label and world volume. Passing both adds the country's exports, imports, net, and uncleared amount for that commodity.

All monetary values use the game's anchor unit, reported as monetaryUnit: "anchor". Full bilateral matrices and internal reachable market books are not exposed.

GET /api/public/v1/sovereigns#

World-wide sovereign-debt monitoring. Each countries[] row includes countryId, countryName, crisisState, creditRating, consecutive failed auctions, turns since default, debt-to-GDP, inflation, GDP growth, trust, coupon rate, 10-turn FX depreciation, entity holdings, and required issuance.

demand contains the subscription ratio, subscribed, undersubscribed, or failed band, and the public contribution breakdown. sustainability contains the 0-100 Debt Sustainability Assessment score, band, and components.

GET /api/public/v1/government?country=CODE#

Government overview. Requires country query param.

GET /api/public/v1/elections?country=CODE[&state=STATE]#

Active elections. Requires country; optional state.

GET /api/public/v1/elections/[id]#

Detailed election info including candidates, votes, and phases.

GET /api/public/v1/news?limit=N[&category=CAT]#

News feed. Optional limit and category.

GET /api/public/v1/legislation?country=CODE[&status=pending|passed|failed][&limit=N]#

Bills and votes. Optional filters.

GET /api/public/v1/market?type=SECTOR&country=CODE&page=N#

Stock market data. type param required. Pass view=share for shares, view=unowned for unowned sectors.

GET /api/public/v1/bonds?corp=NAME&page=N#

Bond market data. Optional corp and page.

GET /api/public/v1/corporations#

List all corporations. Returns corporations[] of { id, name, sequentialId, type, countryId }.

GET /api/public/v1/corporation?name=X[&id=N]#

Corporation details. Requires name or id. Note: id is the corporation's sequentialId (e.g. 112), not the Mongo ObjectId.

GET /api/public/v1/leaderboard?country=CODE[&metric=METRIC][&limit=N]#

Player rankings. Metrics: npi, pi, favorability, funds, actions.

GET /api/public/v1/country/[code]/history?limit=N[&type=TYPE][&beforeTurn=N]#

Append-only country event log (leader changes, bill enactments, referendums, regime changes, international relations). Written by the turn processor.

Response rows: events[].turn, eventType, title, officeType, characterId / characterName / party, billScope, details, iterationStartingYear, timestamp.

GET /api/public/v1/country/[code]/battles?limit=N#

Recent battle reports involving the country (as declarer or target), newest turn first.

Response rows: battles[].theaterId, declarerCountry, targetCountry, attackers, defenders, turn, result (null = no contact), noContact, unopposedAdvance, controlBefore / controlAfter (front-line movement, null when unknown).

GET /api/public/v1/conflicts?country=CODE[&status=STATUS][&limit=N]#

Conflicts, newest first. Filter by involved country (host or belligerent) and/or status (active, escalating, winding_down, resolved).

Response rows: conflicts[].conflictId (public sequential number), name, hostCountry, region, type, status, bloc, terrain, severity, intensity, control (share of host held by side B, 0-100), supplyA / supplyB, and both sides as { label, countries, kind, backer }.

GET /api/public/v1/parties?country=CODE#

All parties for a country, ordered by member count. Seat counts come from the elected-officials roster so they reconcile with the legislature endpoints.

Response rows: parties[].id (sequential id usable with /party?id=), name, abbreviation, color, economicPosition, socialPosition, memberCount, seatCount, treasury, isDefault.

GET /api/public/v1/elections/archives?country=CODE[&limit=N][&type=TYPE]#

Completed/resolved elections for a country, newest first.

Response rows: elections[].id, seatId, electionType, state, cycle, electionYear, totalSeats, startTime / endTime, status, totalVotes, finalized, candidateCount, and winner: { characterName, party, votes } when a final tally exists.

GET /api/public/v1/referendums?country=CODE[&status=STATUS][&limit=N]#

Referendum campaigns and history, newest update first. country and status are optional; limit defaults to 50 and must be from 1 to 200.

Response rows: referendums[].id, countryId, region: { id, name }, kind, targetCountryId, status, lifecycle turns under timing, current and baseline Yes shares, pollHistory, resolved public party positions, and result with Yes/No shares, turnout, pass/fail, and resolution turn. Internal cohort models and campaign-spend ledgers are not exposed.

GET /api/public/v1/referendums/[id]#

One referendum by ObjectId with the same shape as a collection row, wrapped as { ok, found, referendum }.

GET /api/public/v1/organizations#

International organization summaries. Returns count and organizations[] with identity, category, founding and dissolution years, leadership office and holder, full member roster, voting-member count, and activity counts for membership proposals, resolutions, leadership elections, and withdrawals.

GET /api/public/v1/organizations/[id]#

One built-in or custom organization, matched case-insensitively. Adds charter, pending membership proposals, pending and active resolutions, leadership elections, and pending withdrawals.

Vote objects contain aggregate yes, no, and abstain totals plus each country's public position and cast turn. Proposer and voter character IDs are not exposed.

GET /api/public/v1/commodities?country=CODE#

All commodity markets. Each row includes key, label, unit, basePrice, global price/supply/demand, and turn. Passing country adds national price/supply/demand.

GET /api/public/v1/commodity/[key]?country=CODE#

One commodity with state price/supply/demand maps plus its top ten producers and consumers. Passing country limits state data to that country.

GET /api/public/v1/funds[?slug=SLUG][&country=CODE][&scope=country|global]#

Index funds. Without slug: list all funds sorted by NAV. With slug: full detail including top holdings enriched with corporation names.

List rows: funds[].slug, name, tickerSymbol, scope, kind, countryId, sectorType, status, pauseReason, quotedNav, unitSupply, anchorCurrencyCode, backingRatio, sponsorName, expenseRatioAnnual, updatedAt.

Detail adds: reserveUnits, cashAnchor, lastRebalancedAt, charteredAtTurn, seedCapitalAnchor, windDownStartedAtTurn, topHoldings[] of { corporationId, corporationName, shares, lastValueAnchor, avgCostPerShareAnchor }.

GET /api/public/v1/corporation/shares/history?name=X[&id=N][&page=N][&pageSize=N]#

Public share-trade tape for one corporation (same data the in-game corp page shows). Requires name or id (sequential id).

Response: corporation: { id, name }, page, pageSize, total, pageCount, and entries[] of { kind, turn, createdAt, shares, pricePerShareAnchor, totalAnchor, corpCurrencyCode, from: { name }, to: { name }, note }. from/to are null when the public float is that side.

GET /api/public/v1/characters/bulk?ids=1,7,42#

Bulk character lookup for dashboards: up to 100 comma-separated sequential ids in one request. Unknown and invalid ids are skipped (match on what came back).

Response: ok, found, requested / returned counts, and characters[] with the same shape as the search endpoint.

GET /api/public/v1/meta#

Machine-readable catalog of every v1 endpoint with its params, plus base URL, auth header, rate limits, OpenAPI URL, and the stability contract. Bots can validate their integration against this instead of scraping docs.

GET /api/public/v1/openapi.json#

OpenAPI 3.1 contract generated from the same route catalog as /meta. It describes every public v1 path, query and path parameters, both supported auth headers, standard error responses, and rate-limit headers. Use it to generate a client or import the interface into API tooling.

curl -H "X-API-Key: $AHD_API_KEY" \
  https://ahousedividedgame.com/api/public/v1/openapi.json

Private endpoints (send funds and forex)#

Require a private personal API key. All in-game restrictions apply identically to API requests.

POST /api/v1/transfer#

Send campaign funds to another character.

Request body:

{ "targetCharacterId": "<recipient ObjectId>", "amount": 5000 }

amount is in your character's home currency (same unit as your in-game balance, min 1000, integer).

Response: success, amount, currency (sender home currency code), senderRemainingFunds, targetName.

Restrictions:

• Minimum transfer: 1,000 (home currency)
• Sender and target must be in the same country
• Cannot transfer to yourself
• Must have sufficient campaign funds
• Transfers may be paused by admins (returns 403)

POST /api/v1/forex/exchange#

Execute a forex market order.

Request body:

{ "fromCurrency": "USD", "toCurrency": "GBP", "amount": 1000 }

Response: success, trade.fromCurrency, trade.toCurrency, trade.fromAmount, trade.toAmount, trade.effectiveRate, trade.spreadCharged (0.275% spread; 50% destroyed, 50% to central bank).

Restrictions:

• Cannot trade a currency for itself
• Forex must be enabled on the server
• Must have sufficient funds in source currency
• Character must exist and be in an active country

Quick start#

# Read public data (any key)
curl -H "X-API-Key: $AHD_API_KEY" \
  https://ahousedividedgame.com/api/public/v1/game

# Send funds (private key)
curl -X POST -H "X-API-Key: $AHD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetCharacterId":"507f1f77bcf86cd799439011","amount":5000}' \
  https://ahousedividedgame.com/api/v1/transfer

Python:

import os, requests

BASE = "https://ahousedividedgame.com"
headers = {"X-API-Key": os.environ["AHD_API_KEY"]}

game = requests.get(f"{BASE}/api/public/v1/game", headers=headers).json()
print(f"Turn {game['currentTurn']}")