GraphQL API source reference

Each array in the Endpoints object details how you want Coveo to crawl an endpoint of your web application. See the Endpoint section for details on the items found in an array.

The Url value is the GraphQL service URL of the web application of which you want to make the content searchable.

Example: "Url": "https://api.github.com/"

If your web application service requires authentication, this object contains the GraphQL service authentication configuration. See the Authentication section for details on the properties in this object.

You must also enter authentication information in the Authentication section of the Add/Edit a GraphQL API Source panel.

Then:

A key-value list of HTTP headers to add to the query. Each value can be either a number, string, or Boolean.

This property is inheritable.

Example:

In the Paging object, you can specify how you want the Services content to be paged.

See the Paging section for details on the properties in this object.

The Permissions array is required when you select the Same users and groups as in your content system source content security option. It contains the permission levels and sets to apply to the items indexed through this service. The members listed in these levels and sets are either allowed or denied access to the indexed items.

This property is inheritable.

See the Permission Level object section for details on the properties in this object.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

When crawling your content, Coveo may encounter an HTTP error and stop. If you expect the web application API to return an error and want it to be ignored so that the crawling process continues, specify the error code as the SkippableErrorCodes property value.

This property applies at the Services level and is inheritable.

Use a semicolon (;) to separate error codes.

Example: "SkippableErrorCodes": "500;404;403"

The format of the item clickable URI.

Dynamic values are supported.

Example: "ClickableUri": "%[node.url]"

The type of item that the resource contains. Coveo uses this data to organize the indexed content.

Examples:

The relative path to the desired resource endpoint.

Dynamic values are supported when specified within the SubItems, SubQueries, and PermissionSubQueries arrays only.

Dynamic time expressions are also supported.

Example: "Path": "graphql"

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, i.e., the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

The format of the item unique identifier.

Dynamic values are supported.

Example: "Uri": "%[node.url]"

Should a dynamic value be invalid or unretrievable, the source stops crawling and displays an error in the Administration Console.

The path (simple path or JSONPath) to the Body content of the item in the JSON response. The item body is displayed in the Administration Console Content Browser.

Typically, the Body property contains a dynamic value, since a static, hardcoded value would make all item bodies identical. Dynamic values and hardcoded text can also be mixed.

Example: "Body": "%[html.content]"

The format of a date injected thanks to the tokens @Now and @RefreshDate.

All .NET formats are supported, and the default is yyyy-MM-ddTHH:mm:ssZ (ISO 8601).

Alternatively, to handle Unix timestamps, enter either of the following:

Examples:

Whether to ignore or to retrieve an item if the specified Condition resolves to true. See the Action object section for details on the properties expected in the IndexingAction object.

When the specified Condition resolves to true, the Coveo crawler applies the specified action to the corresponding item. Possible actions are Retrieve and Ignore, i.e., the crawler can either index the item to make it searchable or ignore it.

An item ignored with IndexingAction isn’t indexed and therefore not visible in the Administration Console Content Browser or a search interface. However, its sub-items are sent to the index, unless otherwise specified in the ProcessingAction object.

If the condition resolves to false, the Coveo crawler falls back to the default action, which is Retrieve, and the specified item is indexed.

Example:

Whether the subquery retrieves binary content as the body of the item. Default value is false.

This property is available within SubQueries objects only. It allows you to download a file (e.g., XLS or PDF document) to use as the item body in a search result quick view. See Supported file formats for an exhaustive list of item types that Coveo can index.

If you set IsBinaryBody to true, ensure that your API key is valid for subqueries.

Example:

The path to the item in the JSON response returned by the application.

When ItemPath is omitted, Coveo assumes that the item is at the root level of the JSON response. See the Collection of items example.

A key-value list of the metadata to parse. Each key represents the metadata name of the repository item, while its value is the value path (simple path or JSONPath) in the JSON response.

Typically, the value path consists of one or more dynamic values, since a static, hardcoded value would result in an identical piece of metadata for all items. However, you could choose to use a hardcoded value so that the corresponding Coveo field is filled even if the API doesn’t provide this information.

Example:

When you build your source, Coveo retrieves the desired metadata. You can then review a sample of this metadata in the Administration Console and use it to create mapping rules for your source.

The HTTP method to use to fetch the resource.

Possible values are GET and POST. Default value is GET.

This property is not inheritable.

