Product DocsMenu

Coveo Platform 7.0 >
Administrator Help > Coveo REST Search API 8.0 > Customizing and Starting the API

Customizing and Starting the Coveo Search API

The Coveo Search API acts as is a bridge between the front-end search interfaces/applications and a Coveo Enterprise Search (CES) instance maintaining an index on the back-end (see Coveo REST Search API 8.0).  

After installing a fresh copy of the Coveo Search API (see Installing the Coveo Search API) or when you want to modify how the service operates, you must edit the Coveo Search API configuration file.

The Coveo Search API configuration file: 

  • Is available in the root Coveo Search API folder, by default C:\Program Files\Coveo Search API 8\config.yml.

  • Is in the YAML format, an easy to read data file format in which the indentation of the elements determines the data structure (see

    Important: The indentation must be done by two spaces, not tabs. Using tabs will cause a syntax error and the service will immediately stop when you try to start it.

  • Is made of various sections containing one or more parameters (see Windows Service Configuration File).

The default configuration file contains only a few of the possible sections and parameters to help you easily specify the index server and the common options to secure the API. The following procedure describes how to configure the common settings.

To customize and start the Coveo Search API

  1. Using an administrator account, connect to the server on which the Coveo Search API is installed.

  2. Using a text editor, open the [Search_API_Install_Path]\config.yml file (by default C:\Program Files\Coveo Search API 8\config.yml).

  3. In the server section of the file:

    Example: The Coveo Search API is installed on the same server as CES (myCoveoMasterServer) and uses the default port (52810).

      uri: https://myCoveoMasterServer:52810
      serverCertificatePath: E:\CES70\Config\Certificates\cert-ca.pem
      clientCertificatePath: E:\CES70\Config\Certificates\cert-iis.p12
    1. For the uri parameter, enter the URI of your Coveo Master server (where Coveo Enterprise Search is installed) hosting the unified index with which you want this REST API to send query and receive search results.

      When the Coveo Search API is on the same server as CES, the default uri (https://localhost:52810) will work.

      When your Coveo Master server is not using the default service port (52810), enter the port it uses.

    2. For the serverCertificatePath and clientCertificatePath parameters, enter the local path where respectively the CES server and client certificates can be found. The REST API will use these certificates to authenticate itself with the index server.

      Note: When the Coveo Search API is on a different server than CES, you must copy the certificate files from the Coveo Master server (typically from the [Index_Path]\Config\Certificates\ folder to the path you enter on the server where the Coveo Search API is installed).

  4. In the basicAuthentication, windowsAuthentication, and guest sections of the file, determine if and how users performing the search must be authenticated to be authorized to get results from the API: 

    Example: With this configuration, only Active Directory users can get results.

      enabled: false
      provider: Active Directory
      enabled: true
      provider: Active Directory
      enabled: false
      name: DOMAIN\user
      provider: Active Directory
    1. For the enabled parameter, enter true when you want to enable this authentication mode.

      Note: basicAuthentication passes credentials in clear text so it should always be used with secured HTTPS (SSL) connections or only for internal tests.

    2. For the provider parameter, enter the name of the security provider that CES will use to validate the authentication.

      Note: You can find the security provider name in the CES Administration Tool Security Providers page.

    Example: When the API can be accessed publicly by anyone, you can enable the guest authentication mode for the S-1-1-0 Windows (Active Directory) Everyone well-known security identifier group.

      enabled: true
      name: S-1-1-0
      provider: Active Directory
      type: Group
  5. When one or more Web application will use this API, identify tokens/GUIDs that applications will need to provide to be authorized to use the API and that you will communicate only to trusted parties (see On-Premises Search Token Authentication):

    Example: The search interfaces from your Web site and your Intranet use this API.

      sharedKey: a0534332-f093-4064-a712-4a79a97c9227
      - name: Website search
        secret: 353c7d37-7445-4217-a0ba-52c772c05632
        allowImpersonate: false
      - name: Intranet search
        secret: 8eSHODDPqGiMvqVY4vwNDut7sdRgwhovSQlAWDLr1nTwSzJi2lDiK
        allowImpersonate: false
    1. In the tokens section of the file, the sharedKey parameter needs to be set only in specific cases (see Configuring Search Token Generation). When this is the case, generate and enter a GUID to be used as a shared key token.

    2. In the applications section of the file, create one subsection starting with a dash for each application that you want to authorize to use this API: 

      1. For the name parameter, enter a name of your choice that will identify the application. This name is only for your reference in this file.

      2. For the secret parameter, generate and enter a GUID to be used as the application secret token.

      3. For the allowImpersonate parameter, leave to false unless the application needs to perform search on behalf of someone else without having to supply the password.

        Example: With Coveo for Salesforce, the user that performs a search is authenticated in Salesforce. The search application gets the user Salesforce account (email) and is set to impersonate this user to only return documents that this user has the permissions to see.

  6. Save the file.

    Note: You can add many other parameters to more specifically control how your Coveo Search API operates (see Windows Service Configuration File).

  7. Start the Coveo Search API service:

    1. Open the Windows Services management console.

    2. Locate and right-click the Coveo Search API service, and then click Start.

    3. Ensure that the service starts.

      Note: The service immediately stops if the config.yml file contains a syntax error such as a tab character that is an invalid character in the YAML format (see REST Search API Windows Service Stops).

  8. You can validate that the service is accessible from various computers:

    1. Using a browser, access the URL in the following format:



      • From the same server when the port is the default (8080):


      • From another computer when the port is not the default:


    2. Validate that the REST API JSON response appears in the browser.

People who viewed this topic also viewed