---
title: Set advanced model configurations using the API
slug: l3td0254
canonical_url: https://docs.coveo.com/en/l3td0254/
collection: leverage-machine-learning
source_format: adoc
---
# Set advanced model configurations using the API
The [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Advanced Model Configurations API](https://docs.coveo.com/en/19/api-reference/machine-learning-api#tag/Advanced-Model-Configurations) lets you set an advanced configurations for a [model](https://docs.coveo.com/en/1012/) using configuration files.

To set an advanced configuration using the API

. [Create or update an advanced configuration file](#create-or-update-an-advanced-configuration-file).

. [Upload the advanced configuration file](#upload-an-advanced-configuration-file) to the model.

> **Tip**
>
> You can also [get a list of advanced configuration files](https://docs.coveo.com/en/l3pa9257/) currently used by a model, or [delete a configuration file](https://docs.coveo.com/en/l3pa9008/) from a model.

## Create or update an advanced configuration file

Setting an advanced configuration using the API requires an advanced configuration file.

You can create a new configuration file from scratch, or download an existing file that you previously uploaded to a model to edit its configuration.

. If required, to edit an advanced configuration file that's currently used by a [model](https://docs.coveo.com/en/1012/), first download the file using the Swagger UI as follows:

.. Access the **Advanced Model Configurations** section of the Swagger UI that's associated with your Coveo organization region ([US](https://platform.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations) | [CA](https://platform-ca.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations) | [EU](https://platform-eu.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations) | [AU](https://platform-au.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations)).

.. Click **Authorize** and authenticate using your Coveo organization account credentials.

> **Note**
>
> The Coveo organization account you use for authentication must have the **Machine learning - Models - Edit** privilege.

.. Use the `configs/{configurationType}` GET operation to download an existing configuration file that you want to edit:

![Use Swagger UI to download a model advanced configuration file | Coveo](https://docs.coveo.com/en/assets/images/leverage-machine-learning/model-advanced-api-swagger-get.png)

... [Enter the required parameters](#advanced-model-configuration-api-parameters) for the model and configuration type that you want to download.

... Once you've entered the parameters, click **Execute**.

... Click **Download file** in the response body to download the file.

. Use your preferred text editor to either modify the downloaded advanced configuration file or create a new file from scratch.
The configuration file requirements and formatting depends on the configuration type:

** [Blocklist](https://docs.coveo.com/en/l3od9093#blocklist-file-configuration)

** [Stop words](https://docs.coveo.com/en/l3od9093#stop-words-file-configuration)

** [Default queries](https://docs.coveo.com/en/l3od9093#default-queries-file-configuration)

** [ID mappings](https://docs.coveo.com/en/l3od9093#id-mapping-file-configuration)

. [Upload the advanced configuration file](#upload-an-advanced-configuration-file) to the model.

## Upload an advanced configuration file

Once you've [created the configuration file](#create-or-update-an-advanced-configuration-file), use the Swagger UI to upload it to a model to apply the advanced configuration to that model.

. Access the **Advanced Model Configurations** section of the Swagger UI that's associated with your Coveo organization region ([US](https://platform.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations) | [CA](https://platform-ca.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations) | [EU](https://platform-eu.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations) | [AU](https://platform-au.cloud.coveo.com/docs?urls.primaryName=Machine+Learning#/Advanced%20Model%20Configurations)).

. Click **Authorize** and authenticate using your Coveo organization account credentials.

> **Note**
>
> The Coveo organization account you use for authentication must have the **Machine learning - Models - Edit** privilege.

. Use the `configs/{configurationType}` PUT operation to upload a configuration file to the model that you want to configure:

![Use Swagger UI to upload a model advanced configuration file | Coveo](https://docs.coveo.com/en/assets/images/leverage-machine-learning/model-advanced-api-swagger-put.png)

.. [Enter the required parameters](#advanced-model-configuration-api-parameters) for the model to which you want to upload the file, as well as the configuration type.

.. For **configFile**, click **Choose File** to select the configuration file.

.. Click **Execute**.

## Advanced model configuration API parameters

### `configurationType` (string) - required

**Parameter type**: `query`

The type of advanced configuration file. Available values are:

* [`BLOCKLISTS`](https://docs.coveo.com/en/l3od9093#blocklist)
* [`STOPWORDS`](https://docs.coveo.com/en/l3od9093#stop-words)
* [`DEFAULT_QUERIES`](https://docs.coveo.com/en/l3od9093#default-queries)
* [`ID_MAPPING`](https://docs.coveo.com/en/l3od9093#id-mappings)

### `languageCode` (string) - optional

**Parameter type**: `query`

The language of the configuration file.
It must be an [ISO 639-1 code](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes), or the string `commons`.

> **Important**
>
> For a configuration file that uses the `commons` language value, the queries in that file are automatically added to every other language-specific default queries files in your model.
> Languages without a default queries file aren't affected by the `commons` file.
> 
> For example, your [model](https://docs.coveo.com/en/1012/) processes queries in English (`en`), French (`fr`), and Spanish (`es`), but your model includes only `en` and `fr` default queries configuration files.
> Uploading a `commons` file will add its list of queries to the `en` and `fr` configuration files, but not to any other language.

### `modelId` (string) - required

**Parameter type**: `path`

The unique identifier of the target model (see [Review model information](https://docs.coveo.com/en/1894/)).

**Example**

```text
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](https://docs.coveo.com/en/148/)).

**Example**

```text
myorg6j53h4
```

### `configFile` (file) - required

> **Note**
>
> This applies only when uploading a model's advanced configuration file.

**Parameter type**: `formData`

The configuration file to be uploaded.

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

* [Blocklist](https://docs.coveo.com/en/l3od9093#blocklist-file-configuration)
* [Stop words](https://docs.coveo.com/en/l3od9093#stop-words-file-configuration)
* [Default queries](https://docs.coveo.com/en/l3od9093#default-queries-file-configuration)
* [ID mappings](https://docs.coveo.com/en/l3od9093#id-mapping-file-configuration)