See the API documentation of your application to determine which one you should use.

Example: "Method": "POST"

The date on which the item was last modified. Although this property isn’t required in the JSON configuration, we recommend that you include it, as the Coveo-powered search pages use it for their default Sort by Date option.

Typically, ModifiedDate has a dynamic value, since a static, hardcoded value would make dates identical for all items.

Example: "ModifiedDate": "%[updated]"

In the Paging object, you can specify how you want the Endpoint content to be paged.

See the Paging section for details on the properties in this object.

The JSON content to send as a POST request body. The Content-Type header is automatically set to application/json.

Dynamic values are supported when specified within the SubItems and SubQueries objects only.

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, i.e., the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

A key-value list of HTTP parameters to add to the payload. Each value can be either a number, string, or Boolean.

This property can only be used in a POST request. The parameters are sent as URL-encoded data in the request body. The Content-Type header is automatically set to application/x-www-form-urlencoded.

Dynamic values are supported when specified within the SubItems and SubQueries objects only.

Dynamic time expressions are also supported.

Example:

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, i.e., the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

The PermanentId is an alternative, permanent unique item identifier.

When you expect the item Uri to change, this ensures that Coveo Machine Learning (Coveo ML) recognizes the items despite their new URI and associates them to the old data. So, in the future, if you modify or delete this source and reindex the same items, specifying the same item PermanentId format in your next configuration will ensure that Machine Learning doesn’t consider your items as new and rather picks up where it left off.

Dynamic values are supported.

Example:

The Permissions object is required when you select the Same users and groups as in your content system source content security option. It contains the permission levels and sets to apply to the items indexed in this endpoint. The members listed in these levels and sets are either allowed or denied access to the indexed items.

This property is inheritable.

See the Permission Level object section for details on the properties in this object.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

Whether to ignore or to retrieve the child items of an item if the specified Condition resolves to true. See the Action object section for details on the properties expected in the ProcessingAction object.

When the specified Condition resolves to true, the Coveo crawler applies the specified action on the corresponding child items of an item. Possible actions are Process and Ignore, i.e., the crawler can either retrieve the subitems to make them searchable or ignore them.

A child item ignored with ProcessingAction isn’t indexed and therefore not visible in the Administration Console Content Browser or a search interface.

If the condition resolves to false, it fallbacks to the default action, i.e., Process.

Example:

A key-value list of HTTP parameters to add to the query. Each value can be either a number, string, or Boolean.

Dynamic values are supported when specified within the SubItems, SubQueries, and PermissionSubQueries arrays only. They aren’t supported in QueryParameters objects within a RefreshEndpoints object.

Dynamic time expressions are also supported.

Example:

Example:

In sub-items and subqueries, should a dynamic value be invalid or unretrievable, the source skips the item, i.e., the indexing process is dropped and Coveo moves on to the next item. In a permission subquery, however, an invalid or unretrievable dynamic value causes the source to stop crawling and to display an error in the Administration Console.

A list of refresh endpoint queries to execute to retrieve added, updated, or deleted items when refresh is supported and performed. See the Refresh endpoints section for details on the properties in this object.

When crawling your content, Coveo may encounter an HTTP error and stop. If you expect the web application API to return an error and want it to be ignored so that the crawling process continues, specify the error code as the SkippableErrorCodes property value.

This property applies at the Endpoints level and is inheritable.

Use a semicolon (;) to separate error codes.

Example: "SkippableErrorCodes": "500;404;403"

A list of sub-items to retrieve. Each sub-item is represented by a configuration object under Endpoints.

An item can have many different sub-items, e.g., a blog post containing comments and attachments as child items. The SubItems object establishes a parent-child relationship between items. There’s no restriction on the number of sub-items an item can have.

In addition, sub-items can also have sub-items, for example if blog post comments also have attachments. In the application JSON response, these sub-items are nested within each other, and so should be your SubItems arrays in your source configuration.

To refer to the metadata of a parent item, prefix the metadata name with coveo_parent. You may also need to use raw.

Examples:

When the sub-items to index are located under a different endpoint, you provide the Path to their location.

Alternatively, when the desired sub-items are located under the same endpoint as their parent items (e.g., the child item data is nested within the parent item data), you omit the Path property and provide the sub-items' location using the ItemPath property.

A list of subqueries to execute on every item in order to fetch additional metadata and/or the item body, especially if this information is located under a different path than that of the item. See the Subquery object section for details.

