Citeerbaar Agents API

openapi: 3.2.0
info:
  title: Citeerbaar open data en agent-laag Agents API
  version: 1.2.0
  description: 'De machineleesbare laag van citeerbaar.nl: JSON-endpoints met feiten, prijzen, antwoorden, beweringen, begrippen, entiteiten en wijzigingen, plus het MCP- en A2A-endpoint. Alle GET-endpoints zijn openbaar, zonder sleutel, met ETag en CORS. Fouten op de GET-endpoints en op onbekende adressen onder /api/ komen als application/problem+json (RFC 9457) met een vaste code en een hint; het MCP- en A2A-endpoint geven een JSON-RPC-foutobject. Wijzigingen staan in /api/changes.json onder tool_changes. 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.'
  contact:
    name: Citeerbaar
    url: https://www.citeerbaar.nl/contact/
    email: hello@citeerbaar.nl
  license:
    name: CC BY 4.0
    identifier: CC-BY-4.0
servers:
- url: https://www.citeerbaar.nl/
tags:
- name: Agents
  description: JSON-RPC-endpoints voor MCP-clients en A2A-agents.
paths:
  /mcp:
    post:
      summary: MCP-endpoint
      description: 'Model Context Protocol over HTTP, één JSON-RPC-bericht per verzoek. Versies tot en met 2025-11-25: initialize, dan de notificatie notifications/initialized (zonder id, antwoord 202 zonder body), dan tools/list. Versie 2026-07-28: geen handshake; stuur tools/list of tools/call direct met de headers MCP-Protocol-Version: 2026-07-28 en Mcp-Method gelijk aan de methode in de body (bijv. Mcp-Method: tools/list), plus dezelfde versie in params._meta["io.modelcontextprotocol/protocolVersion"]. Bij tools/call, resources/read en prompts/get ook Mcp-Name: de toolnaam (of uri). Ontbreekt of verschilt Mcp-Method of Mcp-Name, dan 400 met code -32020. Optioneel eerst server/discover. Elf tools; alleen request_quick_check schrijft (5 per uur per IP). Protocolversies: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26.'
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  type: string
                  const: '2.0'
                id:
                  oneOf:
                  - type: string
                  - type: integer
                  description: Weglaten bij een notificatie. Een ander type geeft -32600 met id null.
                method:
                  type: string
                  enum:
                  - initialize
                  - notifications/initialized
                  - server/discover
                  - ping
                  - tools/list
                  - tools/call
                  - resources/list
                  - resources/read
                  - prompts/list
                params:
                  type: object
                  additionalProperties: true
            examples:
              initialize:
                summary: 'Stap 1: handshake'
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: initialize
                  params:
                    protocolVersion: '2025-06-18'
                    capabilities: {}
                    clientInfo:
                      name: voorbeeld-client
                      version: '1.0'
              tools_list:
                summary: 'Stap 2: welke tools zijn er'
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/list
              tools_call_search:
                summary: 'Stap 3: zoeken (veilige leesroute, ook om te testen)'
                value:
                  jsonrpc: '2.0'
                  id: 3
                  method: tools/call
                  params:
                    name: search
                    arguments:
                      query: pakketten
              ping:
                summary: Bereikbaarheidscontrole, result is {}
                value:
                  jsonrpc: '2.0'
                  id: 4
                  method: ping
              notifications_initialized:
                summary: 'Na initialize (versies tot en met 2025-11-25): notificatie zonder id, antwoord 202 zonder body'
                value:
                  jsonrpc: '2.0'
                  method: notifications/initialized
              tools_list_2026:
                summary: 'Versie 2026-07-28, zonder handshake. Headers: MCP-Protocol-Version: 2026-07-28 en Mcp-Method: tools/list'
                value:
                  jsonrpc: '2.0'
                  id: list-2026
                  method: tools/list
                  params:
                    _meta:
                      io.modelcontextprotocol/protocolVersion: '2026-07-28'
                      io.modelcontextprotocol/clientCapabilities: {}
              tools_call_2026:
                summary: 'Versie 2026-07-28: tool aanroepen. Headers: MCP-Protocol-Version: 2026-07-28, Mcp-Method: tools/call en Mcp-Name: search'
                value:
                  jsonrpc: '2.0'
                  id: call-2026
                  method: tools/call
                  params:
                    name: search
                    arguments:
                      query: pakketten
                    _meta:
                      io.modelcontextprotocol/protocolVersion: '2026-07-28'
      responses:
        '200':
          description: 'JSON-RPC-antwoord: result bij succes, error bij een fout op protocolniveau (ook bij een onbekende methode). error.message is Engels, error.data.message_nl Nederlands.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '400':
          description: 'Geen geldige JSON (-32700, id null), geldige JSON die geen object is (-32600, id null), een batch of een ongeldige envelop (-32600: jsonrpc niet "2.0", id geen string of geheel getal, method ontbreekt), of een ontbrekend verplicht veld.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '405':
          description: Alleen POST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '429':
          description: 'Limiet: 60 verzoeken per 60 seconden per IP. Retry-After en RateLimit-* zeggen wanneer het weer kan.'
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '202':
          description: Notificatie ontvangen (bericht zonder id, bijv. notifications/initialized). Lege body.
      parameters:
      - name: MCP-Protocol-Version
        in: header
        required: false
        schema:
          type: string
          examples:
          - '2026-07-28'
        description: Vanaf 2025-06-18. Verplicht voor de 2026-07-28-flow zonder handshake.
      - name: Mcp-Method
        in: header
        required: false
        schema:
          type: string
          examples:
          - tools/list
        description: 'Verplicht bij MCP-Protocol-Version 2026-07-28: gelijk aan method in de body.'
      - name: Mcp-Name
        in: header
        required: false
        schema:
          type: string
          examples:
          - search
        description: 'Verplicht bij 2026-07-28 voor tools/call, resources/read en prompts/get: de toolnaam of uri uit de body. Niet nodig bij tools/list.'
      operationId: callMcp
  /a2a:
    post:
      summary: A2A-endpoint
      description: Agent-to-Agent JSON-RPC. De agent-card met skills en voorbeelden staat op /.well-known/agent-card.json.
      tags:
      - Agents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jsonrpc
              - method
              properties:
                jsonrpc:
                  type: string
                  const: '2.0'
                id:
                  oneOf:
                  - type: string
                  - type: integer
                  description: Weglaten bij een notificatie. Een ander type geeft -32600 met id null.
                method:
                  type: string
                  enum:
                  - SendMessage
                  - message/send
                  - GetTask
                  - tasks/get
                  - ListTasks
                  - tasks/list
                  - CancelTask
                  - tasks/cancel
                params:
                  type: object
                  additionalProperties: true
            examples:
              message_send:
                summary: Vraag stellen (SendMessage of message/send), antwoord komt synchroon als Message
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: message/send
                  params:
                    message:
                      role: user
                      messageId: voorbeeld-1
                      parts:
                      - kind: text
                        text: Wat kost de Scan?
              tasks_get:
                summary: Taak opvragen (GetTask of tasks/get); deze agent maakt geen taken aan, dus het antwoord is een fout -32001
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tasks/get
                  params:
                    id: voorbeeld-taak
      responses:
        '200':
          description: 'JSON-RPC-antwoord: result bij succes, error bij een fout op protocolniveau (ook bij een onbekende methode). error.message is Engels, error.data.message_nl Nederlands.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '400':
          description: 'Geen geldige JSON (-32700, id null), geldige JSON die geen object is (-32600, id null), een batch of een ongeldige envelop (-32600: jsonrpc niet "2.0", id geen string of geheel getal, method ontbreekt), of een ontbrekend verplicht veld.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '405':
          description: Alleen POST.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
        '429':
          description: 'Limiet: 60 verzoeken per 60 seconden per IP. Retry-After en RateLimit-* zeggen wanneer het weer kan.'
          headers:
            Retry-After:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
      operationId: callA2a
components:
  schemas:
    JsonRpcResponse:
      type: object
      required:
      - jsonrpc
      - id
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: string
          - type: integer
          - type: 'null'
        result:
          type: object
          additionalProperties: true
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: integer
            message:
              type: string
              description: Engels.
            data:
              type: object
              properties:
                message_nl:
                  type: string
              additionalProperties: true