Adding or Updating a Single Item in a Push Source

Being able to add or update a single item in a Push source can be especially useful when you are testing the service or when you need to perform a very small content update.

Perform a security identity update

Whenever you add or update content in a secured Push source, you should ensure that the security identities referenced in item permission models are up to date in the security identity cache.

In essence, you should always perform a security identity update on the security identity provider of a secured Push source before you perform a content update in that source (see Managing Security Identities in a Security Identity Provider).

Use the Add or update an item operation described in the following table to add or update an item along with its corresponding metadata, data, and permission model (if applicable) in a Push source.

Request template

PUT https://push.cloud.coveo.com/v1/organizations/<MyOrganizationId>/sources/<MySourceId>/documents?documentId=<MyItemURI>&compressionType=<MyCompressionType> HTTP/1.1
 
Content-Type: application/json
Accept: application/json:
Authorization: Bearer <MyAccessToken>

Payload (see Item Models - DocumentBody)

{
  <MyItemMetadata>,
  <MyItemDataProperty>: <MyItemDataOrFileId>,
  "fileExtension": <MyItemDataFileExtension>,
  "parentId": <MyItemParentId>,
  "permissions": <MyItemPermissionModel>
}

Replace:

<MyOrganizationId> by the actual ID of the target Coveo Cloud organization (see Retrieving the ID of a Coveo Cloud V2 Organization).
<MySourceId> by the actual ID of the target Push source. See:
- Creating a Push Source.
- Retrieving the ID of a Source.
<MyItemURI> by the URL-encoded URI of the item to add or update in the target Push source (e.g., file%3A%2F%2Ffolder%2FdummyItem.html).

If you are using the compressedBinaryData or the compressedBinaryDataFileId request body property to push item data, also replace:

<MyCompressionType> by the actual compression algorithm that was applied to the item data (UNCOMPRESSED, DEFLATE, GZIP, LZMA , or ZLIB).

The compressionType values are case sensitive.

Otherwise, you do not need to include the compressionType parameter in your query string.
<MyAccessToken> by an access token that grants the Organization - View and Sources - View/Edit privileges in the target Coveo Cloud organization. See:
<MyItemMetadata> by any number of arbitrary metadata key-values you want to include with the item you are adding or updating in the target Push source (see Understanding Push Source Item Metadata).
<MyItemDataProperty> by the property you want to use to push the item data (data, compressedBinaryData, or compressedBinaryFileId). Also replace <MyItemDataOrFileId> accordingly (see Pushing Item Data).
<MyItemDataFileExtension> by the actual file extension which the Push API should use to interpret the item data (e.g., .txt, .html, etc.). This value must include a preceding dot (.) character.

Although doing so is optional, you should generally specify a fileExtension.

If you want to establish a parent-child relationship between the item and other items in the same Push source, also replace:

<MyItemParentId> with the @documentId of the parent item, or by the @documentId of the item your are adding or updating if this item itself is the parent (see Understanding the parentId Property).

Otherwise, you do not need to include the parentId property in your request body.

If the target Push source is secured, also replace:

<MyItemPermissionModel> by valid a valid permission model for the pushed item. See:
- PermissionSetsModel / Simple Permission Model Definition Examples
- PermissionLevelsModel / Complex Permission Model Definition Example
Otherwise, you do not need to include the permissions property in your request body.

You should never use this operation repetitively to add or update many items in a Push source (i.e., to perform a large scale content update). When this is what you need to do, you should use the batch operation instead (see Managing Batches of Items in a Push Source).

A successful response (202 Accepted) indicates that the operation was successfully forwarded to the service and that the item is now enqueued to be processed by the document processing manager (DPM).

This does not imply that the item was successfully added or updated in the target Push source (see Understanding the Push API Processing Delay).

Update the status of your Push source

If you set your Push source to an active status before, you should consider setting it back to the IDLE status once this operation has successfully returned, assuming you have no more operations to perform as part of this content update (see Updating the Status of a Push Source).

Sample Request

Pushing a secured item whose data was previously uploaded to a file container

PUT https://push.cloud.coveo.com/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mycoveocloudv2organizationg8tp8wu3-rp5rxzbdz753uhndklv2ztkfgy/documents?documentId=file%3A%2F%2Ffolder%2FdummyItem.html&compressionType=Deflate HTTP/1.1
 
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "date": "2017-11-08T12:18:41.666Z",
  "documenttype": "HTML",
  "filename": "dummyItem.html",
  "isfrequentlyupdated": true,
  "language": [
    "English"
  ],
  "permanentid": "my9837423dummy2039482permanent234id",
  "sourcetype": "Push",
  "title": "My Dummy Item",
  "compressedBinaryDataFileId": "b5e8767e-8f0d-4a89-9095-1127915c89c7",
  "parentId": "file://myParentDummyItem.html",
  "permissions": [
    {
      "allowAnonymous": false,
      "allowedPermissions": [
        {
          "identity": "SampleTeam1",
          "identityType": "Group",
        },
        {
          "identity": "SampleGroup1",
          "identityType": "VirtualGroup"
        }
      ],
      "deniedPermissions": [
        {
          "identity": "bjones@example.com",
          "identityType": "User"
        }
      ]
    },
    {
      "allowAnonymous": false,
      "allowedPermissions": [
        {
          "identity": "emitchell@example.com",
          "identityType": "User"
        }
      ]
    }
  ]
}

Successful Response - 202 Accepted

null