Skip to end of metadata
Go to start of metadata

In this topic:

Ultimately, the goal of any Coveo Cloud V2 platform user is to perform queries against a unified, secured index in a specific Coveo Cloud V2 organization, and retrieve the most relevant query result items.

Use the Search request to the Search API operation to perform a simple query:

In the request query string:

  • If the access token you are using to authenticate the call does not implicitly specify the organization it refers to (i.e., if it is not a search token):

    Otherwise, you do not need to include the organizationId parameter at al in your request query string.

In the Authorization HTTP header:

In the request body:

  • Replace <MyQuery> by the basic query expression you want to forward to the Search API, such as the keywords an end-user would enter in a search box. 


    You can pass one or more keywords such as human resources jobs to get all source items containing these keywords.

    You can pass an empty request body rather than specifying a q value to return all items in the target organization index.

    You can include exact phrase match requests in the q value by surrounding groups of keywords with properly escaped double quote characters (e.g., "q": "Coveo \"Cloud V2\" platform").

    Unless you explicitly set the enableQuerySyntax property to false in the request body, you can also include any valid Coveo Cloud query syntax in the q value (e.g., "q": "Example AND @sourcetype==Web").

The body of a successful response (200 OK) contains information about the query itself, such as its duration and the totalCount of query result items. Most importantly, the response body contains the query results.


Occasionally, the response body also contains an executionReport with detailed debug information.

By default, elements in the results array are sorted by relevancy: a standard set of ranking rules is applied to compute a score value for each query result item; the higher a query result item score value is, the lower its 0-based index position in the results array will be. There are several ways you can impact the score value of query result items. Of course, the Search API also allows you to use other sort criteria than the score value, so you should never have to sort query result items client-side.

Each element in the results array contains specific information about a single query result item: its titleclickUri, automatically generated excerpt, etc. You can leverage those values to display relevant information when rendering the query results in a graphical search interface. You can also take advantage of the titleHighlights and excerptHighlights properties to adequately emphasize basic query expression keywords in the title and excerpt.

The raw property of each results element is also very important, as it holds the fields which were retrieved for this item, and their corresponding values. Each field typically contains specific metadata about an item: its most recent modification date, its size, the name of its source, its sourceType, etc. You can explicitly specify which fields to include in (or exclude from) the query result items when performing a query.

Sample Request

Example request - Forwarding a basic query expression to the Search API
Successful response - 200 OK
  • No labels