--- title: Add or update a single item in a Push source slug: '133' canonical_url: https://docs.coveo.com/en/133/ collection: index-content source_format: adoc --- # Add or update a single item in a Push source :figure-caption!: Being able to add or update a single [item](https://docs.coveo.com/en/210/) in a Push [source](https://docs.coveo.com/en/246/) 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 illustrating the handling of an `Add or update an item` Push API request (highlighted) as it progresses through the [Coveo indexing pipeline](https://docs.coveo.com/en/1893/).** ![Sequence diagram for PUT documents request](https://docs.coveo.com/en/assets/images/index-content/put-documents-sequence-diagram.svg) ## 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](https://docs.coveo.com/en/210/) in a public content Push [source](https://docs.coveo.com/en/246/). Refer to the following `Add or update an item` HTTP request template and sample to add an item to your public content Push source. ### Request template **US East region** [%collapsible%open] #### [source,http,subs=attributes] ``` PUT https://api.cloud.coveo.com/push/v1/organizations//sources//documents?documentId=&compressionType= HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ``` #### .Canada region

Details

[source,http,subs=attributes] ``` PUT https://api-ca.cloud.coveo.com/push/v1/organizations//sources//documents?documentId=&compressionType= HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ```

**Ireland region**

Details

[source,http,subs=attributes] ``` PUT https://api-eu.cloud.coveo.com/push/v1/organizations//sources//documents?documentId=&compressionType= HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ```

**Australia region**

Details

[source,http,subs=attributes] ``` PUT https://api-au.cloud.coveo.com/push/v1/organizations//sources//documents?documentId=&compressionType= HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ```

Request parameters: **Parameters**

Details

In the request path: * Replace `` with your [organization ID](https://docs.coveo.com/en/148/). * Replace `` with the [ID](https://docs.coveo.com/en/3390#copy-a-source-name-or-id) of the target public [Push source](https://docs.coveo.com/en/94/). In the query string: * Replace `` 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 `` with a Push source API key that grants the [set of privileges required to push items](https://docs.coveo.com/en/1546#api-key) to your source.

Request body: ```json { "data": } ``` **Parameters**

Details

Replace `` 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](https://docs.coveo.com/en/63#request-size-limits). You must properly escape reserved JSON characters (for example, newline, tab, double quote, backslash, etc.) in your [`data` string](https://docs.coveo.com/en/31/).

Dummy item

This is dummy raw textual item data

" } ``` ## Add or update a complex secured item After you [create a secured Push source](https://docs.coveo.com/en/1546#content-security-tab) and set up a [security identity provider for your secured Push source](https://docs.coveo.com/en/85/), you can use the Push API to add a raw text [item](https://docs.coveo.com/en/210/) with access permissions to your [source](https://docs.coveo.com/en/246/). > **Leading practice: Perform a security identity update** > > Whenever you're about to add or update content in a secured content Push source, you should perform a [security identity update](https://docs.coveo.com/en/244/) on the [security identity provider](https://docs.coveo.com/en/242/) to ensure that the [security identities](https://docs.coveo.com/en/240/) referenced in item [permission models](https://docs.coveo.com/en/225/) are up to date in the [security identity cache](https://docs.coveo.com/en/241/). > For more information, see [Manage security identities in a security identity provider](https://docs.coveo.com/en/132/). Use the following `Add or update an item` HTTP request template and sample to add a secured item with some [metadata](https://docs.coveo.com/en/218/) to your secured content Push source. ### Request template **US East region** [%collapsible%open] #### [source,http,subs=attributes] ``` PUT https://api.cloud.coveo.com/push/v1/organizations//sources//documents?documentId=&compressionType= HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer ``` #### .Canada region

Details

**Ireland region**

Details

**Australia region**

Details

Request parameters: **Parameters**

Details

In the request path: * Replace `` with your [organization ID](https://docs.coveo.com/en/148/). * Replace `` with the actual [ID](https://docs.coveo.com/en/3390#copy-a-source-name-or-id) of the target [Push source](https://docs.coveo.com/en/94/). In the query string: * Replace `` 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 `` with the actual compression algorithm that was applied to the item data (`UNCOMPRESSED`, `DEFLATE`, `GZIP`, `LZMA` , or `ZLIB`). 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 `` with a Push source API key that grants the [set of privileges required to push items](https://docs.coveo.com/en/1546#api-key) to your source.

Request body: ```json { , : , "fileExtension": , "parentId": , "permissions": } ``` **Parameters**

Details

* Replace `` with any number of arbitrary [metadata key-values](https://docs.coveo.com/en/115/) you want to include with the item you're adding or updating in the target Push source. * Replace `` with the property you want to use to push the item data (`data`, `compressedBinaryData`, or `compressedBinaryFileId`). * Replace `` accordingly (see [Pushing item data](https://docs.coveo.com/en/73/)). * (Leading practice) Replace `` 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 `` 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](https://docs.coveo.com/en/57/) for details on parent-child relationships between items. * If the target Push source is secured, replace `` with a valid permission model for the pushed item. See: ** [Push API reference - Item permission models](https://docs.coveo.com/en/78#simplified-permission-model) ** [Simplified permission model](https://docs.coveo.com/en/107/) ** [Complete permission model](https://docs.coveo.com/en/25/)

Successful response: `202 Accepted` 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)](https://docs.coveo.com/en/191/). This doesn't imply that the item was successfully added or updated in the target Push source. See [About the Push API processing delay](https://docs.coveo.com/en/32/) for details. > **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](https://docs.coveo.com/en/35/), assuming you have no more requests to perform as part of this content update. > **Important** > > To maximize efficiency and comply with [API consumption limits](https://docs.coveo.com/en/63/), 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](https://docs.coveo.com/en/90/) instead. ### Sample request The following example shows how to push a secured item whose data was previously uploaded to a file container. ```http 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: ```json { "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" } ] } ] } ```