Introductory Tutorial - Creating an Organization and a Source, and Getting Your First Query Results

In this short tutorial, you will make your first steps with the Coveo Cloud platform by creating a Coveo Cloud organization, provisioning it with a simple Web source, and performing a few simple queries.

Step 1 - Log into the Coveo Cloud Platform for the First Time to Register your Identity

If you have never used the Coveo Cloud platform before, you first need to log in (see Logging in to Coveo Cloud V2).

Step 2 - Get your Coveo Cloud Platform Access Token

Now that the Coveo Cloud platform recognizes your identity, you must get an OAuth2 token with which to authenticate some of the REST API calls you are going to make in this tutorial.

Step 3 - Create a Coveo Cloud Organization

Using the access token you got in step 2, create a Coveo Cloud organization.

Creating a Coveo Cloud organization is very quick; you should get a successful response within seconds.

Once your organization has been successfully created, you can verify that your access token now has extensive privileges in this new organization (see Getting the Privileges of an Access Token). In particular, your access token should allow you to view and edit API keys and sources, and execute queries in your organization.

Step 4 - Create an API key

You will now generate an API key with very limited privileges, which you will use to authenticate your next few calls.

Using the access token you got in step 2, create an API key with the following configuration in the organization you created in step 3:

{
  "description": <MyAPIKeyDescription>,
  "displayName": <MyAPIKeyDisplayName>,
  "enabled": true,
  "privileges": [
    {
      "type": "EDIT",
      "targetDomain": "SOURCE",
      "owner": "PLATFORM"
    },
    {
      "type": "VIEW",
      "targetDomain": "SOURCE",
      "owner": "PLATFORM"
    },
    {
      "targetDomain": "EXECUTE_QUERY",
      "owner": "SEARCH_API"
    }
  ]
}

In the above request body:

  • Replace <MyAPIKeyDescription> with an adequate description (e.g., "Created for Alice Smith on 2017-09-25 to try creating a source and performing a query.").

  • Replace <MyAPIKeyDisplayName> with an adequate display name (e.g., "Introductory Tutorial").

Remember that you can only get the API key value once, in the successful response body of its creation call.

Step 5 - Create a Source

An organization becomes useful only when it has at least one source of content.

A source can be secured, meaning that this source contains permissions associated with each item (see Coveo Cloud V2 Management of Security Identities and Item Permissions). In this introductory tutorial, however, you will create a shared source, meaning that no permissions are associated with items, so that anonymous users can get all source items in their query results.

Using the API key you generated in step 4, create a simple shared Web source to index the content of a single public website.

To minimize the crawling time, and to make your source quickly searchable, preferably select a website with less than 100 pages for this tutorial (such as http://www.example.com/).

Creating your very first source should take around 10 minutes, because your Coveo Cloud organization first has to be provisioned.

Once this process is over, though, creating subsequent sources should only take a few seconds (although crawling and indexing their content can take a while, depending on their respective size).

As soon as your source is created, it will start crawling the target website and processing items in the Coveo Cloud indexing pipeline.

Step 6 - Perform a Query

When at least one source item is fully processed, you can start querying your index and getting results.

Using the API key you generated in step 4, try performing a few simple queries and looking at the results.

Step 7 - (Optional) Delete the Coveo Cloud Organization

If you are done testing and do not want to do any further tutorials, you should use the access token you got in step 2 to delete the organization you created in step 3.

Do not delete your Coveo Cloud organization if you want to proceed to more advanced tutorials, as you could re-use it.

What’s Next?

You are now ready to proceed to the Push API Tutorial 1 - Managing Shared Content.

Recommended Articles