To refer to the metadata of a parent item, prefix the metadata name with coveo_parent. You may also need to use raw.

The title of the item. Although this property isn’t required in the JSON configuration, we recommend that you include it, as the Administration Console Content Browser displays its value.

Typically, Title contains a dynamic value, since a static, hardcoded value would make all item titles identical.

Example: "Title": "%[node.title]"

Action to perform if the specified Condition resolves to true.

In the IndexingAction object, this applies to retrieved items. Possible actions are Retrieve and Ignore, i.e., the crawler can either index the item to make it searchable or ignore it.

In the ProcessingAction object, this applies to child items of an item. Possible actions are Process and Ignore, i.e., the crawler can either retrieve the subitems to make them searchable or ignore them.

The Condition value is a condition that must resolve to true for the specified action to apply to the child items of an item.

To write your condition, use the same syntax as for indexing pipeline extension conditions. Conditions can be assembled together using the following operators: AND, OR, Exists, NOT, >, and <. Parentheses are also supported to specify operation order.

The metadata fields in your condition must either be defined in the Metadata object or referenced with raw. You can specify an array if the metadata refers to a multi-value field in your repository.

Examples:

The type of information on which the offset is based. Possible values are page, item, url, and cursor.

The number of items to fetch per page.

Example: With paging URL https://example.com/api/item?position=0&quantity=50, your JSON configuration should include "PageSize": 50.

When the OffsetType value is "url" or "cursor", provide the path (simple path or JSONPath) to the key representing the value of the next page reference, i.e., either the next page URL or the next page cursor.

The NextPageKey property isn’t required when the OffsetType value is page or item.

Example: "NextPageKey": "NextPageLink"

Offset of the first page to fetch. This property is required when the OffsetType value is "page" or "item".

Example: Your first paging URL is https://example.com/api/item?position=0&quantity=50. If you want to retrieve all items except items 1 to 50, your paging configuration must include "OffsetStart": 1.

The name of an HTTP header whose value represents the total number of items retrieved through the API call. This property is useful when Coveo makes an API call to a page that doesn’t exist, causing an error to be returned.

However, when using this property, you must be sure that the total always matches the actual number of items returned by your API, as Coveo’s crawler uses this total as an indication to stop. Should the expected total be lower than the actual number of items returned, Coveo won’t index the remaining items.

Therefore, if your API supports it, we recommend using the FetchNextPageUntilNoResult property instead, as a safer alternative.

Example: "TotalCountHeaderKey": "x-total-count"

The path (simple path or JSONPath) to a response body property representing the total number of items retrieved through the API call. This property is useful when Coveo makes an API call to a page that doesn’t exist, causing an error to be returned.

However, when using this property, you must be sure that the total always matches the actual number of items returned by your API, as Coveo’s crawler uses this total as an indication to stop. Should the expected total be lower than the actual number of items returned, Coveo won’t index the remaining items.

Therefore, if your API supports it, we recommend using the FetchNextPageUntilNoResult property instead, as a safer alternative.

Example: "TotalCountKey": "retrievedContent.totalCount"

The name of the permission level.

The PermissionsSets array specifies who can or can’t access the indexed items.

See the Permission Set object section for details on the properties expected for each element in this array.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

The Name property indicates the name of the permission set.

Each object in the AllowedMembers and DeniedMembers arrays represents a member security identity that should be allowed or denied to access the indexed content.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

The following is an example of a simple situation where, in your permission system, security identities are identified with email addresses. Your source will work with the Email security identity provider to ensure that your search interface users only see the content they’re allowed to.

If your permission system is more complex, requires a security provider other than Email, or is frequently updated, you should not only index allowed and denied security identities, but also provide a permission configuration instructing Coveo on how to index your permission system.

The IsAnonymousAllowed property indicates whether anonymous, i.e., non authenticated users are allowed to access the retrieved items. Default value is false.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

This array is relevant only when you provide a permission configuration.

The PermissionsFromMetadata array is an alternative to the PermissionSubQueries array, as it fetches permission data, typically the security identities that are allowed or denied access to the item. This data is crucial to retrieve if you want to replicate the application’s permission system in Coveo.

Include a PermissionsFromMetadata array in your GraphQL API source configuration when the permission data appears in the metadata of an item. Conversely, a PermissionSubQueries array should be used when an item and its permission data must be retrieved with two different queries.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

