Create or update an advanced configuration file for a model

This is for:

Developer System Administrator
In this article

The Coveo Machine Learning API configs/{configurationType} endpoints allow you to download and upload an advanced configuration file attached to a Coveo Machine Learning (Coveo ML) model.

Ensure that you’re using an access token with Machine learning - Models - Edit privilege in the target organization (see Add an API key).

Usage overview

The following steps explain how to download a model’s existing advanced configuration file to edit its configuration, and then upload the edited file to the model. If you’re creating an advanced configuration file from scratch, you can go directly to step 2.

Step 1: Download an existing advanced configuration file

Use the GET configs/{configurationType} operation to download a model’s existing advanced configuration file.

Authenticate the request using an access token granting the Machine learning - Models - Edit privilege in the target organization (see Add an API key).

The following request retrieves a model’s desired advanced configuration file:

GET https://platform.cloud.coveo.com/rest​/organizations​/<ORGANIZATION-ID>​/machinelearning​/models​/<MODEL-ID>/configs​/<CONFIGURATION-TYPE> HTTP/1.1

Authorization: Bearer **********-****-****-****-************

For the following example, the downloaded file is a Blocklists file containing a list of terms to be avoided by the model when providing suggestions.

200 OK response body

Example
knight
black knight
dark knight
sword
sabre

Step 2: Create or edit the downloaded advanced configuration file

If you downloaded an existing advanced configuration file, you can edit its configuration using your favorite text editor. You can also create it from scratch.

To learn how to set up your configuration file, click the appropriate link:

Step 3: Upload an advanced configuration file

When you edited the desired configuration file, use the PUT configs/{configurationType} operation to upload a model’s advanced configuration file. Note that the maximum allowed file size is 10 MB.

Authenticate the request using an access token granting the Machine learning - Models - Edit privilege in the target organization (see Add an API key).

The following request uploads a model’s desired advanced configuration file:

PUT https://platform.cloud.coveo.com/rest​/organizations​/<ORGANIZATION-ID>​/machinelearning​/models​/<MODEL-ID>/configs​/<CONFIGURATION-TYPE> HTTP/1.1

Authorization: Bearer **********-****-****-****-************

200 OK response body

{
  "modelId": "<MODEL-ID>",
  "filePath": "<FILE-PATH>"
}

Reference

Authenticating

The Advanced Model Configurations API relies on the bearer HTTP authentication scheme. All HTTP requests made to the Coveo Machine Learning service must include an Authorization header with a valid access token (that is, an API key or OAuth2 token):

Authorization: Bearer <token>

To download or upload a model’s advanced configuration file, the <token> must grant the Machine learning - Models - Edit privilege in the target organization.

Download a model’s advanced configuration file - parameters

When making a GET request to https://platform.cloud.coveo.com/rest/organizations/{organizationId}/machinelearning/models/{modelId}/configs/{configurationType} to download a model’s advanced configuration file, the following parameters apply (see /configs/{configurationType}).

configurationType (string) - required

Parameter type: query

The type of advanced configuration file. Available values are:

languageCode (string) - optional

Parameter type: query

The language of the configuration file to retrieve. It must be an ISO 639-1 code, or the string commons.

modelId (string) - required

Parameter type: path

The unique identifier of the target model (see Review model information).

Example
myOrganization_topclicks_22ec9966_0f8b_4adc_967d_65219552192a

organizationId (string) - required

Parameter type: path

The unique identifier of the target Coveo organization (see Retrieve the organization ID).

Example
myorg6j53h4

Upload a model’s advanced configuration file - parameters

When making a PUT request to https://platform.cloud.coveo.com/rest/organizations/{organizationId}/machinelearning/models/{modelId}/configs/{configurationType} to upload a model’s advanced configuration file, the following parameters apply (see /configs/{configurationType}).

configurationType (string) - required

Parameter type: query

The type of advanced configuration file. Available values are:

languageCode (string) - optional

Parameter type: query

The language of the configuration file to retrieve. It must be an ISO 639-1 code, or the string commons.

modelId (string) - required

Parameter type: path

The unique identifier of the target model (see Review model information).

Example
myOrganization_topclicks_22ec9966_0f8b_4adc_967d_65219552192a

organizationId (string) - required

Parameter type: path

The unique identifier of the target Coveo organization (see Retrieve the organization ID).

Example
myorg6j53h4

configFile (file) - required

Parameter type: formData

The configuration file to be uploaded.

To learn how to set up your configuration file, click the appropriate link: