API Reference

Complete reference for all Citations API endpoints. The API provides access to legal citation networks across Dutch case law (Rechtspraak via Elasticsearch) and European Court of Human Rights case law (HUDOC via PostgreSQL). All endpoints return JSON. POST endpoints accept JSON request bodies, while GET endpoints use query parameters.

API Root

/api

Search Pagination

/api/network and /api/echr use opt-in cursor pagination, max pageSize = 1000

Data Sources

HUDOC (PostgreSQL), Rechtspraak (Elasticsearch)

Search Hard Limit

10,000 matched result nodes max per /api/network or /api/echr query

Authentication & CORS

The API is publicly accessible with no authentication required. All endpoints support CORS with a shared browser-facing CORS policy.

Shared CORS policy

Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Content-Type, x-user-identity, x-vercel-protection-bypass, x-vercel-set-bypass-cookie
Access-Control-Allow-Methods: endpoint-specific method list + OPTIONS

Browser CORS validation depends on method and headers, not JSON body parameters. For normal public API use, Content-Type: application/json is usually sufficient. Do not use credentials: "include" with this API because the allowed origin is *.

Pagination

/api/network and /api/echr use opt-in cursor pagination. If pageSize and cursor are omitted, they return a bounded full graph. If pagination is requested, the cursor is a base64-encoded opaque token returned in the response.

How it works

Field	Description
`pageSize`	Optional. Number of matched result nodes per page (1 to 1000).
`cursor`	Opaque token from a previous response's `nextCursor`.
`nextCursor`	Returned in the response when more pages exist. `null` when no more pages.
`limits`	Shared limits metadata: query result limit 10000, response node limit 5000, response edge limit 30000.
`graph`	Completeness metadata. Use `graph.statisticsSafe` before calling `/api/statistics`.

Cursor tokens encode the current query state; changing query parameters invalidates the cursor. If you fetch all pages client-side, you must still check graph.partialReasons across pages to ensure the graph was not truncated for other reasons.

Example flow

1. Initial request

{ "arguments": { ..., "pageSize": 200 } }

2. Response includes nextCursor

{ "pagination": { "pageSize": 200, "nextCursor": "eyJ..." } }

3. Follow-up request

{ "arguments": { ..., "pageSize": 200, "cursor": "eyJ..." } }

Error Handling

All endpoints return consistent error responses as JSON objects with an error field.

Status codes

Code	Meaning
`200`	Success.
`400`	Validation error (missing required fields, invalid values, bad cursor).
`500`	Internal server error.

Error response shape

{
  "error": "Missing required field: degreesSource",
  "type": "ValidationError",
  "details": "degreesSource must be an integer 0-5"
}

POST /api/network

Query Dutch case law (Rechtspraak) citation networks from Elasticsearch. Returns matching cases as nodes with citation edges, expandable by degrees of separation. All parameters are wrapped inside an arguments object in the request body.

Request parameters (inside `arguments`)

Field	Type	Notes
`engine`	string	Required. `"ES"` (Elasticsearch) or `"OS"` (OpenSearch).
`dataSources`	string[]	Required. Must include `"RS"`.
`docTypes`	string[]	Required. `"DEC"` (Uitspraak) and/or `"OPI"` (Conclusie).
`degreesSource`	int	Required. 0 to 5. Levels to traverse outgoing citations.
`degreesTarget`	int	Required. 0 to 5. Levels to traverse incoming citations.
`keywords`	string[]	Optional. Full-text keyword search terms.
`articles`	string	Optional. Article reference query string.
`selectedLaws`	string[]	Optional. Law items in format `"BWBx123\|456"`.
`selectedLawsIntersect`	boolean	Optional. If true, require all selected laws (AND). Default: false (OR).
`domains`	string[]	Optional. Legal domain identifiers.
`instances`	string[]	Optional. Court instance identifiers.
`eclis`	string	Optional. Comma-separated ECLI identifiers.
`dateStart`	string	Optional. Format `YYYY-MM-DD`. Must not be in the future.
`dateEnd`	string	Optional. Format `YYYY-MM-DD`. Must not be in the future.
`attributesToFetch`	string	Optional. `"ALL"`, `"ID"`, `"NETWORKSTATS"`, `"QUERYHANDLER"`, `"KEYWORDSEARCH"`, `"ARTICLESEARCH"`.
`onlyCaseIds`	boolean	Optional. If true, return only ECLI identifiers without full case data.
`isSubgraph`	boolean	Optional. If true, only return edges between result nodes.
`pageSize`	int	Optional. 1 to 1000 when cursor pagination is requested.
`cursor`	string	Optional. Cursor token from a previous response.

