{"openapi":"3.1.0","info":{"title":"World Republic public API","version":"1.0.0","description":"Read-only access to the World Republic's public data: the party registry, test elections and their results, the party subsidies allocated to each party, and counts of verified citizens and parties. No sign-in. Test elections are experimental and non-binding; they are not public elections. Per-party results are published only after an election closes. Party names and descriptions are written by party leaders. The same reads are available to AI assistants through the MCP server at https://www.worldrepublic.org/api/mcp.","termsOfService":"https://www.worldrepublic.org/en/legal/terms"},"externalDocs":{"url":"https://docs.worldrepublic.org"},"servers":[{"url":"https://www.worldrepublic.org/api/v1"}],"paths":{"/parties":{"get":{"operationId":"listParties","summary":"List or search parties","description":"100 per page, newest first unless sort ranks the whole registry by votes or by subsidies allocated; a ranked list carries each party's figure. Descriptions are shortened in lists. The default list holds parties cleared by moderation; includeUnlisted adds parties still awaiting moderation review and parties flagged as spam.","parameters":[{"name":"search","in":"query","description":"Matches party names, descriptions and leader usernames.","schema":{"type":"string","maxLength":256}},{"name":"offset","in":"query","description":"0, or the nextOffset of the previous page (a multiple of 100).","schema":{"type":"integer","minimum":0}},{"name":"includeUnlisted","in":"query","description":"Also return parties still awaiting moderation review and parties flagged as spam.","schema":{"type":"boolean","default":false}},{"name":"sort","in":"query","description":"newest, votes (drawn in closed test elections) or subsidies (allocated). A ranking cannot be combined with search, and its offset is at most 20000.","schema":{"type":"string","enum":["newest","votes","subsidies"],"default":"newest"}}],"responses":{"200":{"description":"A page of parties.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartyPage"}}}},"400":{"description":"The request was malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data could not be read just now, or search was over its limit. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/parties/{partyId}":{"get":{"operationId":"getParty","summary":"Get a party","parameters":[{"name":"partyId","in":"path","required":true,"description":"The party's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The party's profile and record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartyProfile"}}}},"400":{"description":"The request was malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such party.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data could not be read just now, or search was over its limit. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/elections":{"get":{"operationId":"listElections","summary":"List test elections","description":"Open elections first, then upcoming ones soonest first, then closed ones most recent first. Elections are scheduled months ahead, so the full list is long: status keeps one kind, limit keeps the first few, and total counts every match.","parameters":[{"name":"status","in":"query","description":"open, upcoming or closed. Omit for every election. With closed, the first is the most recent result.","schema":{"type":"string","enum":["open","upcoming","closed"]}},{"name":"limit","in":"query","description":"How many elections to return, counted in the list's order. Omit for all.","schema":{"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Test elections: open, then upcoming (soonest first), then closed (most recent first).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectionList"}}}},"400":{"description":"The request was malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data could not be read just now, or search was over its limit. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/elections/{electionId}":{"get":{"operationId":"getElection","summary":"Get a test election","parameters":[{"name":"electionId","in":"path","required":true,"description":"The election's id.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The election and its results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElectionDetail"}}}},"400":{"description":"The request was malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such election.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The data could not be read just now, or search was over its limit. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/stats":{"get":{"operationId":"getStats","summary":"Citizen and party counts","responses":{"200":{"description":"Verified citizens and parties.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}},"503":{"description":"The data could not be read just now, or search was over its limit. Retry after the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"PartySummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"description":{"description":"Written by the party's leader. At most 200 characters in a list; see descriptionTruncated.","type":["string","null"]},"descriptionTruncated":{"type":"boolean"},"leaderUsername":{"type":"string","description":"The public username of the citizen who leads the party."},"registeredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},"listed":{"type":"boolean","description":"Whether the party appears in the registry's default list. An unlisted party is still reachable at its own address."},"moderation":{"type":"string","enum":["clear","in_review","flagged_as_spam"],"description":"The party's moderation standing. Only cleared parties are in the default list; the others are returned when includeUnlisted is set."},"url":{"type":"string","format":"uri","description":"The party's page in the app."},"totalVotes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Votes the party drew across closed test elections. Set when the list is sorted by votes; null otherwise."},"subsidiesAllocated":{"description":"WDD allocated to the party in party subsidies, across all elections; each allocation is released over 365 days. Set when the list is sorted by subsidies; null otherwise, or where the allocations could not be read.","type":["number","null"]}},"required":["id","name","description","descriptionTruncated","leaderUsername","registeredAt","listed","moderation","url","totalVotes","subsidiesAllocated"],"additionalProperties":false,"description":"A party in the World Republic's registry. Names and descriptions are written by party leaders, not by the World Republic."},"PartyPage":{"type":"object","properties":{"parties":{"type":"array","items":{"$ref":"#/components/schemas/PartySummary"}},"nextOffset":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Pass as offset to read the next page; null on the last page."},"total":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Matches in total, for the first page of a search only; null otherwise."}},"required":["parties","nextOffset","total"],"additionalProperties":false},"PartyProfile":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"description":{"description":"Written by the party's leader.","type":["string","null"]},"leaderUsername":{"type":"string","description":"The public username of the citizen who leads the party."},"registeredAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},"listed":{"type":"boolean","description":"Whether the party appears in the registry's default list. An unlisted party is still reachable at its own address."},"moderation":{"type":"string","enum":["clear","in_review","flagged_as_spam"],"description":"The party's moderation standing. Only cleared parties are in the default list; the others are returned when includeUnlisted is set."},"url":{"type":"string","format":"uri","description":"The party's page in the app."},"websiteUrl":{"type":["string","null"]},"color":{"description":"The leader's chosen color as #rrggbb, or null for the default.","type":["string","null"]},"updatedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},"dissolvedAt":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},{"type":"null"}]},"subsidiesAllocated":{"description":"WDD allocated to the party in party subsidies, across all elections; each allocation is released over 365 days. Null where the allocations could not be read.","type":["number","null"]},"electionRecord":{"type":"array","items":{"type":"object","properties":{"electionId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"votes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"electionTotalVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rank":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"1-based."},"partiesWithVotes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"seats":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Seats won, for an election allocated by seats; else null."},"subsidyAllocated":{"description":"WDD allocated to the party for this election, released over 365 days. Null when nothing was allocated (not yet distributed, or forfeited) or the allocations could not be read; never a zero standing in for either.","type":["number","null"]}},"required":["electionId","votes","electionTotalVotes","rank","partiesWithVotes","seats","subsidyAllocated"],"additionalProperties":false},"description":"The party's results in closed test elections."}},"required":["id","name","description","leaderUsername","registeredAt","listed","moderation","url","websiteUrl","color","updatedAt","dissolvedAt","subsidiesAllocated","electionRecord"],"additionalProperties":false},"ElectionSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"kind":{"type":"string","const":"test_election"},"binding":{"type":"boolean","const":false},"status":{"type":"string","enum":["open","upcoming","closed"]},"startsAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},"endsAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},"ballotMode":{"type":"string","enum":["tally","sealed"],"description":"tally: counted as ballots arrive. sealed: encrypted ballots, counted after the close."},"resultsAvailable":{"type":"boolean"},"ballotsCast":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"While open, the only figure published is this total; per-party results appear only after the close."},"url":{"type":"string","format":"uri"},"topParties":{"type":"array","items":{"type":"object","properties":{"partyId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}],"description":"Null when the party's content has been withheld; its votes still count."},"partyName":{"type":"string"},"withheld":{"type":"boolean"},"votes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"seats":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["partyId","partyName","withheld","votes","seats"],"additionalProperties":false},"description":"The leading parties of a closed election."}},"required":["id","name","kind","binding","status","startsAt","endsAt","ballotMode","resultsAvailable","ballotsCast","url","topParties"],"additionalProperties":false},"ElectionList":{"type":"object","properties":{"elections":{"type":"array","items":{"$ref":"#/components/schemas/ElectionSummary"}},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many elections match the status asked for (all of them without one), before any limit."}},"required":["elections","total"],"additionalProperties":false},"ElectionDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},"name":{"type":"string"},"kind":{"type":"string","const":"test_election"},"binding":{"type":"boolean","const":false},"status":{"type":"string","enum":["open","upcoming","closed"]},"startsAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},"endsAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"ISO 8601 timestamp, UTC."},"ballotMode":{"type":"string","enum":["tally","sealed"],"description":"tally: counted as ballots arrive. sealed: encrypted ballots, counted after the close."},"resultsAvailable":{"type":"boolean"},"ballotsCast":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"While open, the only figure published is this total; per-party results appear only after the close."},"url":{"type":"string","format":"uri"},"note":{"type":"string","const":"The World Republic's own test election: experimental and non-binding, not a public election. It confers no public office, mandate or authority. Its result decides how the platform divides that election's party subsidies."},"eligibleVoters":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Verified citizens who could vote: live while open, frozen at the close."},"results":{"type":"array","items":{"type":"object","properties":{"partyId":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"},{"type":"null"}],"description":"Null when the party's content has been withheld; its votes still count."},"partyName":{"type":"string"},"withheld":{"type":"boolean"},"votes":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"seats":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["partyId","partyName","withheld","votes","seats"],"additionalProperties":false},"description":"Every party's votes. Empty until results are available."}},"required":["id","name","kind","binding","status","startsAt","endsAt","ballotMode","resultsAvailable","ballotsCast","url","note","eligibleVoters","results"],"additionalProperties":false},"Stats":{"type":"object","properties":{"verifiedCitizens":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"parties":{"type":"object","properties":{"listed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Parties in the default list: cleared by moderation."},"includingUnlisted":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Also counting parties still awaiting moderation review and parties flagged as spam."}},"required":["listed","includingUnlisted"],"additionalProperties":false}},"required":["verifiedCitizens","parties"],"additionalProperties":false,"description":"Null where a figure could not be read just now."},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","not_found","unavailable"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}