redocly logoAPI docs by Redocly

Push API (v1)

File Container

Create a file container

Create a file container

Creates a temporary, private, and encrypted Amazon S3 file container where you can safely upload the data of an individual item, or a batch of items or security identities. You can then reference the unique identifier of this file container to actually push this content to a Coveo Cloud V2 index.
Once the content of a file container has been successfully forwarded to the Coveo Cloud V2 indexing pipeline, this file container is automatically deleted. In any case, a file container expires after 60 minutes.
Creating a file container is a necessary step when you want to:

Creating a File Container
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

query Parameters
useVirtualHostedStyleUrl
boolean

Whether to generate the presigned URL using the virtual hosted-style URL.
Example of a virtual hosted-style url: https://coveo-nprod-customerdata.s3.us-east-1.amazonaws.com/proda/blobstore/mycoveocloudv2organizationg8tp8wu3/b5e8767e-8f0d-4a89-9095-1127915c89c7[...]

Responses

Response samples

Content type
application/json
{
  • "fileId": "string",
  • "requiredHeaders": {
    },
  • "uploadUri": "string"
}

Item

Manage items in a Push source

Delete an item and optionally its children

Deletes a specific item from a Push source. Optionally, the items of that item can also be deleted.

Deleting an Item and Optionally, its Children in a Push Source
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
deleteChildren
boolean
Default: false

Whether to also delete the children of the item.

documentId
required
string

The unique identifier of the item. Must be the item URI.
Example: file://folder/my-file.html

orderingId
integer <int64>

A value indicating the order of arrival of the Push operation in the Coveo Cloud V2 indexing pipeline. A lower value corresponds to an older operation.
By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.
Specifying a custom orderingId value is typically not recommended unless you know what you are doing and have a good reason to do so (see Understanding the orderingId Parameter).
Example: 1506700606240

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Add or update an item

Adds or updates an individual item in a Push source.

Adding or Updating a Single Item in a Push Source
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
compressionType
string
Enum: "UNCOMPRESSED" "ZLIB" "GZIP" "LZMA" "DEFLATE"

The algorithm that was used to compress the item data.
Specifying a value for this parameter is only necessary when using the compressedBinaryData or the compressedBinaryDataFileId property to push item data (see Pushing Item Data).
The possible values are: Uncompressed, ZLib, GZip, LZMA, and Deflate. Those values are case-sensitive.
Example: ZLib

documentId
required
string

The unique identifier of the item. Must be the item URI.
Example: file://folder/my-file.html

orderingId
integer <int64>

A value indicating the order of arrival of the Push operation in the Coveo Cloud V2 indexing pipeline. A lower value corresponds to an older operation.
By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.
Specifying a custom orderingId value is typically not recommended unless you know what you are doing and have a good reason to do so (see Understanding the orderingId Parameter).
Example: 1506700606240

Request Body schema: application/json
required

A JSON describing a single item to add or update in a Push source.

compressedBinaryData
string

The Base64-encoded item data.
Depending on your specific needs, you can either use the data, compressedBinaryData, or compressedBinaryDataFileId property to push item data (see Pushing Item Data).
Example: "H4sIAAAAAAAA/0utSMwtyEkFAJ+b7G4HAAAA"

compressedBinaryDataFileId
string

The unique identifier of the file container where the compressed or uncompressed, binary or non-binary item data was previously uploaded (see Creating a File Container).
Depending on your specific needs, you can either use the data, compressedBinaryData, or compressedBinaryDataFileId property to push item data (see Pushing Item Data).
Example: "b5e8767e-8f0d-4a89-9095-1127915c89c7"

data
string

The raw textual item data.
Depending on your specific needs, you can either use the data, compressedBinaryData, or compressedBinaryDataFileId property to push item data (see Pushing Item Data).
Example: "<div>My raw textual item data</div>"

fileExtension
string

The file extension of the item data you are pushing.
Value must include a preceding . character.
Specifying a value for this property is typically only useful when using the compressedBinaryData or compressedBinaryDataFileId property to push compressed item data.
Example: ".html"

parentId
string

The URI of the parent item (see Understanding the parentId Property).
Example: "file://folder/"

Array of objects (PermissionSetsModel)
property name*
additional property
string

The metadata key-value pairs to push along with the item (see Understanding Push Source Item Metadata).
Note:
This specification indicates that metadata values must be of the string type, but other types of metadata values are also actually supported (see Allowed Metadata Types).

Responses

Request samples

