# Usage

Our API adheres to the [GraphQL](https://graphql.org) standard, which you can query at `https://politigraph.wevis.info/graphql` through a [GraphQL Client or HTTP Request](https://www.graphql-js.org/docs/graphql-clients/)

We also provide

- [GraphQL Playground](https://politigraph.wevis.info/graphql) to try building various queries and explore the results
- [Explore](https://politigraph.wevis.info/en/explore) the data through interactive visualization

## Using with AI Agents

We provide two interfaces for AI coding agent or chatbot.

> **Caution: AI responses can be inaccurate or misleading**
>
> An AI agent may build a query that does not answer your question, misinterpret the schema, or state figures that never came from Politigraph at all.
> Before relying on or publishing an answer, you should verify the result yourself, for example by re-running it in the [GraphQL Playground](https://politigraph.wevis.info/graphql).

### llms.txt

Our documentation are published as machine-readable plain text following the [llms.txt](https://llmstxt.org) convention:

- [`/llms.txt`](https://politigraph.wevis.info/llms.txt): an index of every documentation page and resource, with links
- [`/llms-full.txt`](https://politigraph.wevis.info/llms-full.txt): the entire documentation plus the full GraphQL schema in a single file
- [`/schema.graphql`](https://politigraph.wevis.info/schema.graphql): the complete GraphQL schema (SDL)

Give your agent `https://politigraph.wevis.info/llms.txt` to let it pick what it needs, or `https://politigraph.wevis.info/llms-full.txt` to hand it everything at once.

**Example prompt**

```
Understand Politigraph via https://politigraph.wevis.info/llms.txt, then find which representative was absent from the most vote events in the current representative term. Break down the query you sent and the result you got from Politigraph.
```

### MCP Server

If your agent speaks the [Model Context Protocol](https://modelcontextprotocol.io), connect it to our MCP endpoint at `https://politigraph.wevis.info/mcp` instead. No authentication or API key is required.

**MCP client configuration**

```
{ "type": "http", "url": "https://politigraph.wevis.info/mcp" }
```

### Client Compatibility

An agent on your machine can read our documentation and send the query itself, so it can answer with real data. A chatbot in the browser can only read the documentation and help you write a query, but you have to run it yourself in the [GraphQL Playground](https://politigraph.wevis.info/graphql). Connect the chatbot to our MCP server if you want it to return real data.

#### Web chatbots

| Provider                                                                                                         | llms.txt                 | MCP server                                                                  |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------- |
| [ChatGPT](https://platform.openai.com/docs/guides/developer-mode)                                                | Reads it, drafts queries | Custom connector in developer mode, on paid plans                           |
| [Claude](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)    | Reads it, drafts queries | Custom connector on every plan, web and desktop, one connector when on free |
| [Gemini](https://support.google.com/g/answer/17106276)                                                           | Reads it, drafts queries | Custom app in Spark on AI Pro and Ultra, or through an admin on Business    |
| [Perplexity](https://www.perplexity.ai/help-center/en/articles/13915507-adding-custom-remote-connectors)         | Reads it, drafts queries | Custom remote connector, on paid plans                                      |
| [Microsoft Copilot](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent) | Reads it, drafts queries | Only through an agent you build in Copilot Studio                           |

#### Local coding agents

| Client                                                                                     | llms.txt                      | MCP server                      |
| ------------------------------------------------------------------------------------------ | ----------------------------- | ------------------------------- |
| [Claude Code](https://docs.claude.com/en/docs/claude-code/mcp)                             | Reads it and runs queries     | Yes                             |
| [Codex CLI](https://developers.openai.com/codex/agent-approvals-security)                  | Needs `network_access = true` | Yes                             |
| [Gemini CLI](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html)        | Reads it and runs queries     | Yes, configured under `httpUrl` |
| [Cursor](https://cursor.com/docs/context/mcp)                                              | Reads it and runs queries     | Yes                             |
| [VS Code with GitHub Copilot](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Reads it and runs queries     | Yes                             |

_Last checked on 7 September 2026_

## Limitations

### Access

Most data from the Politigraph API is publicly accessible and does not require authentication, with the following exceptions:

- Data with the field `publish_status` that does not have the value `PUBLISHED` will be hidden from the response because it is under review and not yet ready for disclosure.
- Any GraphQL mutation, as we prevent external parties from modifying data on our system.

Access to both of these exceptions is strictly reserved for the WeVis system administration team.

### API Usage Limits

To ensure fair usage and protect the API from abuse, we enforce the following limits on GraphQL operations, both through GraphQL endpoint and MCP:

- **Rate limit**: 30 requests per 10 seconds
- **Batching**: 5 operations per batched request
- **Aliases**: 120 aliases per operation
- **Depth**: 10 levels of nested operation
- **Tokens**: 10,000 tokens per operation

Exceeding these limits will result in an error response.

### Node Limits

Certain types of data, such as "People" and individual "Votes", contain a large number of nodes within the system.
We must limit the number of nodes returned to the user to no more than 1,000 nodes per query.
If you need to retrieve more data than this limit allows, please [read more about using Pagination on GraphQL](https://neo4j.com/docs/graphql/current/queries-aggregations/pagination/).

## License

Regarding the data, the team intends to open it as Open Data under the [Attribution-NonCommercial 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/) terms. This means you can use, modify, and build upon the data, but it cannot be used for commercial purposes or to seek profit from the work, and credit must be given to WeVis.

Regarding the source code, the team intends to develop every project as Open Source under the [Attribution-NonCommercial-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/) terms. This means you can use, modify, and build upon the work, but it cannot be used for commercial purposes or to seek profit from the work. You must provide notice and credit to the work's owner, and the resulting work must be under the same Creative Commons license conditions as the original. WeVis Ltd. and Punch Up Ltd. are joint licensors.