Skip to end of metadata
Go to start of metadata

The Push API allows you to push items and their associated permissions to a Coveo Cloud V2 index, rather than pulling content using standard Coveo connectors and crawlers (see Using the Push API).

This is especially useful when you need to index content from a cloud or on-premises system for which the Coveo Cloud V2 platform offers no source type.

This topic provides reference information describing the available Coveo Cloud V2 Push API calls.

Additional Push API resources

 

All Push API calls must include the following HTTP headers:

KeyValue

Authorization

Bearer <a_valid_API_key>

Tip

Icon

When you create a Push source through the Coveo Cloud V2 administration console to, you can select the Create an API key check box to easily get an API key authorized to push content to sources.

Content-Typeapplication/json

Source Resource

Exposes a service to modify the status of a Coveo Cloud V2 Push source, effectively creating source activities.

Activities are used to group item operations performed on a given source. The Coveo Cloud V2 administration console uses activity data to provide statistics and information about the inner workings of a source.

Set source status

Sets the current status of a Coveo Cloud V2 Push source. This allows you to update the activity logs of the Push source (and consequently, the activity indicators in the Coveo Cloud V2 administration console).

Pushing an "active" source status (REBUILD, REFRESH, or INCREMENTAL) creates an activity. Pushing the IDLE status terminates the ongoing activity and marks it as completed.

Best practice

Icon

 Before adding, updating, or deleting items in a Push source, you should set its status to either REBUILDREFRESH, or INCREMENTAL, depending on the scale of the update. You should then set its status back to IDLE when the update process is over.

Command

Parameters

ParameterInTypeDescriptionSample value

organizationId

Pathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid

sourceId

Pathstring

Required.

The unique identifier of the Coveo Cloud V2 Push source.

myorganizationid-veta6vcbq5onxgj5nsiiaske5e

statusType

Querystring (enum)

Required.

The status to set the Push source to.

Valid values:

  • REBUILD

  • REFRESH

  • INCREMENTAL

  • IDLE

Those values are case insensitive.

REBUILD

Response codes

CodeDescription

201

Success - An activity of the specified type has been started.

401

Unauthorized - The supplied authorization token is invalid or does not allow access to the required resource.

429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too much time to execute.

Document Resource

Exposes services to add, update, and/or delete items in a Coveo Cloud V2 Push source.

Add or update single item

Adds or updates a single item and/or its related permissions in a Coveo Cloud V2 Push source (see Pushing Items to a Source).

Command

 

Parameters

ParameterInTypeDescriptionSample value

organizationId

Pathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid

sourceId

Pathstring

Required.

The unique identifier of the Coveo Cloud V2 Push source.

myorganizationid-veta6vcbq5onxgj5nsiiaske5e

documentId

Querystring

Required.

The unique identifier of the item. Must be the item URI.

http://www.example.com/

orderingId

Queryunsigned long

A value indicating the order of arrival of the push operation in the index.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

Icon

You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

1497448742564
compressionTypeQuerystring (enum)

The type of compression, if the content is being pushed as compressed binary data.

Possible values are:

  • Deflate
  • GZip
  • LZMA
  • Uncompressed
  • ZLib

Those values are case sensitive.

Note

Icon

If you specify Uncompressed as a compressionType, the content you push in the CompressedBinaryData attribute of the DocumentBody must still be base64 encoded.

Default value is ZLib.

GZip

DocumentBody

BodyDocumentBody

Required.

The data structure to push.

Model:

 See JSON Document.

See JSON Document.

Response codes

CodeDescription

202

Success - The item was pushed in the indexing pipeline of the organization.

400

BadRequest - The request contains invalid data.

401

Unauthorized - The supplied authorization token is invalid or does not allow access to the required resource.

413

TooLarge - The request contains a item that is too large to be processed.

In such a case, use the method with the CompressedBinaryDataFileId reserved key to transfer large files.

429TooManyRequests - Too many requests have been sent in a given amount of time.

504

Timeout - The request took too much time to execute.

Delete item (and optionally, its children)

Deletes a specific item, and optionally its children, from a Coveo Cloud V2 Push source.

Command

 

Parameters

ParameterInTypeDescriptionSample value

organizationId

Pathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid

sourceId

Pathstring

Required.

The unique identifier of the Coveo Cloud V2 Push source.

