Migration from V3

This page helps you translate existing V3 (and V1) API calls to the V4 unified filter syntax.

Parameter mapping

V3 parameter	V4 equivalent
type=publication&type=dataset (V1 arrays)	filter=type:publication|dataset
type=("publication" OR "dataset") (V3 expression)	filter=type:publication|dataset
fromPublicationDate=2022&toPublicationDate=2023	filter=from_publication_date:2022,to_publication_date:2023
logicalOperator=AND (top-level)	Implicit: comma is AND, pipe is OR
includeStats=true	facets=type (or any fields you want)
sortBy=citationCount DESC	sort=citation_count:desc
mainTitle=neural network	filter=title.search:neural network
authorOrcid=0000-0002-...	filter=authorships.author.orcid:0000-0002-...
authorFullName=Paolo Manghi	filter=authorships.author.fullname:Paolo Manghi
relProjectFundingShortName=EC	filter=grants.funder_short_name:EC
hasProjectRel=true	filter=has_grant:true
relProjectId=...	filter=grants.project_id:...
relProjectCode=101000360	filter=grants.code:101000360
relOrganizationId=...	filter=affiliations.organization_id:...
relCommunityId=...	filter=communities.id:...
bestOpenAccessRightLabel=OPEN	filter=best_oa.rights:Open Access
influenceClass=C1	filter=impact.influence_class:C1
isPeerReviewed=true	filter=is_peer_reviewed:true
isGreen=true	filter=is_green:true
openAccessColor=gold	filter=oa_color:gold
countryCode=GR	filter=authorships.countries:GR
page=1&pageSize=10	page=1&page_size=10
cursor=*	cursor=* (same)

Key differences

Filter parameter

V3 uses 30+ individual query parameters. V4 collapses them into a single filter= parameter with field:value syntax. Multiple filters are comma-separated (AND logic), and pipe (|) is used for OR within a field.

Sort format

V3: sortBy=citationCount DESC (space-separated, camelCase)

V4: sort=citation_count:desc (colon-separated, snake_case)

Page size

V3: pageSize=10 (camelCase)

V4: page_size=10 (snake_case)

Aggregations

V3 uses includeStats=true which returns a fixed set of statistics.

V4 replaces this with two flexible modes:

• facets=type,best_oa.rights — records + chosen aggregations
• group_by=type — aggregations only, no records

See Aggregations for details.

Sparse fieldsets

V4 introduces select= for requesting only specific response fields. This was not available in V3.

See Sparse fieldsets for details.

Error handling

Code	When
400	Invalid filter syntax, unknown field, disallowed operator, mutual exclusion violation, pagination limit exceeded
404	Research product not found (by-ID endpoint)
500	Internal failure

Error response body:

{
  "status": 400,
  "message": "Unknown filter field: 'foo'"
}