Skip to end of metadata
Go to start of metadata

The Push API allows developers to make content searchable by sending system items (and if applicable their associated permissions) to a Coveo Cloud V2 push type source (see Push API Usage Overview).

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

Note:

Other Push API resources:

 

All Push API calls must include the following HTTP headers:

KeyValue

Authorization

Bearer <a_valid_API_key>

Available only when you create the Push source, it is recommended to 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

Activities are used to regroup item operations performed on a given source. Activities are used by the Coveo Cloud V2 administration console to give statistics/visibility on what is going on with a source.

Set Source Status

Used to set the current source state. In practice, this call only purpose is to update source activity indicators in the Coveo Cloud V2 administration console and logs. 

It is a good practice to set the status to REBUILD (or REFRESH or INCREMENTAL for smaller updates) before adding, updating, or deleting items, and then set the status back to IDLE when the item pushing is completed to create source activity logs in the administration console. 

Command

Parameters
ParameterDescription

organizationId

Unique organization identifier

sourceId

Unique identifier of the source for which the status is specified

statusType

The status type can be:

  • REBUILD

  • REFRESH

  • INCREMENTAL

  • IDLE

An activity is created when an active source state (REBUILD, REFRESH or INCREMENTAL) is pushed. An ongoing activity is terminated and marked complete when the IDLE status is pushed.

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

This API is used to send content into a push enabled custom source in a Coveo Cloud V2 organization index.

You must supply an authorization token (API key) with each performed call. This token is used to validate access to the required resource.

Add/Update Document

The add/update API adds a JSON item into an organization source.

Command

 

Parameters
ParameterDescription

organizationId

Unique organization identifier

sourceId

Unique identifier of the source in which the item will be added.

documentId

Unique item identifier, must be the item URI.

orderingId

[Optional] 64-bit unsigned integer that will be used by the Index to ensure that operations are applied in the correct order. If no value is supplied, a timestamped ordering value is added internally to ensure that changes are performed in the order they were received. This is important in cases where more than one change for a given item are pushed in a short period of time. The index will process the multiple changes for this item to ensure the index contains the latest changes.

Specifying an orderingId value is useful only with the call that allows you to cancel all unprocessed pushes with an orderingId value lower than a given value (see Delete Old Documents).

DocumentBody

The body contains the JSON document to add/update (see JSON Document).

 

Response codes
CodeDescription

202

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

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 take too much time to execute.

Delete Document

The delete API deletes a specific item (and if applicable its children) from an organization source.

Command

 

 

Parameters
ParameterDescription

organizationId

Unique organization identifier

sourceId

Unique identifier of the source from which the item will be deleted.

documentId

Unique item identifier, must be the item URI.

orderingId

[Optional] 64-bit unsigned integer that will be used by the Index to ensure that operations are applied in the correct order.

deleteChildren[Optional] Boolean used to determine if the children of the item will be deleted as part of the delete process. The default value is false.
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 Old Documents

This delete API allows unrefreshed items to be deleted from the index. This method is normally used to clean-up deleted items at the end of a Rebuild operation.

Command

Parameters
ParameterDescription
organizationIdUnique organization identifier
queueDelay[Optional] Grace period to ensure that items remaining in the document processing manager (DPM) (see Coveo Cloud V2 Indexing Pipeline) are added to the index before actually deleting the old items. Prevents deleted items from reappearing inadvertently in the index if they were also being processed by the DPM (because of a refresh operation, for instance). The default value is 15 (minutes).
sourceIdUnique identifier of the source from which items will be deleted.
orderingIdUnique identifier that will be used to filter which items were not refreshed (all items having an ordering ID lower that the specified one)
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 take too much time to execute.

Add/Update/Delete Encrypted Files in a Batch

This call is used to send a large number of encrypted items in a single request.

Command

Parameters
ParameterDescription
sourceIdUnique identifier of the source in which the item will be added.
fileIdUnique file identifier used to link the uploaded data.
organizationId

Unique organization identifier

orderingId[Optional] Unique identifier that will be used to filter which items were not refreshed (all items having an ordering ID lower that the specified one)
deleteChildren[Optional] Boolean used to determine if the children of the item will be deleted as part of the delete process. The default value is false.
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 

Get Large File Container

The large file container API gives an UUI allowing a large item body to be pushed into Amazon S3. Only compressed files are supported.

Command

Parameters
ParameterDescription
organizationIdUnique organization identifier


On success the command returns an object that gives information regarding where the data need to be saved.

 

 

KeyValue
uploadUriSecure URI used to upload the item data into an Amazon S3 file
fileIdIdentifier used to link the uploaded data to the pushed item, this value needs to be set in the item CompressedBinaryDataFileId metadata.

 

Response codes
CodeDescription
201Success - Access to a private file container is created
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 take too much time to execute


Identity Resource

This API allows you to provision an identity provider so that external system permissions on items can be resolved (see Creating an Identity Provider for a Secured Push Type Source and Pushing Identities to an Identity Provider).

Add/Update Identity

This call is used to add or update a unique security identity into an identity provider. 

Command

 

Parameters
ParameterDescription
organizationIdUnique organization identifier
providerIdUnique identifier of the provider into which the identity will be added/updated
orderingId[Optional] Unique identifier that will be used to filter which permissions were not refreshed (all identities having an ordering ID lower that the specified one)
Response codes
CodeDescription
202Success - The identity was added/updated to the 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

This call is used to delete a security identity from an identity provider.

Command


and replace identity_name by the name of the identity that you want to delete.

Parameters
ParameterDescription
organizationIdUnique organization identifier
providerIdUnique identifier of the provider from where the identity will be deleted
orderingId[Optional] Unique identifier that will be used to filter which permissions were not refreshed (all identities having an ordering ID lower that the specified one)
Response codes
CodeDescription
202Success - The identity was deleted from the 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 Old Identities

Command

Parameters
ParameterDescription
organizationIdUnique organization identifier
providerIdUnique identifier of the provider from where the identities will be deleted
orderingIdUnique identifier that will be used to filter which permissions were not refreshed (all identities having an ordering ID lower that the specified one)
Response codes
CodeDescription
202Success - Identities were deleted from the 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/Update Mapped Identity

 

Command

Parameters
ParameterDescription
organizationIdUnique organization identifier
providerIdUnique identifier of the provider into which the identity will be added/updated
orderingId[Optional] Unique identifier that will be used to filter which permissions were not refreshed (all identities having an ordering ID lower that the specified one)
Response codes
CodeDescription
202Success - The identity was added/updated to the 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 Identities in a Batch

Command

Parameters
ParameterDescription
organizationIdUnique organization identifier
providerIdUnique identifier of the provider into which the identity will be added/updated
fileIdUnique file identifier (as returned by large file API) that gives that batch of identities to add/update.
orderingId[Optional] Unique identifier that will be used to filter which permissions were not refreshed (all identities having an ordering ID lower that the specified one)
Response codes
CodeDescription
202Success - The identity was added/updated to the 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 call BODY represents the structure of the data used to add content into an Index.

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

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 cannot 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:

     

Reserved Key Names

  • Data

    This key is used to supply the item content in a textual form only (no binary). 

  • DocumentId
    This key must specify the unique ID of the item (most of the time, this will 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/Update Document). Nevertheless, if you specify a value for this key, you must ensure this value precisely matches that of the documentId query string parameter.
  • CompressedBinaryData

    This key is used to supply the original binary item content compressed using the deflate (zlib) algorithm. The value needs to be Base64 encoded.

    This is the preferred way of pushing binary items (such as XML/HTML, PDF, Word, binary) up to 5MB into the indexing pipeline. 

    Rather use the CompressedBinaryDataFileId key when you get a 413 TooLarge error.

  • CompressedBinaryDataFileId

    This key is used to supply an Amazon S3 key to a file that contains the original binary item content, compressed using the Deflate (zlib) algorithm. 

    This is the preferred way of pushing large binary items into the indexing pipeline. Use this method for compressed content larger than 5MB. Reduce this limit when the rest of the JSON document is not negligible.  

    In short, when using this key, the method involves three calls (see Pushing Items to a Source):

    1. POST to get a presigned Amazon S3 uploadUri and the fileId.

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

    3. PUT to the Push API 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. 

  • FileExtension

    This optional key can be used to give information about the format of the pushed data. This information will be used by the converter to correctly identify how to process the item. The extension should contain the ‘.’ (dot), for example ‘.txt’ for a text file.

  • orderingId
    This can be used to filter which items or permissions were not refreshed (all items or identities having an ordering ID lower that the specified one). Preseance is given to the query param when both are present.

  • ParentId

    This key is used to make a relationship between an attachment and its parent. The value should represent the parent item unique identifier. This Id will also be used to ensure that a parent and all its attachments are routed into the same slice. 

    Only one level of attachment is supported by the Push API, attachments within attachment are not supported. 

  • Permissions

    This key is used when item based security is required (when security isn't configured at the source level).

    Simple Permission Model
    Complex Permission Model

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.

Parameters

KeyValue
NameName provided by the identity provider to identify the security identity
Type

The type can be:

  • UNKNOWN
  • USER
  • GROUP
  • VRTUAL_GROUP
AdditionalInfoThe additional information is a collection of key value pairs that can be used to uniquely identify the security identity.


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