myorganizationid-veta6vcbq5onxgj5nsiiaske5e

documentId

Querystring

Required.

The unique identifier of the item. Must be the item URI.

http://www.example.com/

orderingId

Queryunsigned long

A value indicating the order of arrival of the push operation in the index.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

Icon

You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

1497448742564
deleteChildrenQueryboolean

Whether to delete the children of the item.

Default value is false.

true

Response codes

CodeDescription

202

Success - The item was deleted from the organization source.

401

Unauthorized - The supplied authorization token is invalid or does not allow access to the required resource.

429TooManyRequests - Too many requests have been sent in a given amount of time.

504

Timeout - The request took too much time to execute.

Delete items older than value

Deletes all items whose orderingId is older (lesser) than the specified value. You should normally use this method to clean-up deleted items at the end of a REBUILD operation (see Set source status).

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid
sourceIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 Push source.

myorganizationid-veta6vcbq5onxgj5nsiiaske5e
orderingIdQueryunsigned long

Required.

The unique identifier which determines whether to delete an item. Any item in the Push source whose orderingId is older (lesser) than this value will be deleted.

1497448742564
queueDelayQueryunsigned integer

A grace period (in minutes) to ensure that all items remaining in the document processing manager (see Coveo Cloud V2 Indexing Pipeline) have been added to the Push source before actually starting the deleting process. This prevents deleted items from inadvertently reappearing in the Push source if they were also being processed by the DPM (because of a REFRESH operation, for instance).

Default value is 15.

10

Response codes

CodeDescription
202Success - The item was pushed in the organization indexing pipeline.
401Unauthorized - The supplied authorization token is invalid or does not allow access to the required resource.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too much time to execute.

Add, update, and/or delete batch of items

Adds, updates, and/or deletes a large number of encrypted items in a Coveo Cloud V2 Push source, with a single request (see Batch Pushing Encrypted Files and Permissions to a Source).

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid
sourceIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 Push source.

myorganizationid-veta6vcbq5onxgj5nsiiaske5e
fileIdQuerystring

Required.

The unique identifier of the file.

You can get this using the Get a large file container method.

d22778ca-7f42-4e13-9d9a-47d01bce866c
orderingIdQueryunsigned long

A value indicating the order of arrival of the push operation in the index.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

Icon

You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

1497448742564

Response codes

CodeDescription
202Success - The items were pushed in the organization indexing pipeline.
400BadRequest - The request contains invalid data.
401Unauthorized - The supplied authorization token is invalid or does not allow access to the required resource.
413TooLarge - The request is too large to be processed.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too must time to execute.

File Resource

Exposes a service to get access to a private, encrypted Amazon S3 file container.

Get large file container

Gets a presigned Amazon S3 uploadUri, as well as a unique fileId.

The uploadUri grants you access to a private, encrypted Amazon S3 file container where you can safely upload content you wish to push. Once your items have been indexed, the S3 file container is automatically deleted.

Note

Icon

The uploadUri expires after 60 minutes.

Using this method is necessary when you need to push a single large item (5 MB or more), or a batch of items and/or permissions.

Command

Parameters

ParameterInTypeDescription
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

Response codes

CodeDescription
201

Success - Access to a private file container was created.

Response schema:

AttributeTypeDescription
uploadUristringThe presigned URI of a private, encrypted Amazon S3 file container.
fileIdstringThe unique identifier of the encrypted Amazon S3 file container.
Sample response:
401Unauthorized - The supplied authorization token is invalid or does not allow access to the required resource.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504GatewayTimeout - The request took too much time to execute.


Identity Resource

Exposes services to provision security identity providers in order to be able to resolve external system permissions and items (see Creating an Identity Provider for a Secured Push Type Source and Pushing Identities to an Identity Provider).

Add or update identity

Adds or updates a single security identity in a Coveo Cloud V2 security identity provider. 

Command

 

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 security identity provider.

MyPushSourceSecurityIdentitiyProvider
orderingIdQueryunsigned long

A value indicating the order of arrival of the push operation in the index.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

Icon

You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

1497448742564
IdentityBodyBodyIdentityBody

Required.

The security identity to add or update.

Model:

IdentityBody