Response node fields (`nodes[].data`)

Field	Description
`isResult`	`"True"` for direct search results, `"False"` for expanded citation nodes.
`ecli`	ECLI identifier.
`date_decision`	Decision date (ISO).
`document_type`	`DEC` or `OPI`.
`domains`	Array of legal domain strings.
`instance`	Court instance.
`source`	Data source identifier.
`summary`	Case summary text.
`cites`	Array of cited ECLI identifiers.
`cited_by`	Array of ECLI identifiers citing this case.
`url_publication`	Link to the original publication.

Examples

Keyword search

{
  "arguments": {
    "engine": "ES",
    "keywords": ["privacy"],
    "dataSources": ["RS"],
    "docTypes": ["DEC"],
    "degreesSource": 1,
    "degreesTarget": 1
  }
}

Law item filter

{
  "arguments": {
    "engine": "ES",
    "selectedLaws": ["BWBR0005537|3:44"],
    "dataSources": ["RS"],
    "docTypes": ["DEC", "OPI"],
    "degreesSource": 0,
    "degreesTarget": 0,
    "pageSize": 50
  }
}

Response

{
  "nodes": [
    {
      "id": "ECLI:NL:HR:2018:1234",
      "data": {
        "isResult": "True",
        "ecli": "ECLI:NL:HR:2018:1234",
        "date_decision": "2018-06-15",
        "document_type": "DEC",
        "domains": ["Civiel recht"],
        "instance": "Hoge Raad",
        "cites": ["ECLI:NL:HR:2016:..."],
        "cited_by": ["ECLI:NL:RBAMS:2019:..."],
        "url_publication": "https://..."
      }
    }
  ],
  "edges": [
    {
      "source": "ECLI:NL:HR:2018:1234",
      "target": "ECLI:NL:HR:2016:...",
      "data": {}
    }
  ],
  "message": "",
  "limits": {
    "queryResultLimit": 10000,
    "responseNodeLimit": 5000,
    "responseEdgeLimit": 30000,
    "pageSizeDefault": 1000,
    "pageSizeMax": 1000
  },
  "graph": {
    "paginationRequested": false,
    "graphComplete": true,
    "statisticsSafe": true,
    "partialReasons": []
  }
}

POST /api/echr

Query HUDOC (European Court of Human Rights) cases from PostgreSQL. Supports keyword search, article filters, respondent state, and citation network expansion. Requires at least one search criterion (keyword, ECLI, application number, or article).

Request parameters (inside `arguments`)

