> ## 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.

# List test elections

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



## OpenAPI

````yaml /openapi.json get /elections
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
servers:
  - url: https://www.worldrepublic.org/api/v1
security: []
externalDocs:
  url: https://docs.worldrepublic.org
paths:
  /elections:
    get:
      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.
      operationId: listElections
      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'
components:
  schemas:
    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
    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
    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

````

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