Add or update a single item in a Push source

This is for:

In this article

Add or update a basic public item
Add or update a complex secured item

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

This article provides an overview of the Add or update an item HTTP request, with details and examples for basic and more complex cases.

Sequence diagram for PUT documents request

Sequence diagram illustrating the handling of an Add or update an item Push API request (highlighted) as it progresses through the Coveo indexing pipeline.

Add or update a basic public item

One of the most rudimentary requests you can perform with the Push API is to add or update a single, uncompressed, raw textual item in a public Push source.

Refer to the following Add or update an item HTTP request template and sample to add an item to your public Push source.

Request template

PUT https://api.cloud.coveo.com/push/v1/organizations/<MyOrganizationId>/sources/<MySourceId>/documents?documentId=<MyItemURI> HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer <MyAccessToken>

Parameters

In the request path:

Replace <MyOrganizationId> with the ID of the target Coveo organization (see Retrieving the ID of a Coveo organization).
Replace <MySourceId> with the ID of the target public Push source (see Create a Push source).

In the query string:

Replace <MyItemURI> with the URL-encoded URI of the public item to add or update in the target public Push source (for example, file%3A%2F%2Ffolder%2FdummyItem.html).

In the Authorization HTTP header:

Replace <MyAccessToken> with a Push source API key that grants the set of privileges required to push items to your source.

Request body:

{
  "data": <MyItemData>
}

Parameters

Replace <MyItemData> with the raw textual data corresponding to the public item to add or update in the target public Push source (for example, "This is a sample raw textual \"Data\" string.").

Your total request body size must not exceed 6 MB (see Push API limits - Request size limits).

You must properly escape reserved JSON characters (for example, newline, tab, double quote, backslash, etc.) in your data string (see Using the data property).

Successful response: 202 Accepted

null

A successful response 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).

To maximize efficiency and comply with API consumption limits, don’t use this request repeatedly to add or update many items in a Push source (that is, to perform a large scale content update). Use batch update requests instead.

Sample request

The following example shows how to push an item whose raw textual data is HTML formatted.

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mycoveocloudv2organizationg8tp8wu3-rp5rxzbdz753uhndklv2ztkfgy/documents?documentId=file%3A%2F%2Ffolder%2FdummyItem.html HTTP/1.1

Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Request body:

{
  "data": "<html><body><h1>Dummy item</h1><p>This is dummy raw textual item data</p></body></html>"
}

Add or update a complex secured item

After you create a secured Push source and set up a security identity provider for your secured Push source, you can use the Push API to add a raw text item with access permissions to your source.

Leading practice: Perform a security identity update

Whenever you’re about to add or update content in a secured Push source, you should perform a security identity update on the security identity provider to ensure that the security identities referenced in item permission models are up to date in the security identity cache (see Manage security identities in a security identity provider).

Use the following Add or update an item HTTP request template and sample to add a secured item with some metadata to your secured 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>

Parameters

In the request path:

Replace <MyOrganizationId> with the actual ID of the target Coveo organization (see Retrieve the organization ID).
Replace <MySourceId> with the actual ID of the target Push source.

In the query string:

Replace <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, replace <MyCompressionType> with the actual compression algorithm that was applied to the item data (UNCOMPRESSED, DEFLATE, GZIP, LZMA , or ZLIB). compressionType values are case sensitive. If you’re not using the compressedBinaryData or the compressedBinaryDataFileId request body properties, don’t include the compressionType parameter in your query string.

In the Authorization HTTP header:

Replace <MyAccessToken> with a Push source API key that grants the set of privileges required to push items to your source.

Request body:

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

Parameters

Replace <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).
Replace <MyItemDataProperty> with the property you want to use to push the item data (data, compressedBinaryData, or compressedBinaryFileId).
Replace <MyItemDataOrFileId> accordingly (see Pushing item data).
(Leading practice) Replace <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.
Optionally, to establish a parent-child relationship between the item and other items in the same Push source, 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).
If the target Push source is secured, replace <MyItemPermissionModel> with a valid permission model for the pushed item.

See:

Successful Response: 202 Accepted

null

Leading practice: 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, assuming you have no more requests to perform as part of this content update (see Updating the status of a Push source).

To maximize efficiency and comply with API consumption limits, don’t use this operation repetitively to add or update many items in a Push source (that is, to perform a large scale content update). Use the batch operation instead.

Sample request

The following example shows how to push 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 **********-****-****-****-************

Request body:

{
  "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"
        }
      ]
    }
  ]
}