AttributeTypeDescriptionSample value
IdentityIdentityThe identity.See JSON Identity.
MembersArray<Identity>The list of identities which are part of the identity (assuming the identity is a group).See JSON Identity.
WellKnownsArray<Identity>

The list of security identity roles which the identity belongs to.

 WellKnowns can be seen as groups whose members are defined "the other way around". Normally, instead of explicitly specifying the list of members of a well-known identity in its definition, you specify whether a certain identity belongs to a certain well-known in the definition of this "member" identity.

 For instance, suppose you define a GROUP identity called Everyone. Rather than ensuring that the list of members in the Everyone group definition does indeed include everyone (i.e., all identities), you could ensure that each individual identity includes the Everyone identity in its list of WellKnowns.

See JSON Identity.

Identity

See JSON Identity.

Response codes

CodeDescription
202Success - The identity was added or updated in the security identity provider.
400BadRequest - The request contains invalid data.
401Unauthorized - The supplied authorization token is invalid or does not allow access to the required resource.
413TooLarge - The request is too large to be processed.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too much time to execute.

Delete identity

Deletes a single security identity from a Coveo Cloud V2 security identity provider.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 security identity provider.

MyPushSourceSecurityIdentitiyProvider
orderingIdQueryunsigned long

A value indicating the order of arrival of the push operation in the index.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

Icon

You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

1497448742564
BaseIdentityBodyBodyIdentity

Required.

The security identity to delete.

Model:

See JSON Identity.

Response codes

CodeDescription
202Success - The identity was deleted from the security identity provider.
400BadRequest - The request contains invalid data.
401Unauthorized - The supplied authorization token is invalid or doesn't allow access to the required resource.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too much time to execute .

Delete identities older than value

Deletes all identities which are older than a specified orderingId from a Coveo Cloud V2 security identity provider.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 security identity provider.

MyPushSourceSecurityIdentitiyProvider
orderingIdQueryunsigned long

Required.

The unique identifier which determines whether to delete a security identity. Any identity in the security identity provider whose orderingId is older (lesser) than this value will be deleted.

1497448742564

Response codes

CodeDescription
202Success - The identities were deleted from the security identity provider.
400BadRequest - The supplied authorization token is invalid or doesn't allow access to the required resource.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too much time to execute .

Add or update single mapped identity

Adds or updates a single mapped security identity in a Coveo Cloud V2 security identity provider.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 security identity provider.

MyPushSourceSecurityIdentitiyProvider
orderingIdQueryunsigned long

A value indicating the order of arrival of the push operation in the index.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

Icon

You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

1497448742564
  MappedIdentityBody

Required.

The target identity, and the list of source identities to map the target identity with.

MappedIdentityBody:

AttributeTypeDescriptionSample value
WellKnownsArray<Identity>

The list of security identity roles which the target identity belongs to.

WellKnowns can be seen as groups whose members are defined "the other way around". Normally, instead of explicitly specifying the list of members of a well-known identity in its definition, you specify whether a certain identity belongs to a certain well-known in the definition of this "member" identity.

For instance, suppose you define a GROUP identity called Everyone. Rather than ensuring that the list of members in the Everyone group definition does indeed include everyone (i.e., all identities), you could ensure that each individual identity includes the Everyone identity in its list of WellKnowns.

See JSON Identity.
MappingsArray<MappedIdentity>The list of source identities to map the target identity with.See MappedIdentity.
IdentityIdentityThe identity.See JSON Identity.

Identity:

See JSON Identity.

MappedIdentity:

AttributeTypeDescriptionSample value
AdditionalInfoobject

An object which can contain any additional information you wish to provide about the identity in the form of key-value pairs.

Typestring (enum)

The type of the identity.

Valid values:

  • UNKNOWN
  • USER
    Defines a single user.
  • GROUP
    Defines an existing group of identities within the indexed system. Individual members of this group can be of any valid identity Type (USERGROUP, or VIRTUAL_GROUP).
  • VIRTUAL_GROUP
    Defines a group that does not exist within the indexed system. Mechanically, a VIRTUAL_GROUP is identical to a GROUP.

Those values are case sensitive.

GROUP
NamestringThe name of the identity. This name needs to be unique across the entire system.asmith@example.com
Providerstring

The unique identifier of the cascading security identity provider which contains the source identity to map the target identity with.

Note

Icon

 You only need to specify a value for this parameter if your security identity provider has multiple cascading providers.