Field	Type	Notes
`degreesSource`	int	Required. 0 to 5.
`degreesTarget`	int	Required. 0 to 5.
`keywords`	string[]	Searches issue, docname/headnote, and full text.
`ecli`	string[]	Exact ECLI identifiers.
`application_number`	string[]	HUDOC application numbers.
`respondent_state`	string[]	ISO-3 country codes (e.g., `"GRC"`, `"RUS"`).
`document_type`	string[]	`HEJUD`, `HEDEC`, `HECOM`, `HEINF`, `HECJUD`, `HECDEC`, `HECCOM`, `HECINF`.
`language`	string[]	ISO-3 language codes (e.g., `"ENG"`, `"FRE"`).
`importance`	int	1 to 4 (lower = more important).
`date_judgment_start`	string	`YYYY-MM-DD`. Must not be in the future.
`date_judgment_end`	string	`YYYY-MM-DD`. Must not be in the future.
`date_decision_start`	string	`YYYY-MM-DD`. Must not be in the future.
`date_decision_end`	string	`YYYY-MM-DD`. Must not be in the future.
`article_violated`	string[]	Violated ECHR article numbers.
`article_applied`	string[]	Applied ECHR article numbers.
`article_non_violated`	string[]	Non-violated article numbers.
`article_violated_mode`	string	`"AND"` or `"OR"` (default: `"OR"`). Combine violated articles.
`article_applied_mode`	string	`"AND"` or `"OR"` (default: `"OR"`).
`article_non_violated_mode`	string	`"AND"` or `"OR"` (default: `"OR"`).
`articles_mode`	string	`"AND"` or `"OR"` (default: `"OR"`). Combine across article types.
`attributesToFetch`	string	`"MINIMAL"`, `"ALL"`, `"NETWORKSTATS"`, `"QUERYHANDLER"`.
`onlyCaseIds`	boolean	Return IDs only (no case data).
`isSubgraph`	boolean	Restrict edges to result nodes.
`pageSize`	int	Optional. 1 to 1000 when cursor pagination is requested.
`cursor`	string	Cursor token from previous response.

Response node fields (`nodes[].data`)

Field	Description
`isResult`	`"True"` for search results, `"False"` for expanded nodes.
`dataset`	Always `"ECHR"`.
`ecli`	ECLI identifier.
`itemid`	HUDOC item ID.
`application_number`	Application number.
`date_judgment`	Judgment date.
`date_decision`	Decision date.
`respondent_state`	Respondent country.
`document_type`	HUDOC document type.
`language`	Primary language code.
`languages`	Map of available language versions (`{"ENG": "itemid", ...}`).
`importance`	Case importance level (1-4).
`article_violated`	Violated articles.
`article_applied`	Applied articles.
`keywords`	HUDOC keywords.
`title`	Case title.
`conclusion`	Case conclusion text.
`cites` / `cited_by`	Citation references.

Duplicate ECLIs across languages are deduplicated (English preferred). A languages map is built before dedup so all available versions are preserved.

Examples

Keywords only

{
  "arguments": {
    "keywords": ["Armenia"],
    "degreesSource": 1,
    "degreesTarget": 1,
    "attributesToFetch": "MINIMAL"
  }
}

Article filter with respondent state

{
  "arguments": {
    "article_violated": ["6", "8"],
    "article_violated_mode": "OR",
    "respondent_state": ["GRC"],
    "degreesSource": 1,
    "degreesTarget": 1,
    "pageSize": 100
  }
}

Response

{
  "nodes": [
    {
      "id": "ECLI:CE:ECHR:2019:...",
      "data": {
        "isResult": "True",
        "dataset": "ECHR",
        "ecli": "ECLI:CE:ECHR:2019:...",
        "date_judgment": "2019-03-14",
        "respondent_state": "GRC",
        "document_type": "HEJUD",
        "article_violated": "6",
        "importance": 2,
        "languages": { "ENG": "001-...", "FRE": "001-..." },
        "cites": ["ECLI:CE:ECHR:2015:..."],
        "cited_by": []
      }
    }
  ],
  "edges": [...],
  "message": "",
  "limits": {
    "queryResultLimit": 10000,
    "responseNodeLimit": 5000,
    "responseEdgeLimit": 30000,
    "pageSizeDefault": 1000,
    "pageSizeMax": 1000
  },
  "graph": {
    "paginationRequested": false,
    "graphComplete": true,
    "statisticsSafe": true,
    "partialReasons": []
  }
}

POST /api/combined

Federated search across both Rechtspraak and ECHR with a structured query builder. Supports nested boolean logic, per-rule dataset scoping, sorting, and cursor pagination. This endpoint returns search results only (no citation edges). Use /api/combined/expand to expand citations for individual nodes.

Request parameters

