# API-documentatie

> API-documentatie van Citeerbaar: de openbare JSON-API, de MCP-server en de A2A-agent. Zonder sleutel, met voorbeelden, foutmodel, limieten en uitfaseerbeleid.

Bron: https://www.citeerbaar.nl/docs/

Hoe je de openbare JSON-API, de MCP-server en de A2A-agent van Citeerbaar gebruikt. Zonder account of sleutel.

## Zonder sleutel

Je hebt geen account, sleutel of token nodig. Alle endpoints zijn openbaar en lezen alleen. De enige uitzondering is de Quick Check: de MCP-tool `request_quick_check` en de A2A-vaardigheid `request-quick-check` sturen een aanvraag namens een gebruiker, alleen met diens gegevens en akkoord.

## Snel beginnen

- Alle endpoints op een rij: een GET op [`/api/`](https://www.citeerbaar.nl/api/).
- Werkt de API? Een GET op [`/api/health.json`](https://www.citeerbaar.nl/api/health.json).
- Pakketten en prijzen: een GET op [`/api/pricing.json`](https://www.citeerbaar.nl/api/pricing.json).
- Een pagina als Markdown: vraag het gewone adres op met de header `Accept: text/markdown`, bijvoorbeeld [`/werkwijze/`](https://www.citeerbaar.nl/werkwijze/).
- MCP: een POST op [`/mcp`](https://www.citeerbaar.nl/mcp) met de header `Content-Type: application/json` en als body `{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}` geeft alle tools.
- A2A: lees eerst de agent card op [`/.well-known/agent-card.json`](https://www.citeerbaar.nl/.well-known/agent-card.json). Gesprekken gaan via JSON-RPC op [`/a2a`](https://www.citeerbaar.nl/a2a).

## Endpoints

| Endpoint | Wat het geeft |
| --- | --- |
| GET [`/api/`](https://www.citeerbaar.nl/api/) | API-overzicht. Alle endpoints op een rij, met methode, pad, URL en korte omschrijving, plus links naar deze beschrijving, de API-catalogus en de documentatie op /docs/. |
| GET [`/api/facts.json`](https://www.citeerbaar.nl/api/facts.json) | Feiten-API. De harde feiten over Citeerbaar: diensten, prijzen, doorlooptijden, btw-status en bedrijfsgegevens. |
| GET [`/api/content.json`](https://www.citeerbaar.nl/api/content.json) | Pagina-index. Elke gepubliceerde pagina met titel, samenvatting, type en wijzigingsdatum. |
| GET [`/api/answers.json`](https://www.citeerbaar.nl/api/answers.json) | Vragen en antwoorden. Vragen die zichtbaar op de site staan, met het antwoord, de bron-URL en de wijzigingsdatum van die pagina. |
| GET [`/api/pricing.json`](https://www.citeerbaar.nl/api/pricing.json) | Prijzen. Alle pakketten met prijs, doorlooptijd en inhoud, plus verrekenregel en betaalvoorwaarden. |
| GET [`/api/claims.json`](https://www.citeerbaar.nl/api/claims.json) | Beweringen met bron. Een getoetst register: alleen cijfers waarvan de primaire bron is gecontroleerd en die zichtbaar met bronvermelding op een pagina staan. |
| GET [`/api/glossary.json`](https://www.citeerbaar.nl/api/glossary.json) | Begrippenlijst. De begrippen rond AI-vindbaarheid en GEO met hun definitie, waar mogelijk gekoppeld aan Wikipedia en Wikidata. |
| GET [`/api/entities.json`](https://www.citeerbaar.nl/api/entities.json) | Entiteitenkaart. De entiteiten waar de site over spreekt en hoe ze zich tot elkaar verhouden. |
| GET [`/api/changes.json`](https://www.citeerbaar.nl/api/changes.json) | Wijzigingen. Alles wat is gepubliceerd of bijgewerkt, nieuwste eerst, zodat een crawler in één verzoek ziet wat er veranderde. |
| GET [`/feed.json`](https://www.citeerbaar.nl/feed.json) | Artikelfeed. De blogartikelen als JSON Feed, met volledige tekst. |
| GET [`/api/health.json`](https://www.citeerbaar.nl/api/health.json) | Statuscontrole. Geeft ok, de versie van de agent-laag en de servertijd. |
| GET [`/api/openapi.json`](https://www.citeerbaar.nl/api/openapi.json) | Deze beschrijving. Dit document. |
| POST [`/mcp`](https://www.citeerbaar.nl/mcp) | MCP-endpoint. Model Context Protocol over HTTP, één JSON-RPC-bericht per verzoek. |
| POST [`/a2a`](https://www.citeerbaar.nl/a2a) | A2A-endpoint. Agent-to-Agent JSON-RPC. |

De volledige beschrijving, met het schema van elk antwoord, staat in [`/api/openapi.json`](https://www.citeerbaar.nl/api/openapi.json) (OpenAPI 3.1.0). De API-catalogus op [`/.well-known/api-catalog`](https://www.citeerbaar.nl/.well-known/api-catalog) (RFC 9727) verwijst naar alle ingangen.

## Antwoorden en caching

De GET-endpoints antwoorden in JSON (UTF-8) en mogen vanaf elk domein gelezen worden (CORS). Ze sturen een ETag mee: stuur die terug in `If-None-Match`, dan krijg je een 304 zolang er niets veranderd is. Antwoorden mogen vijf minuten in een cache blijven.

## Fouten

Een fout op een GET-endpoint komt als `application/problem+json` (RFC 9457), met de velden `type`, `title`, `status`, `detail`, `instance`, `code`, `hint` en `docs`. Het veld `code` is bedoeld voor software, `detail` en `hint` voor mensen. Een adres onder `/api/` dat niet bestaat, geeft 404 met de code `endpoint_not_found`.

MCP en A2A geven fouten als JSON-RPC-foutobject, zoals die protocollen voorschrijven.

## Limieten

[`/mcp`](https://www.citeerbaar.nl/mcp) en [`/a2a`](https://www.citeerbaar.nl/a2a) sturen bij elk antwoord de headers `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` en `RateLimit-Policy` mee. Wie daarboven komt, krijgt HTTP 429 met een `Retry-After`-header. Voor de Quick Check gelden lagere limieten; die staan in de beschrijving van de tool `request_quick_check`.

## Versies en uitfasering

Versies en uitfasering: de versie van de agent-laag staat in info.version, in /api/health.json en in serverInfo van de MCP-server. Een brekende wijziging, of het schrappen van een endpoint, veld of tool, kondigen we minimaal 90 dagen vooraf aan: in /api/changes.json onder tool_changes en met de headers Deprecation (RFC 9745) en Sunset (RFC 8594) op de betrokken antwoorden. Uitbreidingen, zoals nieuwe velden of endpoints, zijn niet brekend en komen zonder aankondiging.

Wat er veranderd is, staat in [`/api/changes.json`](https://www.citeerbaar.nl/api/changes.json).

## Meer

- [`/voor-ai/`](https://www.citeerbaar.nl/voor-ai/): alle feiten over Citeerbaar, met de tools van de MCP-server en de vaardigheden van de A2A-agent.
- [`/.well-known/agent-skills/index.json`](https://www.citeerbaar.nl/.well-known/agent-skills/index.json): uitleg voor agents over welke ingang bij welke vraag hoort.
- [`/llms.txt`](https://www.citeerbaar.nl/llms.txt): korte gids voor AI-tools.