Email Security Provider

Response codes

CodeDescription
202Success - The mapped identity was added or updated in the security identity provider.
400BadRequest - The request contains invalid data.
401Unauthorized - The supplied authorization token is invalid or doesn't allow access to the required resource.
413TooLarge - The request is too large to be processed.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too much time to execute.

Add, update, and/or delete batch of identities

Adds, updates, and/or deletes a large number of identities in a Coveo Cloud V2 security identity provider, with a single request.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the Coveo Cloud V2 security identity provider.

MyPushSourceSecurityIdentitiyProvider
fileIdQuerystring

Required.

The unique identifier of the file.

You can get this using the Get a large file container method.

d22778ca-7f42-4e13-9d9a-47d01bce866c
orderingIdQueryunsigned long

A value indicating the order of arrival of the push operation in the index.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

Icon

You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

1497448742564

Response codes

CodeDescription
202Success - The batch of identities was added or updated in the security identity provider.
400BadRequest - The request contains invalid data.
401Unauthorized - The supplied authorization token is invalid or doesn't allow access to the required resource.
413TooLarge - The request is too large to be processed.
429TooManyRequests - Too many requests have been sent in a given amount of time.
504Timeout - The request took too much time to execute.

 

JSON Document

A JSON document supplied in the body of a call represents the structure of the data used to add content into an Index.

The document is a collection of key-value pairs where each key represents a metadata, and each value can be a primitive type (string, a number, a date, etc.) that must match the defined field data type which the metadata will be mapped to.

Icon

Each metadata in the JSON document must be unique. Metadata are case-insensitive (e.g., the Push API considers mykey, MyKey, myKey, MYKEY, etc. as identical).

This implies that you can never use a reserved keyword as a distinct metadata, even if you somehow alter its case.

Supported Data Structure

  • Single Value Field

    Single value field can be represented in the form of:

  • Multi-Value Field

    Multi-value field can be represented in the form of:

  • Sub-Object

    Sub-objects are not supported by the Coveo Cloud V2 index:

     

    Sub-objects are not supported

    Icon

JSON Document Reserved Key Names

KeyTypeDescriptionSample value
CompressedBinaryDatabyte

The original binary item content, compressed using one of the supported compression types (Deflate, GZip, LZMA, Uncompressed, or ZLib), and then Base64 encoded.

You can use this parameter when you are pushing a compressed binary item (such as XML/HTML, PDF, Word, or binary) whose size is less than 5 MB.

Whenever you are pushing an item whose size is 5 MB or more, use the CompressedBinaryDataFileIdproperty instead.

If you are pushing less than 5 MB of textual (non-binary) content, you can use the Data property instead.

eJxzrUjMLchJBQAK4ALN
CompressedBinaryDataFileIdstring

The Amazon S3 key which uniquely identifies the file container where the original compressed (Deflate, GZip, LZMA, Uncompressed, or ZLib) binary item content has been uploaded.

You can get this key using the Get large file container method.

Whenever you are pushing compressed binary items (such as XML/HTML, PDF, Word, or binary) whose size is 5 MB and over, you should use this property rather than CompressedBinaryData.

If you are pushing less than 5 MB of textual (non-binary) content, you can use the Data property instead.

In summary, using this key involves three distinct calls (see Pushing Items to a Source):

  1. A POST to get a pre-signed Amazon S3 uploadUri and a fileId (see Get large file container).

  2. A PUT to the uploadUri to push the binary compressed content (not Base64 encoded) of the item to Amason S3.

  3. A PUT with the documentId being the item URI, and the fileId in the CompressedBinaryDataFileId key.  The Coveo Cloud V2 platform takes care of everything, removing your file from Amazon S3 when the push is completed (see Add or update single item and Add, update, and/or delete batch of items). 

d22778ca-7f42-4e13-9d9a-47d01bce866c
ParendIdstring

The unique identifier (URI) of the parent item. Specifying a value for this key creates a relationship between the attachment item (child) and its parent item. This value also ensures that a parent and all of its attachments will be routed in the same index slice.

Note

Icon

The Push API only allows one level of attachment per item (i.e., the Push API does not support attachments within attachments).

http://www.example.com/
FileExtensionstring

The file extension of the data you are pushing. This is useful when pushing a compressed item. The converter uses this information to identify how to correctly process the item.

