Add or update a single item in a Push source

This is for:

Developer System Administrator

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

This article provides an overview of the PUT /sources/{sourceId}/documents HTTP request, with details and examples for basic and more complex cases.

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.

Add or update a basic public item

One of the most rudimentary operations 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 PUT /sources/{sourceId}/documents HTTP request template and sample to add an item to your public Push source.

Request template

Request definition

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:

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:

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).
Important

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 that’s what you need to do, you should use the batch operation instead (see Manage batches of items in a Push source).

Sample request

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

Request definition

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

Successful response - 202 Accepted

null

Add or update a complex secured item

Assuming that you’ve created a secured Push source, along with a security identity provider for your secured Push source, you can then use the Push API to add a raw text item with access permissions to your source.

Tip
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).

Refer to the following PUT /sources/{sourceId}/documents HTTP request template and sample to add a secured item with some metadata to your public Push source.

Request template

Request definition

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:

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:

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.

  • (Optional) If you want 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:

See Item models - DocumentBody for the complete list of properties you can include in the request body.

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).
Tip
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 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).
Important

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

Sample request

The following example shows how to push a secured item whose data was previously uploaded to a file container.

Request definition

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

Successful Response - 202 Accepted

null