{
  "openapi": "3.1.0",
  "info": {
    "title": "Voterist public records API",
    "version": "1.0.0",
    "description": "Read-only public candidate and race records. No account, API key, OAuth, MCP connection, or address required. Directory responses are complete, with no pagination. Counts describe Voterist coverage. Unclaimed or unpublished candidates may have public researched previews. Use record.workspace when present, otherwise preview. Match positions[].sourceId to evidence[].id and retain evidence status when citing."
  },
  "servers": [
    {
      "url": "https://www.voterist.com"
    }
  ],
  "security": [],
  "externalDocs": {
    "description": "Public API and AI access guide",
    "url": "https://www.voterist.com/ai"
  },
  "paths": {
    "/api/public/candidates": {
      "get": {
        "operationId": "listCandidates",
        "summary": "List and count public candidate entries; fictional samples excluded",
        "responses": {
          "200": {
            "description": "Public record response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "candidates": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CandidateEntry"
                      }
                    }
                  },
                  "required": [
                    "total",
                    "candidates"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure. Retry after the Retry-After interval; no authentication is required.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/races": {
      "get": {
        "operationId": "listRaces",
        "summary": "List and count public races",
        "responses": {
          "200": {
            "description": "Public record response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "races": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Race"
                      }
                    }
                  },
                  "required": [
                    "total",
                    "races"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure. Retry after the Retry-After interval; no authentication is required.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/candidates/{slug}": {
      "get": {
        "operationId": "getCandidate",
        "summary": "Read a candidate preview and published record, when available",
        "responses": {
          "200": {
            "description": "Public record response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Candidate"
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure. Retry after the Retry-After interval; no authentication is required.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No publicly available record matches this slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exact slug returned by the public directory."
          }
        ]
      }
    },
    "/api/public/races/{slug}": {
      "get": {
        "operationId": "getRace",
        "summary": "Read one race and candidate roster",
        "responses": {
          "200": {
            "description": "Public record response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "race": {
                      "$ref": "#/components/schemas/Race"
                    }
                  },
                  "required": [
                    "race"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure. Retry after the Retry-After interval; no authentication is required.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No publicly available record matches this slug.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exact slug returned by the public directory."
          }
        ]
      }
    },
    "/api/public/candidates/{slug}/source-packet": {
      "get": {
        "operationId": "getSourcePacket",
        "summary": "Read a published candidate source packet",
        "responses": {
          "200": {
            "description": "Public record response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SourcePacket"
                }
              }
            }
          },
          "503": {
            "description": "Temporary service failure. Retry after the Retry-After interval; no authentication is required.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Published packet unavailable; candidate preview may still exist.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Exact slug returned by the public directory."
          },
          {
            "name": "download",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            },
            "description": "Set to 1 to download the JSON as an attachment."
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "code": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "CandidateEntry": {
        "type": "object",
        "properties": {
          "candidateId": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "office": {
            "type": "string"
          },
          "district": {
            "type": "string"
          },
          "party": {
            "type": [
              "string",
              "null"
            ]
          },
          "raceSlug": {
            "type": "string"
          },
          "origin": {
            "type": "string",
            "enum": [
              "official_import",
              "voterist_research",
              "seed"
            ]
          },
          "claimStatus": {
            "type": "string",
            "enum": [
              "unclaimed",
              "pending",
              "verified"
            ]
          },
          "published": {
            "type": "boolean"
          },
          "researchStatus": {
            "type": "string"
          }
        },
        "required": [
          "candidateId",
          "slug",
          "name",
          "raceSlug",
          "origin",
          "published"
        ]
      },
      "Evidence": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "label": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "url"
        ]
      },
      "Position": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "issue": {
            "type": "string"
          },
          "statement": {
            "type": "string"
          },
          "sourceId": {
            "type": "string"
          }
        },
        "required": [
          "issue",
          "statement",
          "sourceId"
        ]
      },
      "Workspace": {
        "type": "object",
        "properties": {
          "candidateName": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "bio": {
            "type": "string"
          },
          "published": {
            "type": "boolean"
          },
          "positions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Position"
            }
          },
          "evidence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "endorsements": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "candidateName",
          "positions",
          "evidence"
        ]
      },
      "Candidate": {
        "type": "object",
        "properties": {
          "metadata": {
            "type": [
              "object",
              "null"
            ]
          },
          "party": {
            "type": [
              "string",
              "null"
            ]
          },
          "preview": {
            "$ref": "#/components/schemas/Workspace"
          },
          "record": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "workspace": {
                    "$ref": "#/components/schemas/Workspace"
                  },
                  "version": {
                    "type": "integer"
                  },
                  "publishedAt": {
                    "type": "string"
                  }
                },
                "required": [
                  "workspace"
                ]
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "preview",
          "record"
        ]
      },
      "Race": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "election": {
            "type": "string"
          },
          "electionDate": {
            "type": [
              "string",
              "null"
            ]
          },
          "candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CandidateEntry"
            }
          }
        },
        "required": [
          "slug",
          "title",
          "candidates"
        ]
      },
      "SourcePacket": {
        "type": "object",
        "properties": {
          "schemaVersion": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          },
          "generatedAt": {
            "type": "string"
          },
          "recordVersion": {
            "type": "integer"
          },
          "candidate": {
            "type": "object"
          },
          "positions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Position"
            }
          },
          "evidence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "endorsements": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": [
          "schemaVersion",
          "candidate",
          "positions",
          "evidence"
        ]
      }
    }
  }
}
