Perform a simple query

This is for:

Developer

In this article

Sample request

The goal of any Coveo Platform 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:

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

In the query string:

If the access token that you’re using to authenticate the call doesn’t implicitly specify the organization it refers to (that is, if it’s not a search token):
- Replace <MyOrganizationId> with the ID of the target Coveo organization.
Otherwise, you don’t need to include the organizationId parameter 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 Search API authentication methods).

Note

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

In the request body:

Replace <MyQuery> with the basic query expression (q) that you want to forward to the Search API, such as the keywords that a user would enter in a search box.

Example

You can pass one or more keywords, such as human resources jobs, to get all of the source items that contain these keywords.

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

You can include exact phrase match requests in the q value by surrounding groups of keywords with escaped double quote characters (for example, "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 (for example, "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.

Note

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 affect the score value of query result items. Of course, the Search API also lets you use sort criteria other 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, such as its title, clickUri, and automatically generated excerpt. You can leverage these 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 emphasize q 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, including its most recent modification date, its size, the name of its source, and its sourceType. You can explicitly specify which fields to include in (or exclude from) the query result items when performing a query.

Sample 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",
        ...
      }
    },
    ...
  ],
  ...
}