Objects of the PermissionsFromMetadata array support:

This array is relevant only when you provide a permission configuration.

Each object in the PermissionSubQueries array represents a subquery to execute on every item to fetch permission data, typically the security identities that are allowed or denied access to the item. This data is crucial to retrieve if you want to replicate the application’s permission system in Coveo.

The PermissionSubQueries array is an alternative to the PermissionsFromMetadata array.

Include a PermissionSubQueries array in your source configuration when an item and its permission data must be retrieved with two different queries. Conversely, the PermissionsFromMetadata array should be used when the permission data appears in the metadata of an item.

For more information on sources that index permissions and on how Coveo handles these permissions, see Coveo management of security identities and item permissions.

Objects of the PermissionSubQueries array support:

Example:

Whether the defined query returns items to delete from the index. Default value is false, which means that all retrieved items are added to the index or updated. If the query returns items to add, update, and delete all at once, use the IsDeletedItem property instead.

When a refresh query returns items to add, update, and delete all at once, this property allows you to specify which of these items should be deleted. Default value is false, but it’s considered to be true if IsDeletionQuery is set to true.

You can provide a dynamic value (e.g., %[has_been_deleted_flag]) to be evaluated for each item or a static value.

Example:

"%[is_deleted]" deletes all items that have a "is_deleted": true JSON property flagging them as deleted.

Whether to delete children when the retrieved parent item is deleted. Default value is false. If the value is set to true, child items are deleted based on their Uri.

If the SubQueries object path leads to an image, set IsThumbnail to true to show this image as the thumbnail of an item.

The default value is false.

Supported thumbnail file formats are the following: .bmp, .emf, .exif, .gif, .icon, .jpeg, .png, .tiff, .wmf .

Username used to log in to the GraphQL service. You can use @Username to retrieve the value specified in the Add a GraphQL API Source panel.

Password used to log in to the GraphQL service. This property can be empty even though a Username is specified. You can use @Password to retrieve the value specified in the Add a GraphQL API Source panel.

Domain name to use when authenticating to a NTLM or Kerberos protected server.

Whether to force a basic HTTP header in the request. The default value is false.

If the application to make searchable requires OAuth 2.0 authentication, the OAuth object must contain the required configuration. You can use the @ syntax to map the credentials or API key you specified in the Add a GraphQL API Source panel.

See the OAuth 2.0 section for details on the object properties.

Example:

The Query object represents the OAuth 2.0 refresh query configuration. See OAuth 2.0 Query for the properties expected in this object.

Enter your credentials in the Add a GraphQL API Source panel and use the @ClientId, @ClientSecret, and @RefreshToken placeholders in your JSON configuration.

The Response object represents the OAuth 2.0 refresh query configuration. See OAuth 2.0 Response for the properties expected in this object.

The OAuth 2.0 refresh URL.

Example: "RefreshUrl": "http://example.com/token"

The additional HTTP headers to use to authenticate the client and refresh the token.

Example:

The HTTP method to use to refresh the OAuth 2.0 token. Default is POST.

The parameters to use to authenticate the client and refresh the token. Possible values are query or payload.

If the OAuth 2.0 flow to use doesn’t support refresh tokens, don’t specify it in the Query object parameters.

Enter your credentials in the Add a GraphQL API Source panel and use the @ClientId, @ClientSecret, and @RefreshToken placeholders in your JSON configuration.

Example:

The path to the access token in the response. Default is access_token.

Whether the OAuth 2.0 flow supports refresh tokens. Default is true.

The path to the refresh token in the response. Default is refresh_token.

The path to the expiration time in the response. Default is expires_in. If there’s no expiration time in the response, use the ExpiresInDefaultValue property.

Specify an expiration value in seconds for the refresh token as an alternative to the ExpiresIn property. Default is 3600.

The path to the token type in the response. Default is token_type.

If the TokenType isn’t specified in the response or if it’s invalid or inappropriate, it defaults to Bearer. If you want a different default value, use the TokenTypeDefaultValue property.

If the TokenType isn’t specified in the response or if it’s invalid or inappropriate, it defaults to Bearer. Should you not want to use Bearer as a replacement for the inadequate token_type value that the response returns, specify the desired value.

Specify the name of the authorization header where the access token should appear. Default is Authorization.

Example: