Push API reference

This is for:

Developer System Administrator

The Push API lets you push items, permissions, and security identities into a Coveo index, rather than pulling content using standard Coveo connectors and crawlers (see Use 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 Platform offers no source type.

This article provides reference information describing the available Push API operations.

Tip
Additional Push API resources

All Push API calls must include the following HTTP headers:

Key Value

Authorization

Bearer <a_valid_API_key_or_OAuth2_token>

Tip

When you create a Push source through the Coveo Administration Console, you can select the Create an API key checkbox to easily get an API key authorized to push content to sources.

Content-Type

application/json
Note

All REST API string fields are case-sensitive unless otherwise specified. For example, search queries aren’t case-sensitive.

To keep behavior consistent across the Coveo Platform, the same value passed to different REST APIs must always be passed using the same case. For example, if the unique product identifier, such as ec_product_id, is passed to the Commerce API in lowercase, then it should also be passed to the Usage Analytics Write API in lowercase.

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 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 Administration Console).

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

Command

POST https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/status?statusType={statusType} HTTP/1.1

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
sourceId (Path, string, Required)

The unique identifier of the target Push source.

Example
myorganizationid-veta6vcbq5onxgj5nsiiaske5e
statusType (Query, string(enum), Required)

The status to set the Push source to.

Valid values:

  • REBUILD

  • REFRESH

  • INCREMENTAL

  • IDLE

These values are case insensitive.

Example
`REBUILD`

Response codes

See Troubleshoot Push API error codes.

Code Description

201

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

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

429

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

504

Timeout - 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 or its related permissions in a Push source (see Add or update a single item in a Push source).

Command

PUT https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId}

Payload body:

{
  "<DocumentBody>"
}

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
sourceId (Path, string, Required)

The unique identifier of the target Push source.

Example
myorganizationid-veta6vcbq5onxgj5nsiiaske5e
documentId (Query, string, Required)

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

Example
http://www.example.com/
orderingId (Query, unsigned 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.

Notes

  • 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’re 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 About the orderingId parameter.

Example
1497448742564
compressionType (Query, string (enum))

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

Possible values are:

  • Deflate

  • GZip

  • LZMA

  • Uncompressed

  • ZLib

These values are case sensitive.

Note

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.

Example
`GZip`
DocumentBody (Body, DocumentBody, Required)

The data structure to push.

Model:

See JSON document.

Response codes

See Troubleshoot Push API error codes.

Code Description

202

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

Notes

  • A 202 Success response doesn’t 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 About 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 doesn’t allow access to the required resource.

413

TooLarge - The request contains an item that’s too large to be processed.

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

429

TooManyRequests - 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

DELETE https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents?documentId={documentId} HTTP/1.1

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
sourceId (Path, string Required)

The unique identifier of the target Push source.

Example
myorganizationid-veta6vcbq5onxgj5nsiiaske5e
documentId (Query, string, Required)

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

Example
http://www.example.com/
orderingId (Query, unsigned 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.

Notes

  • 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’re 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 About the orderingId parameter.

Example
1497448742564
deleteChildren (Query, Boolean)

Whether to delete the item children.

Default value is false.

Example
true

Response Codes

See Troubleshoot Push API error codes.

Code Description

202

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

Notes

  • A 202 Success response doesn’t 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 doesn’t allow access to the required resource.

429

TooManyRequests - 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

DELETE https://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents/olderthan?orderingId={orderingId} HTTP/1.1

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
sourceId (Path, string, Required)

The unique identifier of the target Push source.

Example
myorganizationid-veta6vcbq5onxgj5nsiiaske5e
orderingId (Query, unsigned 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 About the orderingId parameter.

Example
1497448742564
queueDelay (Query, unsigned integer)

A grace period (in minutes) to ensure that all items remaining in the document processing manager (see Coveo 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 example).

Default value is 15.

Example
10

Response codes

See Troubleshoot Push API error codes.

Code Description

202

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

Notes

  • A 202 Success response doesn’t 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.

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

429

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

504

Timeout - The request took too much time to execute.

Add, update, and/or delete batch of items

Adds, updates, or deletes a large number of encrypted items in a Push source with a single request (see Manage batches of items in a Push source).

Command

PUT http://api.cloud.coveo.com/push/v1/organizations/{organizationId}/sources/{sourceId}/documents/batch?fileId={fileId} HTTP/1.1

Parameters

organizationId (Path, string Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
sourceId (Path, string, Required)

The unique identifier of the target Push source.

Example
myorganizationid-veta6vcbq5onxgj5nsiiaske5e
fileId (Query, string, Required)

The unique identifier of the file.

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

Example
d22778ca-7f42-4e13-9d9a-47d01bce866c
orderingId (Query, unsigned 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.

Notes

  • 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’re 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 About the orderingId parameter.

Example
1497448742564

Response codes

See Troubleshoot Push API error codes.

Code Description

202

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

Notes

  • A 202 Success response doesn’t 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 About 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 doesn’t allow access to the required resource.

413

TooLarge - The request contains an item that’s too large to be processed.

429

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

504

Timeout - The request took too much 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 want to push into a Coveo index. Once the content has been successfully pushed into the Coveo indexing pipeline, the Amazon S3 file container is automatically deleted.

Important

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 or permissions (see Manage batches of items in a Push source).

Command

POST http://api.cloud.coveo.com/push/v1/organizations/{organizationId}/files HTTP/1.1

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid

Response codes

See Troubleshoot Push API error codes.

Code Description

201

Success - Access to a private file container was created.

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

429

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

504

Timeout - The request took too much time to execute.

201 Success response schema:

Attribute Type Description

uploadUri

string

The presigned URI of a private, encrypted Amazon S3 file container.

fileId

string

The unique identifier of the encrypted Amazon S3 file container.

201 Success sample response:

{
  "uploadUri" : "https://coveo-nprod-customerdata.s3.amazonaws.com/proda/blobstore/myorganizationid/d22778ca-7f42-4e13-9d9a-47d01bce866c[...]",
  "fileId" : "d22778ca-7f42-4e13-9d9a-47d01bce866c"
}

Identity Resource

Exposes services to provision security identity providers to be able to resolve external system permissions and items (see Create a security identity provider for a secured Push source and Manage security identities in a security identity provider).

Add or update single identity

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

Command

PUT http://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions HTTP/1.1

Payload:

{
  <IdentityBody>
}

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
providerId (Path, string, Required)

The unique identifier of the target security identity provider.

Example
MyPushSourceSecurityIdentitiyProvider
orderingId (Query, unsigned 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.

Notes

  • 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’re 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 About the orderingId parameter.

Example
1497448742564
IdentityBody (Body, IdentityBody, Required)

The security identity to add or update.

Model:

IdentityBody

Attribute Type Description Sample value

Identity

Identity

The identity.

See JSON identity.

Members

Array<Identity>

The list of identities which are part of the identity (assuming the identity is a group).

See JSON identity.

WellKnowns

Array<Identity>

The list of security identity roles which the identity belongs to (see {granted identity}).

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 example, 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 (that is, 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.

{
  "Identity" : {
    "AdditionalInfo" : {},
    "Type" : "GROUP",
    "Name" : "UX"
  },
  "Members" : [
    {
      "AdditionalInfo" : {},
      "Type" : "USER",
      "Name" : "Alice Smith"
    },
    {
      "AdditionalInfo" : {},
      "Type" : "USER",
      "Name" : "Bob Jones"
    }
  ],
  "WellKnowns" : [
    {
      "AdditionalInfo" : {},
      "Type" : "VIRTUAL_GROUP",
      "Name" : "Everyone"
    }
  ]
}

Response codes

See Troubleshoot Push API error codes.

Code Description

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.

400

BadRequest - The request contains invalid data.

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

413

TooLarge - The request is too large to be processed.

429

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

504

Timeout - The request took too much time to execute.

Delete single identity

Disables a single security identity in the security identity cache.

Command

DELETE http://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions HTTP/1.1

Payload:

{
  <BaseIdentityBody>
}

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
providerId (Path, string, Required)

The unique identifier of the target security identity provider.

Example
MyPushSourceSecurityIdentitiyProvider
orderingId (Query, unsigned 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.

Notes

  • 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’re 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 About the orderingId parameter.

Example
1497448742564
BaseIdentityBody (Body, JSON, Required)

The security identity to delete.

Model:

See JSON identity.

Example
{
  "AdditionalInfo" : {},
  "Type" : "USER",
  "Name" : "Alice Smith"
}

Response codes

See Troubleshoot Push API error codes.

Code Description

202

Success - 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.

400

BadRequest - The request contains invalid data.

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

429

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

504

Timeout - The request took too much time to execute.

Delete identities older than value

Disables all identities which are older than a specified orderingId in the security identity cache.

Command

DELETE http://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/olderthan?orderingId={orderingId} HTTP/1.1

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
providerId (Path, string, Required)

The unique identifier of the target security identity provider.

Example
MyPushSourceSecurityIdentitiyProvider
orderingId (Query, unsigned 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 About the orderingId parameter.

Example
1497448742564

Response codes

Code Description

202

Success - 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.

400

BadRequest - The request contains invalid data.

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

429

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

504

Timeout - 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

PUT http://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/mappings HTTP/1.1

Payload:

{
  <MappedIdentityBody>
}

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
providerId (Path, string, Required)

The unique identifier of the target security identity provider.

Example
MyPushSourceSecurityIdentitiyProvider
orderingId (Query, unsigned 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.

Notes

  • 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’re 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 About the orderingId parameter.

Example
1497448742564
mappedIdentityBody (Body, mappedIdentityBody, Required)

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

MappedIdentityBody:

Attribute Type Description Sample value

WellKnowns

Array<Identity>

The list of security identity roles which the identity belongs to (see granted identity).

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 example, 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 (that is, all identities), you could ensure that each individual identity includes the Everyone identity in its list of WellKnowns.

See JSON identity.

Mappings

Array<MappedIdentity>

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

See MappedIdentity.

Identity

Identity

The identity.

See JSON identity.

Identity:

See JSON identity.

MappedIdentity
Attribute Type Description Sample value

AdditionalInfo

object

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

 
{
  "key1" : "value 1",
  "key2" : "value 2",
  "keyN" : "value N"
}

Type

string (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 (USER, GROUP, or VIRTUAL_GROUP).

  • VIRTUAL_GROUP

    Defines a group that doesn’t exist within the indexed system. Mechanically, a VIRTUAL_GROUP is identical to a GROUP.

These values are case sensitive.

GROUP

Name

string

The name of the identity. This name needs to be unique across the entire system.

asmith@example.com

Provider

string

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

Note

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

Email Security Provider
Example
{
  "WellKnowns" : [
    {
      "AdditionalInfo" : {},
      "Type" : "VIRTUAL_GROUP",
      "Name" : "Everyone"
    }
  ],
  "Mappings" : [
    {
      "AdditionalInfo" : {},
      "Type" : "USER",
      "Name" : "asmith@example.com",
      "Provider" : "Email Security Provider"
    }
  ],
  "Identity" : {
    "AdditionalInfo" : {},
    "Type" : "USER",
    "Name" : "Alice Smith"
  }
}

Response codes

See Troubleshoot Push API error codes.

Code Description

202

Success - 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.

400

BadRequest - The request contains invalid data.

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

413

TooLarge - The request is too large to be processed.

429

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

504

Timeout - The request took too much time to execute.

Add, update, and/or delete batch of identities

Adds, updates, or deletes a large number of identities in a security identity provider with a single request.

Command

PUT http://api.cloud.coveo.com/push/v1/organizations/{organizationId}/providers/{providerId}/permissions/batch?fileId={fileId} HTTP/1.1

Parameters

organizationId (Path, string, Required)

The unique identifier of the target Coveo organization.

Example
myorganizationid
providerId (Path, string, Required)

The unique identifier of the target security identity provider.

Example
MyPushSourceSecurityIdentitiyProvider
fileId (Query, string, Required)

The unique identifier of the file.

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

Example
d22778ca-7f42-4e13-9d9a-47d01bce866c
orderingId (Query, unsigned 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.

Notes

  • 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’re 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 About the orderingId parameter.

Example
1497448742564

Response codes

See Troubleshoot Push API error codes.

Code Description

202

Success - The add, update, 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.

400

BadRequest - The request contains invalid data.

401

Unauthorized - The supplied authorization token is invalid or doesn’t allow access to the required resource.

413

TooLarge - The request is too large to be processed.

429

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

504

Timeout - 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.

Important

Each metadata in the JSON document must be unique. Metadata are case-insensitive (for example, 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:

    "key" : "value"

  • Multi-value field

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

    "key" : [
  "value1",
  "value2",
  "value3"
]

  • Sub-object

    Sub-objects aren’t supported by the Coveo index.

    Important

    Sub-objects aren’t supported.

    "key" : {
  [ ... ]
}

JSON document reserved key names

CompressedBinaryData (byte)

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’re pushing a compressed binary item (such as XML/HTML, PDF, Word, or binary) whose size is less than 5 MB.

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

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

Example
eJxzrUjMLchJBQAK4ALN

CompressedBinaryDataFileId (string)

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’re 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’re 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 Manage batches of items in a Push 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 Amazon S3.

  3. A PUT with the documentId being the item URI, and the fileId in the CompressedBinaryDataFileId key. Coveo 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).

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

ParentId (string)

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

The Push API only allows one level of attachment per item (that is, the Push API doesn’t support attachments within attachments).
Example
http://www.example.com/

FileExtension (string)

The file extension of the data you’re 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.

Example
.html

Data (string)

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

Whenever you’re 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.

Example
"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."

Permissions (array<PermissionsSetsModel>)

The list of permission sets for this item.

This is useful when item-based security is required (that is, when security isn’t configured at the source level).

Model:

PermissionsSetsModel

Attribute Type Description Sample value

AllowAnonymous

Boolean

Whether to allow anonymous users in this permission set.

Default value is false.

true

AllowedPermissions

array<PermissionsIdentityModel>

The list of allowed permissions for this permission set.

See PermissionsIdentityModel.

DeniedPermissions

array<PermissionsIdentityModel>

The list of denied permissions for this permission set.

See PermissionsIdentityModel.
PermissionIdentityModel
Attribute Type Description Sample value

IdentityType

string (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 (USER, GROUP, or VIRTUAL_GROUP).

  • VIRTUAL_GROUP

    Defines a group that doesn’t exist within the indexed system. Mechanically, a VIRTUAL_GROUP is identical to a GROUP.

These values are case insensitive.

USER

securityProvider

string

The security identity provider through which the security identity is updated.

Defaults to the first security identity provider associated with the target Push source.

My Security Identity Provider
Example
[
  {
    "AllowAnonymous" : false,
    "AllowedPermissions" : [
      {
        "Identity" : "asmith@example.com",
        "IdentityType" : "USER"
      }
    ],
    "DeniedPermissions" : [
      {
        "Identity" : "deprecated_users",
        "IdentityType" : "GROUP"
      }
    ]
  }
]

In addition, the following key names are also reserved:

  • documentId

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

    If you’re pushing a single item, it’s 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’re pushing a batch of items (see Manage batches of items in a Push source).

  • 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.

    Notes

    • 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’re 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, or delete a unique security identity into an identity provider.

{
  "Name" : "Alice Smith",
  "Type" : "USER",
  "AdditionalInfo": {
    "key1" : "value 1",
    "key2" : "value 2",
    "keyn" : "value n"
  }
}

Parameters

AdditionalInfo (object)

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

Example
{
  "key1" : "value 1",
  "key2" : "value 2",
  "keyN" : "value N"
}

Type (string (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, USER, GROUP, or VIRTUAL_GROUP).

  • VIRTUAL_GROUP

    Defines a group that doesn’t exist within the indexed system. Mechanically, a VIRTUAL_GROUP is identical to a GROUP.

These values are case insensitive.

Example
`USER`

Name (string)

The name of the identity. This name needs to be unique across the entire system.

Example
`asmith@example.com`

Call example

PUT http://api.cloud.coveo.com/push/v1/organizations/mycoveoorg/sources/mycoveoorg-qowj5lnc2lqhm/documents?orderingId=42&documentId=http://www.salesforce.com/org:organization/object:Account/record:00160534000z9v9yAAA HTTP/1.1

Payload:

{
  "AccountNumber" : 1567,
  "Name" : "Nasdaq",
  "Phone" : "1-212-401-8700",
  "title" : "Nasdaq",
  "Website" : "www.nasdaqonx.com",
  "Industry" : "Finance",
  "CreatedDate" : "2014-05-16T00:51:37.000+0000",
  "BillingStreet" : "165 Broadway",
  "BillingCity" : "New York",
  "BillingState" : "NY",
  "BillingCountry" : "United States",
  "BillingPostalCode" : "10006-1404",
  "Tags" : [
    "Account",
    "Finance"
  ],
  "Data" : "Account information regarding the NASDAQ client",
  "Permissions" : [
    {
      "AllowAnonymous" : false,
      "AllowedPermissions" : [
        {
          "Type" : "VIRTUAL_GROUP",
          "Name" : "ViewAll:Irrelevant:"
        },
        {
          "Type" : "VIRTUAL_GROUP",
          "Name" : "ObjectAccess:ViewAllRecordsProfiles:Account"
        },
        {
          "Type" : "VIRTUAL_GROUP",
          "Name": "ObjectAccess:ReadRecordsProfiles:Account"
        },
        {
          "Type" : "VIRTUAL_GROUP",
          "Name" : "ObjectAccess:ReadRecordsPermissionSets:Account"
        }
      ],
      "DeniedPermissions" : [
        {
          "Type" : "USER",
          "Identity" : "tjones"
        }
      ]
    }
  ]
}

Comparison to Elastic

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

<REST Verb>  http://<Node>:<Port>/<Index>/<Type>/<ID>

Attributes:

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

  • <Type> Coveo doesn’t 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’s used to uniquely identify an item. Coveo must use the full URI to uniquely represent an item.

You should also note that no permission concept exists within Elastic, therefore the item pushed into it index doesn’t have the Permissions attribute. Everything else matches, though.

PUT http://cloud.coveo.com/Salesforce/Account/1 HTTP/1.1

Payload:

{
  "Uri":"http://www.salesforce.com/org:organization/object:Account/record:0016000000z9v9yAAA",
  "AccountNumber": 1567,
  "Name":"Nasdaq",
  "Phone":"1-212-401-8700",
  "title":"Nasdaq",
  "Website":"www.nasdaqonx.com",
  "Industry":"Finance",
  "CreatedDate":"2014-05-16T00:51:37.000+0000",
  "BillingStreet":"165 Broadway",
  "BillingCity":"New York",
  "BillingState":"NY",
  "BillingCountry":"United States",
  "BillingPostalCode":"10006-1404",
  "Tags":[
    "Account",
    "Finance"
  ],
  "Data":"Account information regarding the NASDAQ client"
}