---
title: GraphQL API source configuration reference
slug: o1ae7549
canonical_url: https://docs.coveo.com/en/o1ae7549/
collection: index-content
source_format: adoc
---
# GraphQL API source configuration reference
When [creating a GraphQL API source](https://docs.coveo.com/en/n6gh2329/) in the [Coveo Administration Console](https://docs.coveo.com/en/183/), you must provide a JSON configuration detailing what to crawl to retrieve the desired content, and how to retrieve items of each type.
This configuration has a single property, [`Services`](#services-array-required), whose value must be an array of objects.
**Example**
```json
{
"Services": [
{
"Url": "https://api.github.com/",
"authentication": {
"username": "@username",
"password": "@password",
"forceBasicAuthentication": "true"
},
"Endpoints": [
{
"paging": {
"pageSize": 10,
"offsetType": "cursor",
"nextPageKey": "data.user.pullRequests.pageInfo.endCursor"
},
"headers": {
"accept": "application/vnd.github.v3+json",
"User-Agent": "PostmanRuntime/7.29.0"
},
"Path": "graphql",
"Method": "POST",
"ItemPath": "data.user.pullRequests.edges",
"SkippableErrorCodes": "404",
"ItemType": "PullRequests",
"Uri": "%[node.url]",
"ClickableUri": "%[node.url]",
"Title": "%[node.title]",
"ModifiedDate": "%[node.createdAt]",
"PayloadJsonContent": "@MyFirstQuery"
}
]
}
]
}
```
This reference article defines parameters to include in your JSON configuration.
When working on your GraphQL API source, you may also want to refer to the following articles:
* [Add a GraphQL API source](https://docs.coveo.com/en/n6gh2329/)
* [Concepts](https://docs.coveo.com/en/n7jg0349/)
* [Permission configuration reference](https://docs.coveo.com/en/n7jg0461/)
> **Tip**
>
> Use online tools such as [JSONPath Online Evaluator](https://jsonpath.com/) to test your [JSON paths](https://docs.coveo.com/en/n7jg0349/), and [freeformatter.com](https://www.freeformatter.com/) to validate and escape your JSON configuration.
## About the GraphQL API source configuration
When you [create a GraphQL API source](https://docs.coveo.com/en/n6gh2329/) in the Coveo Administration Console, you must provide a JSON source configuration listing the content to crawl.
This JSON configuration must also indicate which API calls to execute to fetch the desired items and how to parse the responses to extract relevant [metadata](https://docs.coveo.com/en/218/).
Coveo's GraphQL API [connector](https://docs.coveo.com/en/2734/) is actually the REST API connector under the hood.
So, the JSON configuration to provide is very similar.
Although the expected configuration follows the [repository structure of a REST API](https://docs.coveo.com/en/3131#repository-structure), with services and endpoints, it also works with GraphQL APIs.
## Table of contents
To help you jump to the right section, here's a hierarchical and alphabetical list of all supported arrays, objects, and parameters.
**Show table of contents**
Details
[%header,cols="columns"]
|===
|Hierarchical list |Alphabetical list
a|[`Services`](#services-array-required) (required)
* [`Endpoints`](#endpoints-array-required) (required)
** [`ClickableUri`](#clickableuri-string-required) (required)
** [`ItemType`](#itemtype-string-required) (required)
** [`Path`](#path-string-required) (required)
** [`Uri`](#uri-string-required) (required)
** [`Body`](#body-string)
** [`DateFormat`](#dateformat-string)
** [`ExtendedMetadata`](#extendedmetadata-object)
*** [`Expression`](#expression-object-required) (required)
**** [`Value`](#value-string-required) (required)
**** [`IsDynamicCondition`](#isdynamiccondition-boolean)
*** [`ExtendedMetadataActions`](#extendedmetadataactions-array)
**** [`ActionName`](#actionname-string-enum-required) (required)
**** [`OldValue`](#oldvalue-and-newvalue-string)
**** [`NewValue`](#oldvalue-and-newvalue-string)
**** [`DefaultValue`](#defaultvalue-string)
**** [`FallbackValuesTrigger`](#fallbackvaluestrigger-array)
**** [`StringSeparator`](#stringseparator-string)
** [`IndexingAction`](#indexingaction-object)
*** [`ActionOnItem`](#actiononitem-string-required) (required)
*** [`Condition`](#action-condition-string)
** [`ItemPath`](#itempath-string)
** [`Metadata`](#metadata-object)
** [`Method`](#method-string-enum)
** [`ModifiedDate`](#modifieddate-string)
** [`PayloadJsonContent`](#payloadjsoncontent-string)
** [`PayloadParameters`](#payloadparameters-object)
** [`PermanentId`](#permanentid-string)
** [`ProcessingAction`](#processingaction-object)
** [`QueryParameters`](#queryparameters-object)
** [`RefreshEndpoints`](#refreshendpoints-array)
*** [`IsDeletionQuery`](#isdeletionquery-boolean)
*** [`IsDeletedItem`](#isdeleteditem-boolean)
*** [`DeleteChildren`](#deletechildren-boolean)
** [`StringItemPath`](#stringitempath-string)
** [`SubItems`](#subitems-array)
** [`SubQueries`](#subqueries-array)
*** [`ExecutionCondition`](#executioncondition-string)
*** [`IsBinaryBody`](#isbinarybody-boolean)
*** [`IsThumbnail`](#isthumbnail-boolean)
** [`Title`](#title-string)
* [`Url`](#url-string-required) (required)
* [`Authentication`](#authentication-object)
** [`Username`](#username-string)
** [`Password`](#password-string)
** [`Domain`](#domain-string)
** [`ForceBasicAuthentication`](#forcebasicauthentication-boolean)
** [`OAuth`](#oauth-object)
*** [`Query`](#query-object-required) (required)
**** [`RefreshUrl`](#refreshurl-string-required) (required)
**** [`Headers`](#oauth-query-headers-object)
**** [`Method`](#oauth-query-method-string-enum)
**** [`Parameters`](#oauth-query-parameters-object)
*** [`Response`](#response-object)
**** [`AccessToken`](#accesstoken-string)
**** [`SupportsRefreshToken`](#supportsrefreshtoken-boolean)
**** [`RefreshToken`](#refreshtoken-string)
**** [`ExpiresIn`](#expiresin-string)
**** [`ExpiresInDefaultValue`](#expiresindefaultvalue-number)
**** [`TokenType`](#tokentype-string)
**** [`TokenTypeDefaultValue`](#tokentypedefaultvalue-string)
**** [`AuthorizationHeader`](#authorizationheader-string)
*** [`UsingSingleUseRefreshToken`](#usingsingleuserefreshtoken-boolean)
* [`Headers`](#headers-object)
* [`Paging`](#paging-object)
** [`OffsetType`](#offsettype-string-enum-required) (required)
** [`PageSize`](#pagesize-number-required) (required)
** [`DoNotInherit`](#donotinherit-boolean)
** [`NextPageKey`](#nextpagekey-string)
** [`OffsetStart`](#offsetstart-number)
** [`TotalCountHeaderKey`](#totalcountheaderkey-string)
** [`TotalCountKey`](#totalcountkey-string)
* [`Permissions`](#permissions-array)
** [`Name`](#permission-level-name-string)
** [`PermissionsSets`](#permissionssets-array)
*** [`Name`](#permission-set-name-string)
*** [`AllowedMembers` and `DeniedMembers`](#allowedmembers-and-deniedmembers-arrays)
**** [`Name`](#member-name-string-required) (required)
**** [`Type`](#member-type-string-enum-required) (required)
**** [`Condition`](#permission-condition-string)
**** [`PermissionType`](#permissiontype-string)
**** [`AdditionalInfo`](#additionalinfo-object)
*** [`IsAnonymousAllowed`](#isanonymousallowed-boolean)
*** [`PermissionsFromMetadata`](#permissionsfrommetadata-array)
**** [`IsAllowedMember`](#isallowedmember-boolean)
*** [`PermissionSubQueries`](#permissionsubqueries-array)
* [`RetryableHttpErrorCodes`](#retryablehttperrorcodes-string)
* [`SkippableErrorCodes`](#skippableerrorcodes-string)
|[`AccessToken`](#accesstoken-string)
[`ActionName`](#actionname-string-enum-required)
[`ActionOnItem`](#actiononitem-string-required)
[`AdditionalInfo`](#additionalinfo-object)
[`AllowedMembers`](#allowedmembers-and-deniedmembers-arrays)
[`Authentication`](#authentication-object)
[`AuthorizationHeader`](#authorizationheader-string)
[`Body`](#body-string)
[`ClickableUri`](#clickableuri-string-required)
[`Condition`](#action-condition-string) (action on item)
[`Condition`](#permission-condition-string) (permission)
[`DateFormat`](#dateformat-string)
[`DefaultValue`](#defaultvalue-string)
[`DeleteChildren`](#deletechildren-boolean)
[`DeniedMembers`](#allowedmembers-and-deniedmembers-arrays)
[`Domain`](#domain-string)
[`DoNotInherit`](#donotinherit-boolean)
[`Endpoints`](#endpoints-array-required)
[`ExecutionCondition`](#executioncondition-string)
[`ExpiresIn`](#expiresin-string)
[`ExpiresInDefaultValue`](#expiresindefaultvalue-number)
[`Expression`](#expression-object-required)
[`ExtendedMetadata`](#extendedmetadata-object)
[`ExtendedMetadataActions`](#extendedmetadataactions-array)
[`FallbackValuesTrigger`](#fallbackvaluestrigger-array)
[`ForceBasicAuthentication`](#forcebasicauthentication-boolean)
[`Headers`](#oauth-query-headers-object) (OAuth query)
[`Headers`](#headers-object) (service level)
[`IndexingAction`](#indexingaction-object)
[`IsAllowedMember`](#isallowedmember-boolean)
[`IsAnonymousAllowed`](#isanonymousallowed-boolean)
[`IsBinaryBody`](#isbinarybody-boolean)
[`IsDeletedItem`](#isdeleteditem-boolean)
[`IsDeletionQuery`](#isdeletionquery-boolean)
[`IsDynamicCondition`](#isdynamiccondition-boolean)
[`IsThumbnail`](#isthumbnail-boolean)
[`ItemPath`](#itempath-string)
[`ItemType`](#itemtype-string-required)
[`Metadata`](#metadata-object)
[`Method`](#method-string-enum) (endpoint query)
[`Method`](#oauth-query-method-string-enum) (OAuth query)
[`ModifiedDate`](#modifieddate-string)
[`Name`](#member-name-string-required) (member)
[`Name`](#permission-level-name-string) (permission level)
[`Name`](#permission-set-name-string) (permission set)
[`NewValue`](#oldvalue-and-newvalue-string)
[`NextPageKey`](#nextpagekey-string)
[`OAuth`](#oauth-object)
[`OffsetStart`](#offsetstart-number)
[`OffsetType`](#offsettype-string-enum-required)
[`OldValue`](#oldvalue-and-newvalue-string)
[`PageSize`](#pagesize-number-required)
[`Paging`](#paging-object)
[`Parameters`](#oauth-query-parameters-object) (OAuth query)
[`Password`](#password-string)
[`Path`](#path-string-required)
[`PayloadJsonContent`](#payloadjsoncontent-string)
[`PayloadParameters`](#payloadparameters-object)
[`PermanentId`](#permanentid-string)
[`Permissions`](#permissions-array)
[`PermissionsFromMetadata`](#permissionsfrommetadata-array)
[`PermissionsSets`](#permissionssets-array)
[`PermissionSubQueries`](#permissionsubqueries-array)
[`PermissionType`](#permissiontype-string)
[`ProcessingAction`](#processingaction-object)
[`Query`](#query-object-required)
[`QueryParameters`](#queryparameters-object)
[`RefreshEndpoints`](#refreshendpoints-array)
[`RefreshToken`](#refreshtoken-string)
[`RefreshUrl`](#refreshurl-string-required)
[`Response`](#response-object)
[`RetryableHttpErrorCodes`](#retryablehttperrorcodes-string)
[`Services`](#services-array-required)
[`SkippableErrorCodes`](#skippableerrorcodes-string)
[`StringItemPath`](#stringitempath-string)
[`StringSeparator`](#stringseparator-string)
[`SubItems`](#subitems-array)
[`SubQueries`](#subqueries-array)
[`SupportsRefreshToken`](#supportsrefreshtoken-boolean)
[`Title`](#title-string)
[`TokenType`](#tokentype-string)
[`TokenTypeDefaultValue`](#tokentypedefaultvalue-string)
[`TotalCountKey`](#totalcountkey-string)
[`TotalCountHeaderKey`](#totalcountheaderkey-string)
[`Type`](#member-type-string-enum-required) (member)
[`Uri`](#uri-string-required)
[`Url`](#url-string-required)
[`Username`](#username-string)
[`UsingSingleUseRefreshToken`](#usingsingleuserefreshtoken-boolean)
[`Value`](#value-string-required)
|===
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
Let's say you want to index product IDs in the `product_id` field.
If the API that you call returns ID values such as `gid://Store/Product/12345`, you need to trim the `gid://Store/Product/` part to only index the actual product ID.
The following rule replaces `gid://Store/Product/` with an empty string in values retrieved with the `%[id]` dynamic value.
So, if your API returns `"id": "gid://Store/Product/12345"`, Coveo indexes `12345` in the `product_id` field.
```json
"ExtendedMetadata": {
"product_id": { <1>
"Expression": {
"value": "%[id]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": "gid://shopify/Product/",
"NewValue": ""
}
]
}
}
```
<1> In the `product_id` field, Coveo will index the result of the rule in this object.
<2> `%[id]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `id` in your API response.
<3> Coveo will alter the metadata retrieved with `%[id]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
* `"%[node.author_id]"` is true if the item has an `author_id`.
* `"NOT %[node.author_id]"` is true if the item doesn't have an `author_id`.
* `"%[node.author_id] == 1234"` is true if the item `author_id` is `1234`.
* `"%[node.author_ids] == [1,2,3,4]"` is true if item `author_ids` are `1`, `2`, `3`, and `4`.
* `"%[node.author_id] OR %[author_name]"` is true if the item has an `author_id` or an `author_name`.
* `"%[node.author_id] AND %[author_name]"` is true if the item has an `author_id` and an `author_name`.
* `+"%[node.author_id] > 123"+` is true if the item `author_id` is greater than 123.
* `"(%[node.author_id] OR %[node.author_sys_id]) AND %[node.author_name]"` is true if the item has an `author_id` or an `author_name`, as well as an `author_name`.
Details
The following rule evaluates whether the value retrieved with the `%[inventoryQuantity]` dynamic value is greater than 0.
The result is indexed in the `in_inventory` field as a Boolean value.
So, if your API returns `"inventoryQuantity": "409"`, Coveo indexes `true`.
```json
"ExtendedMetadata": {
"in_inventory": { <1>
"Expression": {
"Value": "%[inventoryQuantity] > 0", <2>
"IsDynamicCondition": true <3>
}
}
}
```
<1> In the `in_inventory` field, Coveo will index the result of the rule in this object.
<2> `%[inventoryQuantity]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `inventoryQuantity` in your API response.
With this `Value` property, Coveo evaluates whether the retrieved value is greater than 0.
<3> The [`IsDynamicCondition`](#isdynamiccondition-boolean) property is set to `true` to indicate that the `Value` property is a dynamic condition to evaluate.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product IDs in the `product_id` field.
If the API that you call returns ID values such as `gid://Store/Product/12345`, you need to trim the `gid://Store/Product/` part to only index the actual product ID.
The following rule replaces `gid://Store/Product/` with an empty string in values retrieved with the `%[id]` dynamic value.
So, if your API returns `"id": "gid://Store/Product/12345"`, Coveo indexes `12345` in the `product_id` field.
```json
"ExtendedMetadata": {
"product_id": { <1>
"Expression": {
"value": "%[id]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": "gid://shopify/Product/",
"NewValue": ""
}
]
}
}
```
<1> In the `product_id` field, Coveo will index the result of the rule in this object.
<2> `%[id]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `id` in your API response.
<3> Coveo will alter the metadata retrieved with `%[id]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
You use the `FormatHierarchical` action because you're planning to add a [hierarchical facet](https://docs.coveo.com/en/2667/) to your Coveo-powered search interface.
This action reformats your metadata in the way that's required for the hierarchical facet to work properly.
Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
So, if your API returns `"category": "Men > Clothing > Shoes"`, Coveo indexes `Men;Men|Clothing;Men|Clothing|Shoes` in the `ec_categories` field.
Then, once you add a hierarchical facet based on the `ec_categories` field to your search interface, your search interface will allow users to filter results by selecting a category such as `Men`, and then a subcategory such as `Shoes`, and so on.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "FormatHierarchical",
"StringSeparator": " > " <4>
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
Details
The following rule trims leading and trailing whitespace characters from values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": " Surf boards "`, Coveo indexes `Surf boards` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Trim"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces ` > ` with a `;` character in values retrieved with the `%[category]` dynamic value.
So, if your API returns `"category": "Electronics > Phones"`, Coveo indexes `"Electronics;Phones"` in the `ec_categories` field.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": " > ",
"NewValue": ";"
},
{
"ActionName": "Default", <4>
"DefaultValue": "No category"
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> If Coveo can't find the `OldValue` in the metadata, it moves on to the next rule.
With the second rule, if no category metadata is returned, Coveo indexes `Unknown category` in the `categories` field.
Then, if you select the [**Multi-value facet** option](https://docs.coveo.com/en/1833#facet-and-multi-value-facet) for the `ec_categories` field, your search interface will allow users to filter results by selecting `Electronics` and/or `Phones`.
Details
Let's say you want to index product IDs in the `product_id` field.
If the API that you call returns ID values such as `gid://Store/Product/12345`, you need to trim the `gid://Store/Product/` part to only index the actual product ID.
The following rule replaces `gid://Store/Product/` with an empty string in values retrieved with the `%[id]` dynamic value.
So, if your API returns `"id": "gid://Store/Product/12345"`, Coveo indexes `12345` in the `product_id` field.
```json
"ExtendedMetadata": {
"product_id": { <1>
"Expression": {
"value": "%[id]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Replace",
"OldValue": "gid://shopify/Product/",
"NewValue": ""
}
]
}
}
```
<1> In the `product_id` field, Coveo will index the result of the rule in this object.
<2> `%[id]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `id` in your API response.
<3> Coveo will alter the metadata retrieved with `%[id]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": ""` or `"name_author": null`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
}
]
}
}
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
Let's say you want to index product title translations in the `product_title` field.
However, if a translation is missing, you want to index the product title in the default language instead.
The following rule retrieves the `title` value from the `localeTranslations` object in your API response.
If the translation is missing, Coveo indexes the product title in the default language in the `product_title` field.
```json
"ExtendedMetadata": {
"product_title": { <1>
"Expression": {
"value": "%[localeTranslations[?(@.key == 'title')].value]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "%[title]"
}
]
}
}
```
<1> In the `product_title` field, Coveo will index the result of the rule in this object.
<2> This query retrieves the metadata stored under `localeTranslations` in your API response and filters it to only return the `title` value.
<3> Coveo will alter the metadata retrieved with the query according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
The following rule replaces a missing metadata value with a default value.
So, if your API returns `"name_author": "None"` or `"name_author": "(Empty)"`, Coveo indexes `"Unknown author"` in the `author` field.
```json
"ExtendedMetadata": {
"author": { <1>
"Expression": {
"Value": "%[name_author]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "Default",
"DefaultValue": "Unknown author",
"FallbackValuesTrigger": [
"None", "(Empty)"
]
}
]
},
},
```
<1> In the `author` field, Coveo will index the result of the rule in this object.
<2> `%[name_author]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `name_author` in your API response.
<3> Coveo will alter the metadata retrieved with the `%[name_author]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
Details
You use the `FormatHierarchical` action because you're planning to add a [hierarchical facet](https://docs.coveo.com/en/2667/) to your Coveo-powered search interface.
This action reformats your metadata in the way that's required for the hierarchical facet to work properly.
Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
So, if your API returns `"category": "Men > Clothing > Shoes"`, Coveo indexes `Men;Men|Clothing;Men|Clothing|Shoes` in the `ec_categories` field.
Then, once you add a hierarchical facet based on the `ec_categories` field to your search interface, your search interface will allow users to filter results by selecting a category such as `Men`, and then a subcategory such as `Shoes`, and so on.
```json
"ExtendedMetadata": {
"ec_categories": { <1>
"Expression": {
"Value": "%[category]" <2>
},
"ExtendedMetadataActions": [ <3>
{
"ActionName": "FormatHierarchical",
"StringSeparator": " > " <4>
}
]
}
}
```
<1> In the `ec_categories` field, Coveo will index the result of the rule in this object.
<2> `%[category]` is a [dynamic value](https://docs.coveo.com/en/n7jg0349#dynamic-values) that retrieves the metadata stored under `category` in your API response.
<3> Coveo will alter the metadata retrieved with `%[category]` according to the rules specified in the [`ExtendedMetadataActions` array](#extendedmetadataactions-array).
<4> Thanks to the `StringSeparator` property, Coveo can identify the hierarchy levels in the metadata.
Details
With the following `IndexingAction` object, all items with an `id` greater than `5` are ignored.
Only items with an `id` of `5` or less are indexed.
```json
"IndexingAction": {
"ActionOnItem": "Ignore",
"Condition": "%[id] > 5"
}
```
Details
With the following `IndexingAction` object on an endpoint, all items that have a `name` metadata value other than `myvalue` are ignored.
The [`ProcessingAction`](#processingaction-object) object has the same condition.
As a result, a [child item](#subitems-array) of the ignored items is also ignored if its `name` metadata value is not `myvalue`.
```json
"IndexingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'" <1>
},
"ProcessingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'"
}
```
<1> As stated under [`Condition`](#action-condition-string), the metadata fields in your condition must either be defined in the [`Metadata` object](#metadata-object) or referenced with [`raw`](https://docs.coveo.com/en/n7jg0349#raw).
Details
Let's say you want to index store data, with full-time employee data as store subitems.
However, in your API, the employee data isn't directly linked to the store data.
Instead, it's linked to the store data through the department data.
Here's an example of the data structure as it would be returned by your API:
```text
Store 1
Department A
Employee 1
type: full time
Employee 2
type: full time
Department B
Employee 3
type: full time
Employee 4
type: part time
Employee 5
type: full time
Store 2
Department C
Employee 6
type: part time
Employee 7
type: full time
Employee 8
type: full time
Department D
Employee 9
type: full time
Department E
Employee 10
type: full time
Employee 11
type: full time
Employee 12
type: maternity leave
```
To index employee items, you need to retrieve the parent department items first.
However, since you want don't want to index the department data, you'll use the `IndexingAction` object to have Coveo ignore it.
As a result, Coveo will index employee items as subitems of the store items, even if they don't have a parent-child relationship in the API response.
Your source configuration is the following:
```json
{
"Services": [
{
"Url": "https://api.com",
"Endpoints": [
{
"Path": "/search",
"Method": "GET",
"Headers": {
"x-api-key": "@ApiKey",
"Accept": "application/json",
"Host": "api.com"
},
"QueryParameters": {
"type": "grocery"
},
"ItemType": "Store",
"Uri": "%[url]",
"ClickableUri": "%[url]",
"Title": "%[name]",
"ModifiedDate": "%[updatedAt]",
"Body": "%[address]",
"Metadata": {
"id": "%[id]"
},
"SubItems": [
{
"ItemPath": "departments",
"ItemType": "Department",
"Uri": "%[url]",
"ClickableUri": "%[url]",
"Title": "%[name]",
"ModifiedDate": "%[updatedAt]",
"IndexingAction": { <1>
"ActionOnItem": "Ignore"
},
"Body": "description",
"Metadata": {
"id": "%[id]"
},
"SubItems": [
{
"ItemPath": "employees",
"ItemType": "Employee",
"Uri": "%[url]",
"ClickableUri": "%[url]",
"Title": "%[name]",
"ModifiedDate": "%[updatedAt]",
"Body": "description",
"Metadata": {
"id": "%[id]",
},
"IndexingAction": { <2>
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.type]=='full time'" <3>
}
}
]
}
]
}
]
}
]
}
```
<1> This `IndexingAction` object is used to ignore `Department` items.
Since there's no condition, all `Department` items will be ignored.
<2> This `IndexingAction` object is used to index only the `Employee` items that have `full time` as their `type` metadata value.
`Employees` items with a different `type` value will be ignored.
<3> As stated under [`Condition`](#action-condition-string), the metadata fields in your condition must either be defined in the [`Metadata` object](#metadata-object) or referenced with [`raw`](https://docs.coveo.com/en/n7jg0349#raw).
Details
* `"%[node.author_id]"` is true if the item has an `author_id`.
* `"NOT %[node.author_id]"` is true if the item doesn't have an `author_id`.
* `"%[node.author_id] == 1234"` is true if the item `author_id` is `1234`.
* `"%[node.author_ids] == [1,2,3,4]"` is true if item `author_ids` are `1`, `2`, `3`, and `4`.
* `"%[node.author_id] OR %[author_name]"` is true if the item has an `author_id` or an `author_name`.
* `"%[node.author_id] AND %[author_name]"` is true if the item has an `author_id` and an `author_name`.
* `+"%[node.author_id] > 123"+` is true if the item `author_id` is greater than 123.
* `"(%[node.author_id] OR %[node.author_sys_id]) AND %[node.author_name]"` is true if the item has an `author_id` or an `author_name`, as well as an `author_name`.
Details
Most APIs return items or permissions as a series of objects such as:
```json
{
"allowed": [
{
"email": "jsmith@example.com"
},
{
"email": "ballen@example.com"
}
]
}
```
In such a case, you would use [`ItemPath`](#itempath-string) to extract permissions.
However, if your API rather returns items or permissions as strings in a JSON array, you should use `StringItemPath` instead.
```json
{
"allowed": ["jsmith@example.com", "ballen@example.com"]
}
```
[NOTE]
**Note**
Details
If your API's response looks like this:
```json
{
"count": 8,
"entries": [
{
"results": [
{ "id": 1, "name": "Caroline" },
{ "id": 2, "name": "Marcella" },
{ "id": 3, "name": "Susie" },
{ "id": 4, "name": "Rhonda" },
{ "id": 5, "name": "Wendy" },
{ "id": 6, "name": "Barbara Ann" },
{ "id": 7, "name": "Deirdre" },
{ "id": 8, "name": "Lynda" }
]
}
]
}
```
Then your source configuration should contain the following:
```
"ItemPath": "entries[0].results"
```
This tells Coveo to index the `results` array of the first `entries` object in the JSON response.
Details
If your API returns a response with a single item that looks like this:
```json
{
"id": 1,
"firstname": "Lloyd",
"lastname": "Sweeney",
"age": 26,
"address": {
"streetAddress": "6974 Rutrum Dr",
"city": "Ashburn",
"state": "VA",
"zip": "25581"
},
"email": "JWeakliem@lectus.org",
"username": "GHohmann",
"phone": "9556676434",
"created": "2023-09-12T05:29:48.688Z"
}
```
Then your source configuration could look like this:
```json
{
"Services": [
{
"Url": "http://example.com/api/v1",
"Endpoints": [
{
"Path": "/users/1",
"Method": "GET",
"ItemType": "User",
"Uri": "%[coveo_url]/users/%[id]",
"ClickableUri": "%[coveo_url]/users/%[id]",
"Title": "%[username]",
"ModifiedDate": "%[created]",
"Metadata": {
"id": "%[id]",
"title": "Mr.", <1>
"firstname": "%[firstname]",
"lastname": "%[lastname]",
"age": "%[age]",
"address": "%[address]", <2>
"email": "%[email]",
"phonenumber": "%[phone]"
}
}
]
}
]
}
```
<1> The `title` metadata is hardcoded to "Mr." for all items.
<2> In the configuration above, the `address` metadata contains the whole JSON object.
So, to flatten the metadata, you could also write the following `Metadata` object:
```json
{
"Metadata": {
"id": "%[id]",
"firstname": "%[firstname]",
"lastname": "%[lastname]",
"age": "%[age]",
"address.street": "%[address.streetAddress]",
"address.city": "%[address.city]",
"address.state": "%[address.state]",
"address.zip": "%[address.zip]",
"email": "%[email]",
"phonenumber": "%[phone]"
}
}
```
Details
```json
"PayloadParameters": {
"type": "post",
"expand": "true",
"id": 120
}
```
Details
If your API requires Coveo to authenticate with an API key as the value of the `api_key` payload parameter, you must enter this key in the [**Authentication** section](https://docs.coveo.com/en/n6gh2329#authentication-section) of the **Add a GraphQL API source** panel.
Then, in your source JSON configuration, you must use the `@ApiKey` placeholder to refer to this key.
This ensures that your API key is [encrypted](https://docs.coveo.com/en/1663#source-credentials) rather than stored in clear text in the source JSON configuration, where other Administration Console users could access it.
When Coveo processes the source configuration, it replaces the placeholder with the actual key you entered in the panel.
Your source configuration could therefore look like this.
```json
{
"Services": [
{
"Url": "http://example.com/api/v1",
"Endpoints": [
{
"Path": "/users",
"Method": "POST",
"ItemType": "User",
"Uri": "%[coveo_url]/users/%[id]",
"ClickableUri": "%[coveo_url]/users/%[id]",
"PayloadParameters": {
"api_key": "@ApiKey" <1>
}
}
]
}
]
}
```
<1> `api_key` is the name of the payload parameter that your API expects to contain the API key.
As a result, Coveo sends the following HTTP request to the API:
```http
POST /users HTTP/1.1
Host: http://example.com/api/v1
api_key=Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM <1>
```
<1> `Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM` is the API key you entered in the source panel.
Details
You want to pass the following GraphQL query as a payload parameter:
```graphql
query {
user(login:"jsmith") {
pullRequests(first:@pageSize, after:@offset) {
totalCount
edges {
node {
createdAt
title
url
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
When entering this query in the [**GraphQL queries** section](https://docs.coveo.com/en/n6gh2329/), you name it `@MyFirstQuery`.
Your source JSON configuration therefore contains the following:
```json
"PayloadParameters": {
"query": "@MyFirstQuery"
}
```
Details
```json
"ProcessingAction": {
"ActionOnItem": "Ignore",
"Condition": "%[id]==1"
}
```
Details
With the following `IndexingAction` object on an endpoint, all items that have a `name` metadata value other than `myvalue` are ignored.
The [`ProcessingAction`](#processingaction-object) object has the same condition.
As a result, a [child item](#subitems-array) of the ignored items is also ignored if its `name` metadata value is not `myvalue`.
```json
"IndexingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'" <1>
},
"ProcessingAction": {
"ActionOnItem": "Ignore",
"Condition": "NOT %[raw.name]=='myvalue'"
}
```
<1> As stated under [`Condition`](#action-condition-string), the metadata fields in your condition must either be defined in the [`Metadata` object](#metadata-object) or referenced with [`raw`](https://docs.coveo.com/en/n7jg0349#raw).
Details
```json
"QueryParameters": {
"type": "post",
"expand": "true",
"id": 120
}
```
Details
```json
"QueryParameters": {
"since": "@Now-6M",
"until": "@Now"
}
```
Details
If your API requires Coveo to authenticate with an API key as the value of the `api_key` query parameter, you must enter this key in the [**Authentication** section](https://docs.coveo.com/en/n6gh2329#authentication-section) of the **Add a GraphQL API source** panel.
Then, in your source JSON configuration, you must use the `@ApiKey` placeholder to refer to this key.
This ensures that your API key is [encrypted](https://docs.coveo.com/en/1663#source-credentials) rather than stored in clear text in the source JSON configuration, where other Administration Console users could see it.
When Coveo processes the source configuration, it replaces the placeholder with the actual key you entered in the panel.
Your source configuration could therefore look like this.
```json
{
"Services": [
{
"Url": "http://example.com/api/v1",
"Endpoints": [
{
"Path": "/users",
"Method": "GET",
"ItemType": "User",
"Uri": "%[coveo_url]/users/%[id]",
"ClickableUri": "%[coveo_url]/users/%[id]",
"QueryParameters": {
"api_key": "@ApiKey" <1>
}
}
]
}
]
}
```
<1> `api_key` is the name of the query parameter that your API expects to contain the API key.
As a result, Coveo sends the following HTTP request to the API:
```http
GET /users?api_key=Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM HTTP/1.1
Host: http://example.com/api/v1
```
`Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM` is the API key you entered in the source panel.
Details
You want to pass the following GraphQL query as a query parameter:
```graphql
query {
user(login:"jsmith") {
pullRequests(first:@pageSize, after:@offset) {
totalCount
edges {
node {
createdAt
title
url
}
cursor
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
```
When entering this query in the [**GraphQL queries** section](https://docs.coveo.com/en/n6gh2329/), you name it `@MyFirstQuery`.
Your source JSON configuration therefore contains the following:
```json
"QueryParameters": {
"query": "@MyFirstQuery"
}
```
Details
When refreshing your source, Coveo indexes only the published items that have been updated since the last refresh operation, as instructed by the following `RefreshEndpoints` array.
Since no other property is specified, Coveo will index these items exactly like during the initial indexing operation.
```json
"Endpoints": [
{
"Path": "/api/now/table/kb_knowledge",
"Method": "GET",
"ItemPath": "result",
"ItemType": "kbknowledge",
"Uri": "%[coveo_url]/kb_knowledge/%[sys_id]",
"PermanentId": "%[sys_id]",
"ModifiedDate": "%[sys_updated_on]",
"ClickableUri": "%[coveo_url]/nav_to.do?uri=kb_knowledge.do?sys_id=%[sys_id]%26sysparam_view-ess",
"Title": "%[short_description]",
"Body": "%[text]",
"QueryParameters": {
"sysparm_query": "workflow_state=published"
},
"Metadata": {
"short_description": "%[short_description]",
"number": "%[number]",
"workflow_state": "%[workflow_state]",
},
"RefreshEndpoints": [
{
"DateFormat": "\'yyyy-MM-dd\',\'hh:mm:ss\'", <1>
"QueryParameters": {
"sysparm_query": "workflow_state=published^sys_updated_on>javascript:gs.dateGenerate(@RefreshDate)"
}
}
]
}
]
```
<1> The [`DateFormat`](#dateformat-string) property specifies the format of the date value in the query parameters.
Details
Most APIs return items or permissions as a series of objects such as:
```json
{
"allowed": [
{
"email": "jsmith@example.com"
},
{
"email": "ballen@example.com"
}
]
}
```
In such a case, you would use [`ItemPath`](#itempath-string) to extract permissions.
However, if your API rather returns items or permissions as strings in a JSON array, you should use `StringItemPath` instead.
```json
{
"allowed": ["jsmith@example.com", "ballen@example.com"]
}
```
[NOTE]
**Note**
Details
If you expect your API to return items or permissions in an array such as:
```json
{
"users": ["jsmith@example.com", "ballen@example.com"]
}
```
Your source configuration should contain `"StringItemPath": "users"`.
In a permission subquery, to [index](https://docs.coveo.com/en/204/) the extracted user identities under [`Name`](#member-name-string-required), also add: `"Name": %[item]`.
Your permission subquery therefore looks as follows:
```json
"permissionSubQueries": [
{
"StringItemPath": "users",
"Path": "item/location",
"Method": "GET",
"Name": "%[item]",
"Type": "User",
"IsAllowedMember": true
}
]
```
Details
* `"%[node.author_id]"` is true if the item has an `author_id`.
* `"NOT %[node.author_id]"` is true if the item doesn't have an `author_id`.
* `"%[node.author_id] == 1234"` is true if the item `author_id` is `1234`.
* `"%[node.author_ids] == [1,2,3,4]"` is true if item `author_ids` are `1`, `2`, `3`, and `4`.
* `"%[node.author_id] OR %[author_name]"` is true if the item has an `author_id` or an `author_name`.
* `"%[node.author_id] AND %[author_name]"` is true if the item has an `author_id` and an `author_name`.
* `+"%[node.author_id] > 123"+` is true if the item `author_id` is greater than 123.
* `"(%[node.author_id] OR %[node.author_sys_id]) AND %[node.author_name]"` is true if the item has an `author_id` or an `author_name`, as well as an `author_name`.
Details
If your API uses API keys for authentication, Coveo will typically need to provide such a key in an [HTTP header](#headers-object), as a [query parameter](#queryparameters-object), or as a [payload parameter](#payloadparameters-object).
You therefore don't need an `Authentication` object in your JSON configuration.
Details
If your API uses password-based authentication, you must enter the username and password in the [**Authentication** section](https://docs.coveo.com/en/n6gh2329#authentication-section) of the **Add a GraphQL API source** panel.
Then, in your JSON configuration, you must use the `@Username` and `@Password` placeholders to refer to these credentials.
Your `Authentication` object therefore looks like this:
```json
"Authentication": {
"Username": "@Username",
"Password": "@Password",
"ForceBasicAuthentication": "true"
}
```
Details
If your API uses OAuth 2.0 authentication, you must enter the client ID, client secret, and refresh token in the [**Authentication** section](https://docs.coveo.com/en/n6gh2329#authentication-section) of the **Add a GraphQL API source** panel.
Then, in your JSON configuration, you must use the `@ClientId`, `@ClientSecret`, and `@RefreshToken` placeholders to refer to this information.
Your `Authentication` object could therefore look like this:
```json
"Authentication": {
"OAuth": {
"Query": {
"RefreshUrl": "http://example.com/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
}
}
}
}
}
```
Details
```json
"Query": {
"RefreshUrl": "http://example.com/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
}
}
}
```
Details
```json
"Query": {
"RefreshUrl": "http://example.com/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
}
}
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
If the authentication server's response looks like this:
```
HTTP/1.1 200 OK
Content-Type: application/json
```
```json
{
"access_token": "jOs0PoLKm61sd6h49",
"refresh_token": "QpMas-tuI9bvFp01-Xxpl04gC_0m",
"token_type": "bearer",
"expires_in": 86400
}
```
Then your `Response` object should look like this:
```json
"Response": {
"AccessToken": "access_token",
"SupportsRefreshToken" : "true",
"RefreshToken": "refresh_token",
"ExpiresIn": "expires_in",
"TokenType": "token_type"
}
```
Details
```json
"Authentication": {
"OAuth": {
"UsingSingleUseRefreshToken": true,
"Query": {
"RefreshUrl": "https://auth.example.com/oauth/token",
"Method": "POST",
"Parameters": {
"grant_type": {
"Type": "Payload",
"Value": "refresh_token"
},
"client_id": {
"Type": "Payload",
"Value": "@ClientId"
},
"client_secret": {
"Type": "Payload",
"Value": "@ClientSecret"
},
"refresh_token": {
"Type": "Payload",
"Value": "@RefreshToken",
"IsRefreshToken": true
}
}
}
}
}
```
Details
```json
"Headers": {
"accept": "application/vnd.github.v3+json",
"User-Agent": "PostmanRuntime/7.29.0"
}
```
Details
If your API requires Coveo to authenticate with an API key in the `Authorization` HTTP header, you must enter this key in the [**Authentication** section](https://docs.coveo.com/en/n6gh2329#authentication-section) of the **Add a GraphQL API source** panel.
Then, in your source JSON configuration, you must use the `@ApiKey` placeholder to refer to this key.
This ensures that your API key is [encrypted](https://docs.coveo.com/en/1663#source-credentials) rather than stored in clear text in the source JSON configuration, where other Administration Console users could access it.
When Coveo processes the source configuration, it replaces the placeholder with the actual key you entered in the panel.
Your source configuration could therefore look like this.
```json
{
"Services": [
{
"Url": "http://example.com/api/v1",
"Headers": {
"Authorization": "Bearer @ApiKey" <1>
},
"Endpoints": [
{
"Path": "/users",
"Method": "GET",
"ItemType": "User",
"Uri": "%[coveo_url]/users/%[id]",
"ClickableUri": "%[coveo_url]/users/%[id]"
}
]
}
]
}
```
<1> `Bearer` is the authorization type and is most commonly used with OAuth 2.0 tokens.
If your API requires a different authorization type, replace `Bearer` with the appropriate type.
As a result, Coveo sends the following HTTP request to the API:
```http
GET /users HTTP/1.1
Host: http://example.com/api/v1
Authorization: Bearer Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM <1>
```
<1> `Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM` is the API key you entered in the source panel.
Details
If your API requires Coveo to authenticate with an API key in the custom HTTP header `X-Api-Key`, you must enter this key in the [**Authentication** section](https://docs.coveo.com/en/n6gh2329#authentication-section) of the **Add a GraphQL API source** panel.
Then, in your source JSON configuration, you use the `@ApiKey` placeholder to refer to this key.
This ensures that your API key is [encrypted](https://docs.coveo.com/en/1663#source-credentials) rather than stored in clear text in the source JSON configuration, where other Administration Console users could access it.
When Coveo processes the source configuration, it replaces the placeholder with the actual key you entered in the panel.
Your source configuration could therefore look like this.
```json
{
"Services": [
{
"Url": "http://example.com/api/v1",
"Headers": {
"X-Api-Key": "@ApiKey" <1>
},
"Endpoints": [
{
"Path": "/users",
"Method": "GET",
"ItemType": "User",
"Uri": "%[coveo_url]/users/%[id]",
"ClickableUri": "%[coveo_url]/users/%[id]"
}
]
}
]
}
```
<1> `X-Api-Key` is the name of the custom header that your API expects to contain the API key.
As a result, Coveo sends the following HTTP request to the API:
```http
GET /users HTTP/1.1
Host: http://example.com/api/v1
X-Api-Key: Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM <1>
```
<1> `Az4adfSyBhZX8fTThUJ4Kb2TC3Ax0RshgrZtUiqM` is the API key you entered in the source panel.
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=100&pageNumber=0+` for the first page, and `+http://example.com/api/item?limit=100&pageNumber=1+` for the second page.
With these URLs, Coveo would request the first page (page 0), and then increment the page number by 1 to request the second page, and so on.
In this case, your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 100,
"OffsetStart": 0,
"OffsetType": "page",
"Parameters": {
"Limit": "limit",
"Offset": "pageNumber"
}
}
}
```
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=100&start=0+` for the first page, and `+http://example.com/api/item?limit=100&start=100+` for the second page.
With these URLs, Coveo would request the 100 first items starting from item 0, and then the 100 next items, starting from item 100.
In this case, your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 100,
"OffsetStart": 0,
"OffsetType": "item",
"Parameters": {
"Limit": "limit",
"Offset": "start"
}
}
}
```
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=8+` for the first page, and `+http://example.com/api/item?page=3d170d80d8n3n2342c328s+` for the second page.
In this context, Coveo would request the first page, and then the next page using the URL provided in the `nextPage` value in the JSON response.
In this case, if your API returns the following first page:
```json
{
"nextPage": "http://example.com/api/item?page=3d170d80d8n3n2342c328s",
"items": [
{ "id": 1, "name": "Caroline" },
{ "id": 2, "name": "Marcella" },
{ "id": 3, "name": "Susie" },
{ "id": 4, "name": "Rhonda" },
{ "id": 5, "name": "Wendy" },
{ "id": 6, "name": "Barbara" },
{ "id": 7, "name": "Deirdre" },
{ "id": 8, "name": "Lynda" }
]
}
```
Then your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 8,
"NextPageKey": "nextPage",
"OffsetType": "url",
"Parameters": {
"Limit": "limit"
}
}
}
```
Details
Your API expects request URLs in a format such as `+http://example.com/api/item?limit=8+` for the first page, and `+http://example.com/api/item?limit=8&nextPageToken=3d170d80-7b3b-4377+` for the second page.
With these URLs, Coveo would request the 8 first items, and then the next page using the token provided in the `NextPageId` value in the JSON response.
In this case, if your API returns the following first page:
```json
{
"nextPageId": "3d170d80-7b3b-4377",
"items": [
{ "id": 1, "name": "Caroline" },
{ "id": 2, "name": "Marcella" },
{ "id": 3, "name": "Susie" },
{ "id": 4, "name": "Rhonda" },
{ "id": 5, "name": "Wendy" },
{ "id": 6, "name": "Barbara" },
{ "id": 7, "name": "Deirdre" },
{ "id": 8, "name": "Lynda" }
]
}
```
Then your `Paging` object should look like this:
```json
{
"Paging": {
"PageSize": 8,
"NextPageKey": "NextPageId",
"OffsetType": "cursor",
"Parameters": {
"Limit": "limit",
"Offset": "nextPageToken"
}
}
}
```
Details
Your source configuration contains the following `Permissions` object, which indicates that members of the Support Agents group should be allowed to access the indexed content:
```json
"Permissions": [
{
"Name": "Permission Level 1",
"PermissionsSets": [
{
"Name": "Permission Set 1",
"AllowedMembers": [
{
"Name": "Support Agents",
"Type": "Group",
"PermissionType": "MyPermissionType2",
"AdditionalInfo": {
"group_id": "00841"
}
}
],
}
]
}
]
```
To extract the members of this group, you provide the following permission configuration.
Therefore, the security identity provider will use the `group_id` you specified in the source configuration to make an API request and obtain the group members.
Then, the security provider will refer to the `user` instructions to retrieve the desired information on the extracted group members.
```json
"identities": {
"group": {
"permissionSubQueries": [
{
"path": "/group/%[coveo_parent.group_id]/members",
"method": "GET",
"itemPath": "members",
"permissionType": "user",
"name": "%[username]",
"type": "User",
"additionalInfo": {
"user_id": "%[user_id]"
}
}
]
},
"user": {
"permissionSubQueries": [
{
"path": "/users/%[user_id]",
"method": "GET",
"itemPath": "user",
"name": "%[email]",
"type": "User"
}
]
}
}
```