Content type
application/json
{
  • "compressedBinaryData": "string",
  • "compressedBinaryDataFileId": "string",
  • "data": "string",
  • "fileExtension": "string",
  • "parentId": "string",
  • "permissions": [
    ],
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Add, update, and/or delete a batch of items

Manages a batch of items in a Push source.

Managing Batches of Items in a Push Source
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
fileId
required
string

The unique identifier of the Amazon S3 file container into which the JSON definition of the content update was previously uploaded (see Creating a File Container).
Example: d22778ca-7f42-4e13-9d9a-47d01bce866c

orderingId
integer <int64>

A value indicating the order of arrival of the Push operation in the Coveo Cloud V2 indexing pipeline. A lower value corresponds to an older operation.
By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.
Specifying a custom orderingId value is typically not recommended unless you know what you are doing and have a good reason to do so (see Understanding the orderingId Parameter).
Example: 1506700606240

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Delete old items

In a specific Push source, deletes all items whose last update was made by a Push API operation whose orderingId is strictly lower than a specified value.

Deleting Old Items in a Push Source
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
orderingId
required
integer <int64>

The lowest Push API operation timestamp value an item must be associated to in order not to be deleted from the Push source.
Example: 1506700606240

queueDelay
integer <int32> >= 0

A grace period (in minutes) whose purpose is to give the Coveo Cloud V2 indexing pipeline enough time to finish processing any previously enqueued operation that would affect the target Push source. Default value is 15 minutes.
Example: 5

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Security Identity

Manage security identities in a security identity provider

Add or update an alias

Adds or updates a single security identity alias pointing to one or several security identities in other security identity providers.

Adding or Updating a Single Alias
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

providerId
required
string

The unique identifier of the target security identity provider (see Creating a Security Identity Provider for a Secured Push Source).
Example: My Secured Push Source Security Identity Provider

query Parameters
orderingId
integer <int64>

A value indicating the order of arrival of the Push operation in the Coveo Cloud V2 indexing pipeline. A lower value corresponds to an older operation.
By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.
Specifying a custom orderingId value is typically not recommended unless you know what you are doing and have a good reason to do so (see Understanding the orderingId Parameter).
Example: 1506700606240

Request Body schema: application/json
required

The security identity alias definition.

object (Identity)
Array of objects (MappedIdentity)
object (EntityUpdateResult)
Array of objects (Identity)

Responses

Request samples

Content type
application/json
{
  • "Result": {
    },
  • "identity": {
    },
  • "mappings": [
    ],
  • "wellKnowns": [
    ]
}

Delete a security identity

Deletes a single security identity in the security identity provider of a secured Push source.

Deleting a Single Security Identity
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

providerId
required
string

The unique identifier of the target security identity provider (see Creating a Security Identity Provider for a Secured Push Source).
Example: My Secured Push Source Security Identity Provider

query Parameters
orderingId
integer <int64>

A value indicating the order of arrival of the Push operation in the Coveo Cloud V2 indexing pipeline. A lower value corresponds to an older operation.
By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.
Specifying a custom orderingId value is typically not recommended unless you know what you are doing and have a good reason to do so (see Understanding the orderingId Parameter).
Example: 1506700606240

Request Body schema: application/json
required

The security identity to delete.

object (Identity)
object
name
string

The unique name of the security identity.
Example: `"Alpha Group"

type
string
Enum: "USER" "GROUP" "VIRTUAL_GROUP" "UNKNOWN"

The security identity type.

  • UNKNOWN: a security identity whose type is unknown.
  • USER: an individual user security identity
  • GROUP: an existing group in the original secured enterprise system. Groups can have members of any valid security identity type (i.e., UNKNOWN, USER, GROUP, or VIRTUAL_GROUP).
  • VIRTUAL_GROUP: a group that does not exist in the original secured enterprise system. Mechanically, a VIRTUAL_GROUP works just like a GROUP.
    Example: `"GROUP"

Responses

Request samples

Content type
application/json
{
  • "identity": {
    }
}

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Add or update a security identity

Adds or updates a single security identity in the security identity provider of a secured Push source.

Adding or Updating a Single Security Identity
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

providerId
required
string

The unique identifier of the target security identity provider (see Creating a Security Identity Provider for a Secured Push Source).
Example: My Secured Push Source Security Identity Provider

query Parameters
orderingId
integer <int64>

A value indicating the order of arrival of the Push operation in the Coveo Cloud V2 indexing pipeline. A lower value corresponds to an older operation.
By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.
Specifying a custom orderingId value is typically not recommended unless you know what you are doing and have a good reason to do so (see Understanding the orderingId Parameter).
Example: 1506700606240

Request Body schema: application/json
required

The security identity to add or update.

object (Identity)
Array of objects (Identity)
object (EntityUpdateResult)
Array of objects (Identity)

Responses

Request samples

Content type
application/json
{
  • "Result": {
    },
  • "identity": {
    },
  • "members": [
    ],
  • "wellKnowns": [
    ]
}

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Add, update, and/or delete a batch of security identities

Manages a batch of security identities in the security identity provider of a secured Push source.

Managing Batches of Security Identities
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

providerId
required
string

The unique identifier of the target security identity provider (see Creating a Security Identity Provider for a Secured Push Source).
Example: My Secured Push Source Security Identity Provider

query Parameters
fileId
required
string

The unique identifier of the Amazon S3 file container into which the JSON definition of the security identity update was previously uploaded (see Creating a File Container).

orderingId
integer <int64>

A value indicating the order of arrival of the Push operation in the Coveo Cloud V2 indexing pipeline. A lower value corresponds to an older operation.
By default, the service automatically sets this parameter to the current number of milliseconds since Unix Epoch.
Specifying a custom orderingId value is typically not recommended unless you know what you are doing and have a good reason to do so (see Understanding the orderingId Parameter).
Example: 1506700606240

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Delete old security identities

In a specific security identity provider, deletes all security identities whose last update was made by a Push API operation whose orderingId is strictly lower than a specified value.

Deleting Old Security Identities
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

providerId
required
string

The unique identifier of the target security identity provider (see Creating a Security Identity Provider for a Secured Push Source).
Example: My Secured Push Source Security Identity Provider

query Parameters
orderingId
required
integer <int64>

The lowest Push API operation timestamp value a security identity must be associated to in order not to be deleted from the security identity provider.
Example: 1506700606240

queueDelay
integer <int32> >= 0

A grace period (in minutes) whose purpose is to give the Coveo Cloud V2 indexing pipeline enough time to finish processing any previously enqueued operation that would affect the target Push source. Default value is 15 minutes.
Example: 5

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Source Status

Update the status of a Push source

Set the status of a Push source

Modifies the current status of a Push source.
This operation allows you to update the activity logs of a 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.

Updating the Status of a Push Source
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
statusType
required
string
Enum: "INCREMENTAL" "REFRESH" "REBUILD" "IDLE"

The status to set the Push source to.
The possible values are: INCREMENTAL, REFRESH, REBUILD, and IDLE.
Example: REBUILD

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Stream

Manage streams

Delete old documents

Delete documents indexed before specified epoch milliseconds.

Authorizations:
oauth2
path Parameters
epochMilliseconds
required
string

The epoch milliseconds timestamp limit used to delete documents indexed before it.
Example: 1699456507127 for nov 8th 2023 15:15 UTC time

organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target source.
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
queueDelay
integer <int32> >= 0

A grace period (in minutes) whose purpose is to give the Coveo Cloud V2 indexing pipeline enough time to finish processing any previously enqueued operation that would affect the target stream enabled source. Default value is 15 minutes.
Example: 5

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Update a catalog stream source

Perform inline update of catalog items.

Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

Request Body schema: application/json
required

A JSON describing a batch of documents to update in catalog.

partialUpdate
Array of objects (InlineUpdateModel)

Responses

Request samples

Content type
application/json
{
  • "partialUpdate": [
    ]
}

Response samples

Content type
application/json
{
  • "orderingId": "string",
  • "requestId": "string"
}

Merge documents of a catalog stream source

Perform a shallow merge with a batch of items in a Catalog source.

Merge a batch of items in a Catalog source
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
fileId
required
string

The unique identifier of the Amazon S3 file container into which the JSON definition of the content update was previously uploaded (see Creating a File Container).
Example: d22778ca-7f42-4e13-9d9a-47d01bce866c

Responses

Response samples

Content type
application/json
{
  • "orderingId": "string",
  • "requestId": "string"
}

Open a stream

Opens a stream for upload.

Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target source.
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Update a catalog stream source

Manages a batch of items in a Catalog source.

Upload a batch of items to a Catalog source
Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

shard
required
string

Experimental An identifier to process the JSON payload by groups. The shard must be a string from 1 to 10 alphanumeric characters.

sourceId
required
string

The unique identifier of the target Push source (see Creating a Push Source).
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

query Parameters
fileId
required
string

The unique identifier of the Amazon S3 file container into which the JSON definition of the content update was previously uploaded (see Creating a File Container).
Example: d22778ca-7f42-4e13-9d9a-47d01bce866c

Responses

Response samples

Content type
application/json
{
  • "orderingId": "string",
  • "requestId": "string"
}

Get a new chunk for a stream

Requests another chunk of a stream for upload.

Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target source.
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

streamId
required
string

The unique identifier of the stream.
Example: 18320d0e-c2e8-4a56-acfc-4eae55f92380

Responses

Response samples

Content type
application/json
{
  • "errorCode": "string",
  • "message": "string"
}

Close a stream

Closes a stream.

Authorizations:
oauth2
path Parameters
organizationId
required
string

The unique identifier of the target Coveo Cloud V2 organization.
Example: mycoveocloudv2organizationg8tp8wu3

sourceId
required
string

The unique identifier of the target source.
Example: rp5rxzbdz753uhndklv2ztkfgy-mycoveocloudv2organizationg8tp8wu3

streamId
required
string

The unique identifier of the stream.
Example: 18320d0e-c2e8-4a56-acfc-4eae55f92380

Responses

Response samples

Content type
application/json
{
  • "orderingId": "string",
  • "requestId": "string"
}