> ## Documentation Index
> Fetch the complete documentation index at: https://docs.worldrepublic.org/llms.txt
> Use this file to discover all available pages before exploring further.

# World Republic API reference

> Read-only JSON access to parties, test elections and their results.

The World Republic API returns the party registry, test elections and their results, and counts of verified citizens and parties, as JSON. It only reads, and any website may call it.

* **Base URL:** `https://www.worldrepublic.org/api/v1`
* **Authentication:** none; there is no key and no sign-in.
* **OpenAPI document:** [openapi.json](https://www.worldrepublic.org/api/v1/openapi.json) describes every endpoint and field, and the endpoint pages are generated from it.

## Endpoints

Every endpoint is a `GET`.

| Endpoint | Returns |
| :- | :- |
| [`/parties`](https://docs.worldrepublic.org/integrations/api-reference/list-or-search-parties) | A page of parties, newest first or ranked by votes or subsidies, or the parties matching a search. |
| [`/parties/{partyId}`](https://docs.worldrepublic.org/integrations/api-reference/get-a-party) | One party's profile, its record in closed test elections, and the subsidies allocated to it. |
| [`/elections`](https://docs.worldrepublic.org/integrations/api-reference/list-test-elections) | Test elections, open first, then upcoming, then closed; or only those with one status. |
| [`/elections/{electionId}`](https://docs.worldrepublic.org/integrations/api-reference/get-a-test-election) | One election, with every party's votes and seats once it has closed. |
| [`/stats`](https://docs.worldrepublic.org/integrations/api-reference/citizen-and-party-counts) | Verified citizens and party counts. |

## Paging, sorting, filters and search

* **Pages hold 100 parties.** Pass the `nextOffset` of one page as the `offset` of the next; it is `null` on the last page.
* **`search` matches names, descriptions and leader usernames.** The first page of a search also carries `total`.
* **`sort` orders the list:** `newest` (the default), `votes` (drawn in closed test elections) or `subsidies` (allocated). A ranked list carries each party's `totalVotes` or `subsidiesAllocated`. A ranking can't be combined with `search`, and its `offset` is at most 20,000.
* **`includeUnlisted=true` adds the parties the default list leaves out:** those still awaiting moderation review and those flagged as spam. Each party's `moderation` field says which.
* **`/elections` takes `status` and `limit`.** `status` is `open`, `upcoming` or `closed`; `limit` keeps the first 1 to 100 in the list's order, so `?status=closed&limit=1` is the latest result. `total` counts every election that matches, before the limit.
* **Search is limited per IP address, per minute.** Over the limit, a search answers `503` with a `Retry-After` header.

## Errors

An error answers with a status code and a body like this:

```json theme={null}
{ "error": { "code": "not_found", "message": "No such party." } }
```

| Status | Code | Meaning |
| :- | :- | :- |
| `400` | `invalid_request` | A malformed id, offset or parameter. The message says which. |
| `404` | `not_found` | No such party or election. |
| `503` | `unavailable` | The data could not be read just now, or search was over its limit. Retry after the `Retry-After` header. |

## Data conventions

* **Timestamps** are ISO 8601, in UTC. **Ids** are UUIDs.
* **Per-party results appear only once an election has closed.** While it is open, the only vote figure is `ballotsCast`, the total number of ballots.
* **Every election is marked `binding: false`.** Test elections are experimental and non-binding, and confer no public office, mandate or authority.
* **A party whose content was withheld** keeps its votes in results, but its `partyId` is `null`.
* **Party names and descriptions are written by party leaders,** not by us.
* **Responses are not cached.** The API reads exactly what the app shows, so a party removed from the app disappears from the API at the same time.
* **Subsidies are WDD allocations,** each released over 365 days. An election not yet distributed shows `null`, never a zero.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.