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

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

Step 1: Log in to the Coveo Platform for the First Time to Register your Identity

If you have never used the Coveo Platform before, you first need to log in (see Log in to Coveo Cloud).

Step 2: Get your Coveo Platform Access Token

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

Step 3: Create a Coveo Organization

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

Creating a Coveo 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 Get 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’ll now generate an API key with very limited privileges, which you’ll 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 index permissions associated with each item to allow a Coveo-powered search interface to replicate them when displaying search results. In this introductory tutorial, however, you’ll create a source whose content is accessible to everyone ("sourceVisibility": "PUBLIC"), 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 public 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

Creating your very first source should take around 10 minutes, because your Coveo 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 Organization

If you’re done testing and don’t 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.

Don’t delete your Coveo organization if you want to proceed to more advanced tutorials, as you could re-use it.

What’s Next?

You’re now ready to proceed to the Push API Tutorial 1: Manage Public Content.

Recommended Articles