Version differences

This is for:

Developer

In this article

Field name normalization
Specific differences

This article aims to explain the key differences between the main versions of Coveo’s Search API.

Version 1 and 2 of the Search API include a compatibility layer designed to ensure that existing Coveo platform integrations continue to work seamlessly as the Search API evolves. This compatibility layer automatically normalizes field names in both requests and responses by adding or removing the sys prefix for certain fields. This ensures backward compatibility with existing legacy integrations that may rely on the old field names.

Outside of this normalization and some specific differences in the way certain fields are handled, the core functionality of the Search API remains consistent across the different versions.

Version 3 of the Search API does not include this compatibility layer. As such, version 3 does not perform any of the field name normalization that versions 1 and 2 do. All field names are handled exactly as provided in the request, and the response will contain the same field names without modification.

Feature/Behavior v1 v2 v3

Feature/Behavior	v1	v2	v3
Field name normalization (`sys` prefix)	Yes	Yes	No
Compatibility layer for legacy field names	Yes	Yes	No
`/fields` endpoint normalization	Yes	No	No
Accepts `sys` fields in requests	Yes	Yes	No
Returns `sys` fields in responses	Yes	Yes	No
Notable caveats	Normalization facilitates backwards compatibility for `sys` fields.	Requests and responses are "as-is"; no normalization is performed.

Field name normalization (sys prefix)

Yes

Compatibility layer for legacy field names

Yes

/fields endpoint normalization

Yes

Accepts sys fields in requests

Yes

Returns sys fields in responses

Yes

Notable caveats

Normalization facilitates backwards compatibility for sys fields.

Requests and responses are "as-is"; no normalization is performed.

Field name normalization

There is a hardcoded list of fields that are normalized by the compatibility layer in versions 1 and 2 of the Search API. These fields are regarded as system fields, or sys fields, and are the only fields that are normalized by the compatibility layer. See About the SYS Field Name Prefix for more information about the sys prefix.

System fields

sysaboutme
sysaddeddate
sysarchivesystem
sysattachmentdepth
sysattachmentparentid
sysauthor
sysauthorloginname
sysbcc
syscc
syscfcomment
syscflabels
syscfspacename
sysclickableuri
syscollection
syscompany
sysconcepts
sysconnectortype
syscontainsattachment
sysconversationreferenceid
sysconversationsubject
sysconversationsubjectid
sysconversationtopic
syscrmaccount
syscrmaccountid
syscrmaccountstatus
syscrmaccounttype
syscrmamount
syscrmasset
syscrmassetpurchasedate
syscrmassetqty
syscrmassetstatus
syscrmbillingcity
syscrmbillingcountry
syscrmbillingpostalcode
syscrmbillingstate
syscrmbillingstreet
syscrmcasecloseddate
syscrmcaseid
syscrmcasepriority
syscrmcasestatus
syscrmcity
syscrmcontact
syscrmcountry
syscrmcurrency
syscrmdivision
syscrmindustry
syscrmopquality
syscrmopsalestage
syscrmopsource
syscrmopstatus
syscrmoptype
syscrmowner
syscrmpostalcode
syscrmproduct
syscrmshippingcity
syscrmshippingcountry
syscrmshippingpostalcode
syscrmshippingstate
syscrmshippingstreet
syscrmstate
syscrmstreet
syscrmwebsite
syscscommunity
syscsitemtype
syscsplace
syscsplacetype
syscstag
syscstaggroup
syscstaskassignedto
sysdate
sysdatebucket
sysdesktopconnectorhostname
sysdesktopconnectorversion
sysdisplaybcc
sysdisplaycc
sysdisplayfrom
sysdisplayparticipants
sysdisplayrecipients
sysdisplayto
sysdocid
sysdocumenttype
sysdtdue
sysdtstart
sysduration
sysemailfolders
sysexcerpt
sysfax
sysfileextension
sysfilename
sysfiletype
sysfirstname
sysfolders
sysfollowupaction
sysfrom
sysfullname
sysfullnameexpanded
sysheight
syshomephone
sysindexeddate
sysinreplyto
sysinternal_email_with_attachments
sysisattachment
sysisdeleteditem
sysisemptydocument
sysisrecord
sysisreference
syslanguage
syslastname
syslinks
syslnform
syslocation
sysloginname
sysmailbox
sysmanager
sysmessageclass
sysmessageid
sysmiddlename
sysmmrpath
sysmobilephone
sysmobileuri
sysmonth
sysoffice
sysopenwithquickview
sysoutlookformacuri
sysoutlookuri
sysowaurl
syspages
sysparentid
sysparents
sysparticipants
syspicturetakenon
syspictureuri
sysprintableuri
sysrecipients
sysrelatedlink
sysrowid
syssearchablemeta
syssfaccount
syssfaccountid
syssfamount
syssfamountconverted
syssfbillingcity
syssfbillingcountry
syssfbillingpostalcode
syssfbillingstate
syssfbillingstreet
syssfcasebugnumbers
syssfcasecallstacks
syssfcasehasbugs
syssfcaseid
syssfcasenumber
syssfcity
syssfclosedate
syssfclosedatebucket
syssfcloseddate
syssfclosequarter
syssfcompany
syssfcontact
syssfcountry
syssfcreatedby
syssfcreatedbyid
syssfcreateddate
syssfcreateddatebucket
syssfcurrency
syssfcurrentpriority
syssfdescription
syssfduration
syssfemail
syssffax
syssffirstname
syssfid
syssfindustry
syssflastname
syssfleadsource
syssflocation
syssfopendate
syssfopportunitytype
syssfowner
syssfownerid
syssfparents
syssfphone
syssfpostalcode
syssfpricebandid
syssfpricebandname
syssfpriority
syssfproducts
syssfshippingcity
syssfshippingcountry
syssfshippingpostalcode
syssfshippingstate
syssfshippingstreet
syssfstagename
syssfstate
syssfstatus
syssfstreet
syssfwebsite
syssite
syssize
syssource
syssourcetype
sysspauthorid
sysspblogpostid
sysspcontenttype
sysspdocsetguid
sysspdocsetname
sysspenableofficeintegration
sysspiscontainer
sysspisdraft
sysspispersonalsite
sysspistoplevelsite
sysspitemtype
syssplistbasetype
syssplistguid
syssplistitemguid
syssplistitemid
syssplistname
syssplisttruncatedguid
syssplisttype
sysspparentguids
sysspparentname
sysspparenttruncatedguid
syssprelativelisturi
sysspsiteguid
sysspsitename
sysspsitetruncatedguid
sysspsiteuri
syssptagguids
syssptagnames
sysspversion
syssubject
systargetfileext
systitle
systo
systopparent
systopparentid
systransactionid
sysuri
sysurihash
syswcmid
syswcmlibrary
syswcmtype
syswidth
sysworkemail
sysworkphone
sysworktitle
sysyear

Specific differences

Some specific differences exist between the versions of the Search API, particularly in how certain fields are handled on specific endpoints.

Search

Request

Search requests using sys fields in their request body have those fields normalized before being sent to the index. The @date and year fields in the example below are both sys fields, and are normalized before being sent to the index as follows:

Sent to the Search API

{
  "q": "@date=2024-01-01",
  "groupBy": [
    {
      "field": "year"
    }
  ]
}

Sent to the index

{
  "q": "@sysdate=2024-01-01",
  "groupBy": [
    {
      "field": "sysyear"
    }
  ]
}

Response

In search responses, in addition to normalization, certain top level fields are also returned twice. One version of the field will be lowercase, while the other is capitalized. For example, the title field is returned as both title and Title in the response returned from the Search API below.

Returned by the index

"results": [
  {
    "title": "hello",
    "uri": "file://case5",
    "raw": {
      "urihash": "TTtC5QltXUNvIyO1",
      "date": 1727447125000,
    },
  },
]

Returned by Search API

"results": [
  {
    "title": "hello",
    "uri": "file://case5",
    "raw": {
      "urihash": "TTtC5QltXUNvIyO1",
      "date": 1727447125000,
      "sysurihash": "TTtC5QltXUNvIyO1", 
      "sysdate": 1727447125000, 
    },
    "Title": "hello", 
    "Uri": "file://case5", 
  },
]

	These fields are duplicated as `sys` fields.
	These fields are duplicated as uppercase.

List fields

The request body for the request targetting the /rest/search/fields endpoint is empty, while the response body contains a list of fields that are available for the organization.

This endpoint only performs normalization on the v1 route. The v2 and v3 routes do not perform any normalization on the field names returned.

Response

Returned by the index

{
  "fields": [
    {
      "type": "Field",
      "name": "uri",
      "nativeName": "@uri",
      "description": "The URI of the document",
      "defaultValue": "",
      "fieldType": "LargeString",
      "fieldSourceType": "System",
      "includeInQuery": true,
      "includeInResults": true,
      "groupByField": false,
      "splitGroupByField": false,
      "sortByField": false
    },
  ]
}

Returned by Search API

{
  "fields": [
    {
      "type": "Field",
      "name": "@sysuri", 
      "nativeName": "@uri",
      "description": "The URI of the document",
      "defaultValue": "",
      "fieldType": "LargeString",
      "fieldSourceType": "System",
      "includeInQuery": true,
      "includeInResults": true,
      "groupByField": false,
      "splitGroupByField": false,
      "sortByField": false
    },
  ]
}

The sys prefix is added to the field name in the v1 version of the Search API.

List field values

The request body for the request targeting the /rest/search/values endpoint is a JSON object containing a single field, field, which specifies the field for which to retrieve values. In the v1 and v2 versions of the Search API, this would accept a sys field, while in v3 it will be expected to be the as-is field instead. The example below shows the normalization that occurs on v1 and v2 of the request to /rest/search/values.

Request

Sent to the Search API

{
  "field": "sysyear"
}

Sent to the index

{
  "field": "year" 
}

The sys prefix is removed from the field name before being sent to the index.