Skip to end of metadata
Go to start of metadata

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

This API 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 Push API operations.

Additional Push API resources

 

All Push API calls must include the following HTTP headers:

KeyValue

Authorization

Bearer <a_valid_API_key_or_OAuth2_token>

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 Push source, effectively creating activity logs for this source.

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 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 (i.e., 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 target Coveo Cloud V2 organization.

myorganizationid

sourceId

Pathstring

Required.

The unique identifier of the target 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

See Troubleshooting Push API Error 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 Push source.

Add or update single item

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

Command

 

Parameters

ParameterInTypeDescriptionSample value

organizationId

Pathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

myorganizationid

sourceId

Pathstring

Required.

The unique identifier of the target 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 (the "age") of the push operation in the index. A lower value, indicates an "older" operation.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.

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.

See Understanding the orderingId Parameter.

1497448742564
compressionTypeQuerystring (enum)

The type of compression, if the content is being pushed as compressed binary data (i.e., the DocumentBody contains a CompressedBinaryData key-value pair).

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

See Troubleshooting Push API Error Codes.

CodeDescription

202

Success - The item was successfully pushed into the indexing pipeline.

Icon

A 202 Success response does not imply that the item was successfully indexed. In fact, the indexing pipeline could still reject the item.

Also, remember that processing a push operation can take a variable amount of time (see Understanding the Push API Processing Delay).

If you want to know the current status of a push operation, you must consult the source logs.

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 an 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 single item (and optionally, its children)

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

Command

 

Parameters

ParameterInTypeDescriptionSample value

organizationId

Pathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

myorganizationid

sourceId

Pathstring

Required.

The unique identifier of the target 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 (the "age") of the push operation in the index. A lower value, indicates an "older" operation.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.

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.

See Understanding the orderingId Parameter.

1497448742564
deleteChildrenQueryboolean

Whether to delete the item children.

Default value is false.

true

Response codes

See Troubleshooting Push API Error Codes.

CodeDescription

202

Success - The Push API has sucessfully received the delete request.

Icon

A 202 Success response does not imply that the items were successfully deleted from the target organization source. In fact, the delete operation could still fail due to invalid parameters.

If you want to know the current status of a delete item operation, you must consult the source logs.

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

Removes all items whose orderingId is "older" (lesser) than the specified value from the Push source. You should typically 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 target Coveo Cloud V2 organization.

myorganizationid
sourceIdPathstring

Required.

The unique identifier of the target Push source.

myorganizationid-veta6vcbq5onxgj5nsiiaske5e
orderingIdQueryunsigned long

Required.

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

See Understanding the orderingId Parameter.

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

See Troubleshooting Push API Error Codes.

CodeDescription
202

Success - The Push API has successfully received the delete request.

Icon

A 202 Success response does not imply that the items were successfully deleted from the target organization source. In fact, the delete operation could still fail due to invalid parameters.

If you want to know the status of a delete operation, you must consult the source logs.

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 Push source with a single request (see Batch Pushing Files and Permissions to a Source).

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

myorganizationid
sourceIdPathstring

Required.

The unique identifier of the target Push source.

myorganizationid-veta6vcbq5onxgj5nsiiaske5e
fileIdQuerystring

Required.

The unique identifier of the file.

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

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

A value indicating the order of arrival (the "age") of the push operation in the index. A lower value, indicates an "older" operation.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.

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.

See Understanding the orderingId Parameter .

1497448742564

Response codes

See Troubleshooting Push API Error Codes.

CodeDescription
202

Success - The batch of items was successfully pushed into the indexing pipeline.

Icon

A 202 Success response does not imply that the entire batch of items was successfully indexed. In fact, the indexing pipeline could still reject some, or all of the items.

Also, remember that processing a push operation can take a variable amount of time (see Understanding the Push API Processing Delay).

If you want to know the current status of a push operation, you must consult the source logs.

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 into a Coveo Cloud V2 index. Once the content has been successfully pushed into the Coveo Cloud V2 indexing pipeline, the Amazon 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 (see Batch Pushing Files and Permissions to a Source).

Command

Parameters

ParameterInTypeDescription
organizationIdPathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

Response codes

See Troubleshooting Push API Error 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 single 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 target Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the target security identity provider.

MyPushSourceSecurityIdentitiyProvider
orderingIdQueryunsigned long

A value indicating the order of arrival (the "age") of the push operation in the index. A lower value, indicates an "older" operation.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.

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.

See Understanding the orderingId Parameter).

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

See Troubleshooting Push API Error Codes.

CodeDescription
202

Success - The add or update identity request was successfully forwarded to an intermediary service. When the security cache refreshes, it will query this service to get the updated security identity expansions.

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 single identity

Deletes a single security identity from a security identity provider.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the target security identity provider.

MyPushSourceSecurityIdentitiyProvider
orderingIdQueryunsigned long

A value indicating the order of arrival (the "age") of the push operation in the index. A lower value, indicates an "older" operation.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.

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.

See Understanding the orderingId Parameter.

1497448742564
BaseIdentityBodyBodyIdentity

Required.

The security identity to delete.

Model:

See JSON Identity.

Response codes

See Troubleshooting Push API Error Codes.

CodeDescription
202Success - The delete identity request was successfully forwarded to an intermediary service. When the security cache refreshes, it will query this service to get the updated security identity expansions.
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 security identity provider.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the target 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.

See Understanding the orderingId Parameter.

1497448742564

Response codes

CodeDescription
202Success - The delete identities request was successfully forwarded to an intermediary service. When the security cache refreshes, it will query this service to get the updated security identity expansions.
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 security identity provider.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the target security identity provider.

MyPushSourceSecurityIdentitiyProvider
orderingIdQueryunsigned long

A value indicating the order of arrival (the "age") of the push operation in the index. A lower value, indicates an "older" operation.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.

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.

See Understanding the orderingId Parameter.

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

See Troubleshooting Push API Error Codes.

CodeDescription
202Success - The add or update mapped identity request was successfully forwarded to an intermediary service. When the security cache refreshes, it will query this service to get the updated security identity expansions.
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 security identity provider with a single request.

Command

Parameters

ParameterInTypeDescriptionSample value
organizationIdPathstring

Required.

The unique identifier of the target Coveo Cloud V2 organization.

myorganizationid
providerIdPathstring

Required.

The unique identifier of the target security identity provider.

MyPushSourceSecurityIdentitiyProvider
fileIdQuerystring

Required.

The unique identifier of the file.

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

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

A value indicating the order of arrival (the "age") of the push operation in the index. A lower value, indicates an "older" operation.

By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.

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.

See Understanding the orderingId Parameter.

1497448742564

Response codes

See Troubleshooting Push API Error Codes.

CodeDescription
202Success - The add, update, and/or delete identity requests were successfully forwarded to an intermediary service. When the security cache refreshes, it will query this service to get the updated security identity expansions.
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