openapi: 3.0.4
info:
  title: BesluitBron API
  description: 'The machine-readable addresses of BesluitBron, over the public decision-making records of 310 Dutch municipalities, 8 provinces, 13 water authorities, the Tweede Kamer, the official publication register and the published rulings of the judiciary. Both addresses are anonymous and read-only, and both share the rate budget and the two clocks of the screen they mirror.'
  license:
    name: EUPL-1.2
    url: https://eupl.eu/1.2/
  version: '1.4.4'
paths:
  /api/status.json:
    get:
      tags:
        - API
      summary: 'The loading status of every source, as data.'
      description: 'Whether new material is still arriving at each of the seven source platforms, the same measurement as /{culture}/status rendered as JSON. Answers 503 with measured: false before the first sweep has completed. The language of the label fields follows the optional culture query parameter, then the culture cookie, then Accept-Language; every label carries a _code sibling that stays the same whatever language was chosen, for a monitoring rule to key on.'
      operationId: GetStatusJson
      parameters:
        - name: culture
          in: query
          description: 'The language of the label fields, e.g. de. Omitted falls back to the culture cookie and then Accept-Language.'
          schema:
            type: string
            description: 'The language of the label fields, e.g. de. Omitted falls back to the culture cookie and then Accept-Language.'
      responses:
        '200':
          description: OK
  /api/search.json:
    get:
      tags:
        - API
      summary: 'One free-text search over every source, answered whole.'
      description: 'The JSON counterpart of /{culture}/zoeken: the same search over the same six sources (Open Raadsinformatie, OpenBesluitvorming, OpenTK, Officiële Bekendmakingen, Rechtspraak and Open Archivaris), run once and answered when every source has resolved or the shared ceiling is reached, whichever comes first. Shares the one-per-second budget the public search screen uses and answers 429 with a Retry-After header when that budget is taken. ''q'' is required. ''mode'' is one of all, any, near or exact, defaulting to all; ''page_size'' is one of 100, 500, 1000 or max (each source''s own platform maximum, typically 100, 250 for Officiële Bekendmakingen), defaulting to the installation''s own configured default (100 unless the operator changed it); date_from and date_to (yyyy-MM-dd) narrow the already-loaded hits to a period, and date_undated=1 additionally keeps a hit with no readable date while doing so, exactly as the screen''s own date filter does. Every one of ''mode'', ''page_size'', ''date_from'' and ''date_to'' answers 400 with a named error when given a value outside what is listed here, rather than silently falling back to a default: the difference between a caller''s default and a caller''s typo is exactly what a program needs told apart, where a person reading the screen does not.'
      operationId: GetSearchJson
      parameters:
        - name: q
          in: query
          description: 'The search terms, exactly as typed into /zoeken. Required.'
          schema:
            type: string
            description: 'The search terms, exactly as typed into /zoeken. Required.'
        - name: mode
          in: query
          description: 'How the words combine: all (every word, the default), any (at least one), near (every word within ten words of the others) or exact (every word, adjacent, in this order). Any other value answers 400.'
          schema:
            type: string
            description: 'How the words combine: all (every word, the default), any (at least one), near (every word within ten words of the others) or exact (every word, adjacent, in this order). Any other value answers 400.'
        - name: page_size
          in: query
          description: 'Rows requested per source: 100, 500, 1000 or max (each source''s own platform ceiling). Omitted uses the installation''s own configured default, 100 unless the operator changed BesluitBron:Search:PageSize. Any other value answers 400.'
          schema:
            type: string
            description: 'Rows requested per source: 100, 500, 1000 or max (each source''s own platform ceiling). Omitted uses the installation''s own configured default, 100 unless the operator changed BesluitBron:Search:PageSize. Any other value answers 400.'
        - name: date_from
          in: query
          description: 'The lower bound of the date filter, yyyy-MM-dd, or omitted for no lower bound. An unparseable value answers 400.'
          schema:
            type: string
            description: 'The lower bound of the date filter, yyyy-MM-dd, or omitted for no lower bound. An unparseable value answers 400.'
        - name: date_to
          in: query
          description: 'The upper bound of the date filter, yyyy-MM-dd, or omitted for no upper bound. An unparseable value answers 400.'
          schema:
            type: string
            description: 'The upper bound of the date filter, yyyy-MM-dd, or omitted for no upper bound. An unparseable value answers 400.'
        - name: date_undated
          in: query
          description: '1 to also show a hit that carries no readable date at all while date_from or date_to is set; omitted, or any other value, hides such a hit once either bound is active. Has no effect while neither bound is set.'
          schema:
            type: string
            description: '1 to also show a hit that carries no readable date at all while date_from or date_to is set; omitted, or any other value, hides such a hit once either bound is active. Has no effect while neither bound is set.'
        - name: culture
          in: query
          description: 'The language of the outcome, the note and the ''wijze'' per source, e.g. de. Omitted falls back to the culture cookie and then Accept-Language.'
          schema:
            type: string
            description: 'The language of the outcome, the note and the ''wijze'' per source, e.g. de. Omitted falls back to the culture cookie and then Accept-Language.'
      responses:
        '200':
          description: OK
components: { }
tags:
  - name: API