---
title: Use the Extensions API
slug: '156'
canonical_url: https://docs.coveo.com/en/156/
collection: index-content
source_format: adoc
---
# Use the Extensions API
[Coveo organization](https://docs.coveo.com/en/185/) [sources](https://docs.coveo.com/en/246/) can pull content from a variety of systems to make your content searchable for those with the appropriate [permissions](https://docs.coveo.com/en/223/) (see [Connector types](https://docs.coveo.com/en/1702#connector-types)).

The [indexing pipeline extension (IPE)](https://docs.coveo.com/en/206/) feature provides a way to execute Python conversion scripts in a securely isolated non-persistent container, allowing developers to customize how [items](https://docs.coveo.com/en/210/) get [indexed](https://docs.coveo.com/en/204/).
Extension scripts can be executed at two different stages of the [indexing pipeline](https://docs.coveo.com/en/184/): _pre-conversion_ and _post-conversion_.

> **Notes**
>
> * You can [manage your indexing pipeline extensions](https://docs.coveo.com/en/1645/) from the [Coveo Administration Console](https://docs.coveo.com/en/183/) [**Extensions**](https://platform.cloud.coveo.com/admin/#/orgid/content/extensions/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/content/extensions/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/content/extensions/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/content/extensions/)) page and get more information on IPEs from the Administration Console documentation.
> 
> * {empty}
>  
> --
> All REST API string fields are case-sensitive unless otherwise specified.
> For example, [search queries aren't case-sensitive](https://docs.coveo.com/en/3074/).
> 
> To keep behavior consistent across the [Coveo Platform](https://docs.coveo.com/en/186/), the same value passed to different REST APIs must always be passed using the same case.
> For example, if the [unique product identifier](https://docs.coveo.com/en/n73f0502#define-a-unique-product-identifier), such as `ec_product_id`, is passed to the Commerce API in lowercase, then it should also be passed to the Usage Analytics Write API in lowercase.
> --

## Usage overview

You can execute an indexing pipeline extension for every item of one or more sources of your organization using the Extension API:

. On the Administration Console [**API Keys**](https://platform.cloud.coveo.com/admin/#/orgid/organization/api-access/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/organization/api-access/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/organization/api-access/)) page, add an API key to which you grant the [privilege](https://docs.coveo.com/en/228/) to edit extensions (that is, the **Edit** [access level](https://docs.coveo.com/en/2818/) on the **Extensions** [domain](https://docs.coveo.com/en/2819/)) (see [Manage API keys](https://docs.coveo.com/en/1718/), [Manage privileges](https://docs.coveo.com/en/3151/), and [Extensions domain](https://docs.coveo.com/en/1707#extensions-domain)).

. Write your extension script using the `document` object (see [`document` object Python API reference](https://docs.coveo.com/en/34/)).

. Create your extension (see [Creating an indexing pipeline extension with the API](https://docs.coveo.com/en/146/)).

. Add your script to your extension.

. Apply your extension to your sources (see [Apply an extension to a source](https://docs.coveo.com/en/1936/)).

. [rebuild](https://docs.coveo.com/en/2712/) your sources to make your extension effective.

. Validate that your changes perform as expected.

## Indexing Pipeline Extensions API versions

When using the Indexing Pipeline Extensions API, you may want to specify the API version you want to use.
By default, version 1 is used.

To specify the version to use, add the `apiVersion` key to your request JSON body.
Accepted values are `v1` and `v2`.
Default is `v1`.

The difference between the API versions are the following:

[%header,cols="~,~,~]
|===
|Aspect |Version 1 |Version 2

|Populating [dictionary fields](https://docs.coveo.com/en/2036/)
|Not supported
|Supported

|[`get_meta_data_value` method](https://docs.coveo.com/en/34#get-meta-data-value-method)
a|* Returns a list of one value when the field contains a single value.

* Returns an empty list when the field is empty.

a|* Returns the field value (without any list wrapper) when the field contains a single value.

* Returns `None` when the field is empty.
|===

By default, the methods listed in the [`document` object Python API reference](https://docs.coveo.com/en/34/) use the version of the IPE API that you used to create your extension.
For example, if you created an extension with version 2 of the API, the methods retrieving metadata will support dictionary fields seamlessly, as they will also use version 2 of the API by default.

However, if you created an extension using version 1 of the API and now need to handle dictionary fields, do one of the following to ensure that version 2 is always used in the future:

* If your extension contains only one method, you can edit the extension script to specify the API version to use in the method call.
For example, if using `document.get_meta_data()`, change it to `document_api.v2.get_meta_data()`.

* If your extension contains multiple methods, make the [Update extension API call](https://platform.cloud.coveo.com/docs?urls.primaryName=Extension#/Indexing%20Pipeline%20Extensions/rest_organizations_paramId_extensions_paramId_put), using `{"apiVersion": "v2"}` as the request body.

In either case, avoid using both versions in an extension and make sure that your extension still works as expected after switching versions.

## Python version deprecation

Currently, the IPE feature uses Python **3.10**.
To see what has been deprecated from 3.8, refer to:

* [Python 3.9](https://docs.python.org/3/whatsnew/3.9.html)

* [Python 3.10](https://docs.python.org/3/whatsnew/3.10.html)

Extensions with deprecation warnings can be seen in the [**Log Browser**](https://platform.cloud.coveo.com/admin/#/orgid/logs/browser/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/logs/browser/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/logs/browser/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/logs/browser/)) as shown below.

![Python deprecation message in the Log Browser | Coveo](https://docs.coveo.com/en/assets/images/index-content/python-deprecation-log-browser-example.png)

Execution of extensions using deprecated code may fail following our upgrade to Python 3.10.

> **Note**
>
> The most common warning is the removal of the `unescape` method, which has been moved from the `HTMLParser` object to the `html` module.
> 
> The following code has been deprecated before Python 3.8 and is not supported in Python 3.10.
> 
> ```python
from html.parser import HTMLParser
h = HTMLParser()
h.unescape("....")
```
> 
> The preceding code should be replaced with:
> ```python
from html import unescape
unescape("....")
```