Perform a simple query

This is for:

Developer
In this article

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

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

Request template

POST https://<MyOrganizationId>.org.coveo.com/rest/search/v2?organizationId=<MyOrganizationId> HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Payload

{
  "q": <MyQuery>
}

In the query path:

In the query string:

  • If the access token you’re using to authenticate the call doesn’t implicitly specify the organization it refers to (i.e., if it’s not a search token):

    • Replace <MyOrganizationId> with the actual ID of the target Coveo organization.

    Otherwise, you don’t need to include the organizationId parameter at al in the query string.

In the Authorization HTTP header:

  • Replace <MyAccessToken> with an access token that grants the privilege to execute queries in the target Coveo organization (see Get your Coveo access token and Authentication methods).

    You can pass an access token as a query string argument (e.g., access_token=MyAccessToken) rather than in an Authorization header.

In the request body:

  • Replace <MyQuery> with the basic query expression (q) 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 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.

Sometimes, 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 title, clickUri, 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

Request - Forwarding a basic query expression to the Search API

POST https://mycoveocloudv2organizationg8tp8wu3.org.coveo.com/rest/search/v2?organizationId=mycoveocloudv2organizationg8tp8wu3 HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "q": "Example"
}

Successful response - 200 OK

{
  "totalCount": 50,
  ...
  "duration": 61,
  ...
  "results": [
    {
      ...
      "title": "Example Domain",
      ...
      "clickUri": "http://www.example.com/",
      ...
      "excerpt": "Example Domain This domain is established to be used for illustrative examples in documents. ...",
      ...
      "score": 4268,
      ...
      "titleHighlights": [
        {
          "length": 7,
          "offset": 0
        }
      ],
      ...
      "excerptHighlights": [
        ...
      ],
      "raw": {
        ...
        "date": 1376092475000,
        "size": 1270,
        "sourcetype": "Web",
        "source": "My web source",
        ...
      }
    },
    ...
  ],
  ...
}