Values must include the preceding . character

.html

Datastring

The textual (non-binary) content of the item.

Whenever you are pushing a compressed binary item (such as XML/HTML, PDF, Word, or binary), you should use the CompressedBinaryData or CompressedBinaryDataFileId attribute instead, depending on the content size.

"This domain is established to be used for illustrative examples in documents. You may use this domain in examples without prior coordination or asking for permission."
Permissionsarray<PermissionsSetsModel>

The list of permission sets for this item.

This is useful when item based security is required (i.e., when security is not configured at the source level).

Model:

PermissionsSetsModel

AttributeTypeDescriptionSample value
AllowAnonymousboolean

Whether to allow anonymous users in this permission set.

Default value is false.

true
AllowedPermissionsarray<PermissionIdentityModel>The list of allowed permissions for this permission set.See PermissionsIdentityModel.
DeniedPermissionsarray<PermissionIdentityModel>The list of denied permissions for this permission set.See PermissionsIdentityModel.

PermissionIdentityModel

AttributeTypeDescriptionSample value
IdentitystringThe name of the identity. This name needs to be unique across the entire system.asmith@example.com
IdentityTypestring (enum)

The type of the identity.

Valid values:

  • UNKNOWN
  • USER
    Defines a single user.
  • GROUP
    Defines an existing group of identities within the indexed system. Individual members of this group can be of any valid identity Type (USERGROUP, or VIRTUAL_GROUP).
  • VIRTUAL_GROUP
    Defines a group that does not exist within the indexed system. Mechanically, a VIRTUAL_GROUP is identical to a GROUP.

Those values are case insensitive.

USER

In addition, the following key names are also reserved:

  • documentId
    The unique identifier of the item. Must be the item URI.

    If you are pushing a single item, it is useless to specify a value for this key, since documentId is a required query parameter for this call (see Add or update single item). Nevertheless, if you specify a value for this key in the DocumentBody, you must ensure this value precisely matches that of the documentId query string parameter.

    Specifying a value for this key only becomes necessary when you are pushing a batch of items (see Add, update, and/or delete batch of items).

  • orderingId

    A value indicating the order of arrival of the push operation in the index.

    By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch when the push operation is made.

    Icon

    You could manually specify your own orderingId values to ensure that all pushes which are part of a given refresh or rebuild operation are assigned the same orderingId. Doing so would arguably make the Delete items older than value and Delete identities older than value operations easier to use and more predictable, since you would know precisely which set of pushes you are deleting. The Coveo for Sitecore integration uses this approach.

    If you want to refresh a previously pushed item, the new orderingId you provide must be higher than the previous orderingId. Otherwise, the refresh will be rejected.

JSON Identity

A JSON identity supplied in the call BODY represents the structure of the data used to add/update/delete a unique security identity into an identity provider.

Example:

Parameters

AttributeTypeDescriptionSample value
AdditionalInfoobject

An object which can contain any additional information you wish to provide about the identity in the form of key-value pairs.

Typestring (enum)

The type of the identity.

Valid values:

  • UNKNOWN
    Defines an identity whose type is unknown.
  • USER
    Defines a single user.
  • GROUP
    Defines an existing group of identities within the indexed system. Individual members of this group can be of any valid identity Type (UNKNOWN, USERGROUP, or VIRTUAL_GROUP).
  • VIRTUAL_GROUP
    Defines a group that does not exist within the indexed system. Mechanically, a VIRTUAL_GROUP is identical to a GROUP.

Those values are case insensitive.

USER
NamestringThe name of the identity. This name needs to be unique across the entire system.asmith@example.com

Call Example

Comparison to Elastic

URIs used by Elastic to manipulate the content of its index has the following format:


Attributes:

  • <Index>
    Coveo Cloud V2 offers a single index per organization, thus the OrganizationId should be used to represent the destination index.

  • <Type>
    Coveo does not have any concept that matches the Elastic Type attribute which is used to represent an item type. Coveo uses the sourceId to group similar items.

  • <ID>
    Numerical Id that is used to uniquely identify an item. Coveo Cloud V2 must use the full URI to uniquely represent an item.

You should also note that no permission concept exists within Elastic, thus the item pushed into it index does not have the Permissions attribute. Everything else matches, though.

  • No labels