Field	Type	Notes
`queryBuilder`	object	Required. Contains `op`, `rules`, and optional `groups`.
`queryBuilder.op`	string	Required. `"AND"`, `"OR"`, or `"NOT"`.
`queryBuilder.rules`	array	Required. Array of rule objects (see below).
`queryBuilder.groups`	array	Optional. Nested groups (one level). Each has `op` and `rules`.
`sort.by`	string	Optional. `"date"` (default) or `"citations"`.
`sort.direction`	string	Optional. `"ASC"` or `"DESC"` (default).
`pagination.pageSize`	int	Optional. 1 to 1000 (default: 20).
`pagination.cursor`	string	Optional. Cursor token from a previous response.

Rule object

Field	Type	Notes
`field`	string	The field to query (see field reference below).
`operator`	string	`"equals"`, `"contains"`, `"not_contains"`, `"not_equals"`, `"after"`, `"before"`, `"lte"`.
`value`	string	The value to match against.
`sourceScope`	string	`"ANY"` (both datasets), `"RS"`, or `"ECHR"`. Only common fields can use `"ANY"`.

Query builder fields

Field	Scope	Operators
`text`	ANY	contains, not_contains
`title`	ANY	contains, equals, not_contains
`ecli`	ANY	equals, contains, not_contains
`keywords`	ANY	contains, not_contains
`year`	ANY	equals, after, before
`dateStart`	ANY	equals, after
`dateEnd`	ANY	equals, before
`source`	ANY	equals, not_equals, contains
`document_type`	ANY	equals
`instance`	RS	equals
`domain`	RS	equals
`articles`	RS	contains, equals, not_contains
`selectedLaws`	RS	equals, contains
`respondent_state`	ECHR	equals, not_equals
`importance`	ECHR	equals, lte
`article_violated`	ECHR	equals, contains, not_contains
`article_applied`	ECHR	equals, contains, not_contains
`application_number`	ECHR	equals, contains
`language`	ECHR	equals, not_equals

Validation rules

- sourceScope "ANY" only for fields in both datasets
- Root op AND excludes datasets missing scoped rules
- year: 4-digit, must not be in the future
- Dates: YYYY-MM-DD, must not be in the future
- respondent_state: ISO-3 (ARM, DEU, TUR)
- language: ISO-3 (ENG, FRE, DEU)
- document_type RS: DEC, OPI
- document_type ECHR: JUD, DEC, COM, CLIN, PR
- selectedLaws: "BWBx123|456" format
- Cursor must match current sort settings

Note: This endpoint does not return citation edges. Use /api/combined/expand to expand citations for individual nodes.

Examples

Unified query with nested group

{
  "queryBuilder": {
    "op": "AND",
    "rules": [
      {
        "field": "year",
        "operator": "equals",
        "value": "2020",
        "sourceScope": "ANY"
      },
      {
        "field": "respondent_state",
        "operator": "equals",
        "value": "ARM",
        "sourceScope": "ECHR"
      },
      {
        "field": "document_type",
        "operator": "equals",
        "value": "DEC",
        "sourceScope": "RS"
      }
    ],
    "groups": [
      {
        "op": "OR",
        "rules": [
          {
            "field": "keywords",
            "operator": "contains",
            "value": "right to life",
            "sourceScope": "ANY"
          },
          {
            "field": "domain",
            "operator": "equals",
            "value": "Human rights",
            "sourceScope": "RS"
          }
        ]
      }
    ]
  },
  "sort": { "by": "date", "direction": "desc" },
  "pagination": { "pageSize": 20 }
}

Response

{
  "nodes": [
    {
      "id": "ECLI:NL:HR:2020:...",
      "data": {
        "isResult": "True",
        "dataset": "RS",
        "cites_count": 5,
        "cited_by_count": 12,
        "languages": ["NLD"],
        "document_type": "DEC"
      }
    },
    {
      "id": "ECLI:CE:ECHR:2020:...",
      "data": {
        "isResult": "True",
        "dataset": "ECHR",
        "cites_count": 3,
        "cited_by_count": 8,
        "languages": ["ENG", "FRE"],
        "document_type": "JUD"
      }
    }
  ],
  "pagination": {
    "pageSize": 20,
    "nextCursor": "eyJ...",
    "total": 1234,
    "rsTotal": 800,
    "echrTotal": 434
  },
  "facets": {
    "rs_document_type": [{"value": "DEC", "count": 750}],
    "rs_domain": [{"value": "Strafrecht", "count": 200}],
    "rs_instance": [{"value": "Hoge Raad", "count": 100}],
    "echr_document_type": [{"value": "JUD", "count": 300}],
    "echr_respondent_state": [{"value": "TUR", "count": 50}],
    "echr_importance": [{"value": 1, "count": 40}],
    "echr_language": [{"value": "ENG", "count": 400}],
    "echr_article_violated": [{"value": "6", "count": 500}, {"value": "6-1", "count": 480}],
    "echr_article_applied": [{"value": "41", "count": 1200}, {"value": "35-1", "count": 900}],
    "echr_article_non_violated": [{"value": "6", "count": 50}]
  },
  "warnings": []
}

Response notes

- nodes[].data.cites_count / cited_by_count — citation counts per node
- pagination.total — combined total hits across both datasets
- pagination.rsTotal / echrTotal — per-dataset totals
- facets — only returned on the first page (no cursor). Contains filter
  value counts grouped by rs_* and echr_* prefixes.
- sort.by = "citations" sorts by cited_by_count (most cited first)

Typical integration flow

1. Search — POST /api/combined
   → returns nodes + totals + facets (first page only)

2. User selects a node to explore

3. Expand — POST /api/combined/expand
   → returns edges + neighbour nodes

POST /api/combined/expand

Expand a single node's degree-1 citations. Given an ECLI identifier, returns the immediate citation edges (incoming and/or outgoing) and the hydrated neighbour nodes. The dataset (ECHR or RS) is auto-detected from the ECLI format, or can be specified explicitly via nodeDataset.

Request parameters

Field	Type	Notes
`nodeId`	string	Required. The ECLI identifier of the node to expand.
`degreesSource`	int	Optional. `0` or `1` (default: `0`). Set to `1` to include cases that cite this node.
`degreesTarget`	int	Optional. `0` or `1` (default: `0`). Set to `1` to include cases cited by this node.
`nodeDataset`	string	Optional. `"ECHR"` or `"RS"`. Auto-detected from the ECLI if omitted.

Validation rules

- nodeId is required and must be non-empty
- At least one of degreesSource or degreesTarget
  must be 1 (otherwise nothing to expand)
- Degrees accept only 0 or 1 (integer, not boolean)
- nodeDataset must be "ECHR" or "RS" if provided
- Unknown request keys are rejected

Edge directionality

Direction	Controlled by	Meaning
Incoming	`degreesSource: 1`	Cases that cite the seed node (source → seed).
Outgoing	`degreesTarget: 1`	Cases cited by the seed node (seed → target).

Response fields

Field	Description
`nodeId`	Echo of the requested ECLI.
`edges`	Array of edge objects with `id`, `source`, and `target`.
`expandedNodes`	Array of hydrated neighbour nodes (same shape as `/api/combined` nodes). Each includes a `dataset` field.

Examples

Expand ECHR node (both directions)

{
  "nodeId": "ECLI:CE:ECHR:1968:0723JUD000147462",
  "degreesSource": 1,
  "degreesTarget": 1
}

Expand RS node (outgoing only)

{
  "nodeId": "ECLI:NL:HR:2018:1234",
  "degreesTarget": 1
}

With explicit dataset

{
  "nodeId": "ECLI:CE:ECHR:2019:0101JUD001234567",
  "degreesSource": 1,
  "nodeDataset": "ECHR"
}

Response

{
  "nodeId": "ECLI:CE:ECHR:1968:0723JUD000147462",
  "edges": [
    {
      "id": "ECLI:CE:ECHR:2006:..._ECLI:CE:ECHR:1968:...",
      "source": "ECLI:CE:ECHR:2006:...",
      "target": "ECLI:CE:ECHR:1968:..."
    },
    {
      "id": "ECLI:CE:ECHR:1968:..._ECLI:CE:ECHR:1961:...",
      "source": "ECLI:CE:ECHR:1968:...",
      "target": "ECLI:CE:ECHR:1961:..."
    }
  ],
  "expandedNodes": [
    {
      "id": "ECLI:CE:ECHR:2006:...",
      "data": {
        "dataset": "ECHR",
        "ecli": "ECLI:CE:ECHR:2006:...",
        "date_judgment": "2006-07-11",
        "respondent_state": "GRC",
        "document_type": "JUD",
        "languages": ["ENG", "FRE"]
      }
    }
  ]
}

POST /api/echr/text

Fetch full-text judgments for ECHR cases by ECLI identifier. Supports single or batch retrieval. Use JSON body.

Parameters

Field	Type	Notes
`ecli`	string \| string[]	Required. String or array in JSON body.
`language`	string	Optional. ISO language code (e.g., `ENG`, `FRE`).

Response fields

Field	Description
`ecli`	The requested ECLI identifier.
`itemid`	Item identifier for the requested language.
`full_text`	Complete judgment text.
`full_text_available`	Boolean flag indicating whether full text is present.
`language`	Language code of the text (e.g., `"ENG"`).

Single ECLI returns one object. Multiple ECLIs return an array of objects.

If full text is missing, full_text is null and a message is included.

If language is omitted, the endpoint prefers ENG, then FRE, then any other language.

If language is omitted, the response includes a languages map keyed by ISO code.

Examples

POST (batch)

{
  "ecli": [
    "ECLI:CE:ECHR:2000:1026JUD003098596",
    "ECLI:CE:ECHR:2005:0315JUD007009801"
  ],
  "language": "ENG"
}

Response (single)

{
  "ecli": "ECLI:CE:ECHR:2000:1026JUD003098596",
  "itemid": "001-0001",
  "full_text": "THIRD SECTION CASE OF...",
  "full_text_available": true,
  "language": "ENG"
}

Response (all languages)

{
  "ecli": "ECLI:CE:ECHR:2000:1026JUD003098596",
  "default_language": "ENG",
  "languages": {
    "ENG": { "itemid": "001-0001", "full_text": "...", "full_text_available": true },
    "FRE": { "itemid": "001-0002", "full_text": null, "full_text_available": false, "message": "Full text not available for this ECLI." }
  }
}

POST /api/network/text

Fetch full-text judgments for Rechtspraak cases by ECLI identifier. Supports single or batch retrieval. Use JSON body.

Parameters

Field	Type	Notes
`ecli`	string \| string[]	Required. String or array in JSON body.

Response fields

Field	Description
`ecli`	The requested ECLI identifier.
`full_text`	Complete judgment text.

Single ECLI returns one object. Multiple ECLIs return an array of objects.

Examples

POST (batch)

{
  "ecli": [
    "ECLI:NL:HR:2019:1234",
    "ECLI:NL:RVS:2017:123"
  ]
}

Response (single)

{
  "ecli": "ECLI:NL:HR:2019:1234",
  "full_text": "..."
}

POST /api/statistics

Compute graph statistics and network metrics for a set of nodes and edges. Uses NetworkX for centrality, PageRank, and Louvain community detection. Pass the same node/edge shape returned by the search endpoints.

Parameters

Field	Type	Notes
`nodes`	array	Required. Node objects with `id` and optional `data` (including `date_decision` or `date_judgment`).
`edges`	array	Required. Edge objects with `source` and `target`.

Computed metrics (per node)

Field	Description
`degree`	Total degree (in + out).
`in-degree`	Number of incoming citations.
`out-degree`	Number of outgoing citations.
`degree centrality`	Degree centrality score.
`in-degree centrality`	In-degree centrality score.
`out-degree centrality`	Out-degree centrality score.
`relative in-degree`	In-degree normalized by network size at node's publication date.
`pageRank`	PageRank score.
`betweenness centrality`	Betweenness centrality score.
`closeness centrality`	Closeness centrality score.
`community`	Community ID (Louvain algorithm on undirected graph).
`parent`	Representative node ECLI for the community.
`year`	Publication year (from date_decision > date_judgment > ECLI pattern).

Returns empty object {} if nodes or edges array is empty.

Examples

Request

{
  "nodes": [
    { "id": "ECLI:NL:HR:2018:1234", "data": { "date_decision": "2018-05-01" } },
    { "id": "ECLI:NL:HR:2017:5678", "data": { "date_decision": "2017-11-15" } },
    { "id": "ECLI:NL:RBAMS:2019:9012", "data": { "date_decision": "2019-02-20" } }
  ],
  "edges": [
    { "source": "ECLI:NL:HR:2018:1234", "target": "ECLI:NL:HR:2017:5678" },
    { "source": "ECLI:NL:RBAMS:2019:9012", "target": "ECLI:NL:HR:2018:1234" }
  ]
}

Response

{
  "ECLI:NL:HR:2018:1234": {
    "parent": "ECLI:NL:HR:2018:1234",
    "degree": 2,
    "in-degree": 1,
    "out-degree": 1,
    "degree centrality": 1.0,
    "in-degree centrality": 0.5,
    "out-degree centrality": 0.5,
    "relative in-degree": 0.5,
    "pageRank": 0.4,
    "betweenness centrality": 1.0,
    "closeness centrality": 1.0,
    "community": 0,
    "year": 2018
  },
  "ECLI:NL:HR:2017:5678": { ... },
  "ECLI:NL:RBAMS:2019:9012": { ... }
}

POST /api/community

Generate keyword labels and legal category classification for a community of nodes. Uses TF-IDF vectorization on node summaries to extract top keywords, then classifies into legal categories: CRIMINAL, IMMIGRATION, CIVIL, ADMINISTRATIVE, or UNDEFINED.

Parameters

Field	Type	Notes
`community_id`	int	Required. Identifier for the community.
`nodes`	array	Required. Nodes with optional `summary` text.
`nodes[].id`	string	Optional. ECLI or node identifier.
`nodes[].summary`	string	Recommended. Case summary text used for keyword extraction.

Response fields

Field	Description
`community_id`	The requested community identifier.
`keywords.keywords`	Top 3 extracted keywords (TF-IDF weighted).
`keywords.category`	Legal category: `CRIMINAL`, `IMMIGRATION`, `CIVIL`, `ADMINISTRATIVE`, or `UNDEFINED`.
`keywords.scores`	TF-IDF relevance scores for each keyword.
`node_count`	Total nodes in the request.
`summary_count`	Nodes that had summary text.

Examples

Request

{
  "community_id": 1,
  "nodes": [
    {
      "id": "ECLI:NL:...",
      "summary": "Vreemdelingenrecht en asielaanvraag..."
    },
    {
      "id": "ECLI:NL:...",
      "summary": "Verblijfsvergunning en terugkeerbesluit..."
    }
  ]
}

Response

{
  "community_id": 1,
  "keywords": {
    "keywords": [
      "asiel",
      "vreemdeling",
      "verblijfsvergunning"
    ],
    "category": "IMMIGRATION",
    "scores": [0.29, 0.22, 0.18]
  },
  "node_count": 2,
  "summary_count": 2
}

POST /api/summaries

Retrieve structured summary segments for Rechtspraak cases. Returns procesverloop (procedural history), overwegingen (considerations), beslissing (decision), and their auto-generated summaries. Data sourced from DynamoDB.

Parameters

Field	Type	Notes
`eclis`	string[]	Required. Non-empty list of ECLI strings.

Response fields (`summaries[].data`)

Field	Description
`procesverloop`	Full procedural history text.
`overwegingen`	Full considerations text.
`beslissing`	Full decision text.
`proces_summary`	Auto-generated procedural summary.
`overw_summary`	Auto-generated considerations summary.
`beslis_summary`	Auto-generated decision summary.

Examples

Request

{
  "eclis": [
    "ECLI:NL:RBAMS:2018:1234",
    "ECLI:NL:RBAMS:2019:5678"
  ]
}

Response

{
  "summaries": [
    {
      "ecli": "ECLI:NL:RBAMS:2018:1234",
      "data": {
        "procesverloop": "Op 12 maart 2018...",
        "overwegingen": "De rechtbank overweegt...",
        "beslissing": "De rechtbank verklaart...",
        "proces_summary": "Procedure betreffende...",
        "overw_summary": "De rechtbank heeft...",
        "beslis_summary": "Vordering toegewezen..."
      }
    }
  ]
}

GET /api/links

Extract Dutch law references from free text and find related cases. Parses the input for article and law references (e.g., "artikel 6 EVRM"), resolves BWB identifiers, and returns matching cases for each reference.

Parameters

Field	Type	Notes
`q`	string	Required. Query param. Text to parse for legal references.

Response fields (per reference)

Field	Description
`type`	Reference type (e.g., `"LAW"`).
`number`	Article or section number.
`bwb_id`	BWB (Basiswettenbestand) identifier.
`bwb_label_id`	BWB label identifier.
`title`	Law title.
`cases`	Array of `[ecli, source]` pairs for related cases.

Examples

Request

GET /api/links?q=artikel%206%20evrm

Response

[
  {
    "type": "LAW",
    "number": "6",
    "bwb_id": "BWBV0001000",
    "bwb_label_id": "6",
    "title": "Europees Verdrag voor de Rechten van de Mens",
    "cases": [
      ["ECLI:NL:HR:2020:...", "RS"],
      ["ECLI:NL:RBAMS:2019:...", "RS"]
    ]
  }
]

GET POST /api/links/laws

Extract law references from text and return the count of related cases for each. More efficient than /api/links when you only need case counts. Supports both GET query parameters and POST JSON body.

Parameters

Field	Type	Notes
`q`	string	Required. Text to parse. GET: query param. POST: JSON body field.

Response fields (per law)

Field	Description
`bwb_id`	BWB identifier.
`bwb_label_id`	BWB label identifier.
`title`	Law title.
`amount_related_cases`	Number of related cases in the database.

Examples

GET

GET /api/links/laws?q=artikel%206%20evrm

POST

{ "q": "artikel 6 evrm" }

Response

[
  {
    "bwb_id": "BWBV0001000",
    "bwb_label_id": "6",
    "title": "Europees Verdrag voor de Rechten van de Mens",
    "amount_related_cases": 42
  }
]

GET /api/links/cases

Return all cases linked to a specific law reference, identified by BWB ID and label ID. Use the values from /api/links or /api/links/laws responses.

Parameters

Field	Type	Notes
`b`	string	Required. BWB identifier (e.g., from `/api/links` response).
`bl`	string	Required. BWB label identifier.

Response format

Returns an array of [ecli, source] tuples, where source indicates the dataset the case belongs to.

Examples

Request

GET /api/links/cases?b=BWBV0001000&bl=6

Response

[
  ["ECLI:NL:HR:2020:1234", "RS"],
  ["ECLI:NL:RBAMS:2019:5678", "RS"],
  ["ECLI:NL:RBDHA:2021:9012", "RS"]
]

API Reference

Authentication & CORS

Pagination

How it works

Example flow

Error Handling

Status codes

Error response shape

Request parameters (inside arguments)

Response node fields (nodes[].data)

Examples

Request parameters (inside arguments)

Response node fields (nodes[].data)

Examples

Request parameters

Rule object

Query builder fields

Validation rules

Examples

Response notes

Typical integration flow

Request parameters

Validation rules

Edge directionality

Response fields

Examples

Parameters

Response fields

Examples

Parameters

Response fields

Examples

Parameters

Computed metrics (per node)

Examples

Parameters

Response fields

Examples

Parameters

Response fields (summaries[].data)

Examples

Parameters

Response fields (per reference)

Examples

Parameters

Response fields (per law)

Examples

Parameters

Response format

Examples

Request parameters (inside `arguments`)

Response node fields (`nodes[].data`)

Request parameters (inside `arguments`)

Response node fields (`nodes[].data`)

Response fields (`summaries[].data`)