Add or Update a Single Item in a Push Source

This is for:

In this article

Sample Request

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

This article provides an overview of the PUT /sources/{sourceId}/documents HTTP request.

Sequence diagram for PUT documents request

Sequence diagram illustrating the handling of a PUT /sources/{sourceId}/documents Push API request (highlighted) as it progresses through the Coveo indexing pipeline.

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 Manage security identities in a security identity provider).

Use the PUT /sources/{sourceId}/documents HTTP request 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://api.cloud.coveo.com/push/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> with the actual ID of the target Coveo organization (see Retrieve the organization ID).
<MySourceId> with the actual ID of the target Push source.
<MyItemURI> with the URL-encoded URI of the item to add or update in the target Push source (for example, file%3A%2F%2Ffolder%2FdummyItem.html).

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

<MyCompressionType> with 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 don’t need to include the compressionType parameter in your query string.
<MyAccessToken> with an access token that grants the Sources - Edit privilege on the target source, if not already done. See:
<MyItemMetadata> with any number of arbitrary metadata key-values you want to include with the item you’re adding or updating in the target Push source (see About Push Source Item Metadata).
<MyItemDataProperty> with the property you want to use to push the item data (data, compressedBinaryData, or compressedBinaryFileId). Also replace <MyItemDataOrFileId> accordingly (see Pushing Item Data).
<MyItemDataFileExtension> with the actual file extension which the Push API should use to interpret the item data (for example, .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 About the parentId Property).

Otherwise, you don’t need to include the parentId property in your request body.

If the target Push source is secured, also replace:

<MyItemPermissionModel> with valid a valid permission model for the pushed item. See:
- PermissionSetsModel / Simple Permission Model Definition Examples
- PermissionLevelsModel / Complex Permission Model Definition Example
Otherwise, you don’t 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 (that is, to perform a large scale content update). When this is what you need to do, you should use the batch operation instead (see Manage 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 doesn’t imply that the item was successfully added or updated in the target Push source (see About 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://api.cloud.coveo.com/push/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