Skip To Content
ArcGIS Developer

/addItem: Add Item

  • URL:https://[root]/content/users/[userName]/addItem(POST only)

Example usage

URL for Add Item
title=My Mapping Application
type=Web Mapping Application
tags=web, mapping, application


The Add Item operation (POST only) is used to upload an item file, submit text content, or submit the item URL to the specified user folder depending on documented items and item types. This operation is available only to the specified user.

The request to upload an item file must be a multipart request pursuant to IETF RFC1867. The request to submit text content or a URL can be a standard HTTP POST request.

The user owning the folder automatically becomes the owner of the item. The item is flagged as private (that is, not shared with any group) by default. This can be changed using the Share Item operation. The added item is available to everyone it's shared with at the item resource. The item is also available to the owner at the user item resource, which supports operations to update, delete, move, share, and unshare items.

The filename or URL used for an item must be unique within the particular user's folder.

The addItem operation allows users to optionally create a relationship and share an item in one call. See Add Relationship for parameter information. The same rules apply, with the following exceptions:

  • If you specify an originItemId, the new item is added as the destination item.
  • If you specify a destinationitemId, the new item is added as the origin item.
  • If you specify both, an error is thrown.
  • The destination item will inherit all the sharing permissions of the origin item.

The relationship creation is done after the item is created. If the item isn't added correctly, no relationship is created. However, if the item is added correctly, but the relationship fails (that is, it's a bad relationship type, invalid origin or destination item, and so on), the item is deleted.

Asynchronous Uploads

For large file uploads, which take a long time to process, items can be added asynchronously. In this mode, the client checks back with the server on the status of the processing. To invoke the asynchronous mode, the extra parameter of async=true is used with the addItem operation.

  • After the file is uploaded, the server returns the ID of the item. The server then processes the file. The response is the same as a synchronous addItem call.
  • Status can be checked using the status call and has three possible states: processing, completed, or failed. Completed is returned when processing is finished.
  • The status output looks like this:
      "status": "processing",
      "statusMessage": "processing",
      "itemId": "ddb1838f5a76478894698d371be3a2b6"
  • A status error message looks like this:
      "status": "failed",
      "statusMessage": "Item '' already exists. Set the 'overwrite' flag to true if you want to overwrite."
      "itemId": "ddb1838f5a76478894698d371be3a2b6"

Multipart Uploads

Large files can also be uploaded in parts from a client who has the ability to split files into smaller parts.

To initiate a multipart upload, the client passes in the multipart=true parameter to this addItem operation along with the filename. In multipart mode, those are the only two parameters needed, and all others will be ignored.

Once the multipart update is initiated, the Add Part operation is used to upload each part of a file, and finally the Commit operation is used to complete the upload.

No item properties can be passed into the multipart call. If the uploaded file is not a package that includes item information (see additional details in the next section), then an Update Item call must be made to update the item's information.

Item Info

If the item is an uploaded ZIP file or an ArcGIS package and if it contains an esriinfo folder, then all files and subfolders in the esriinfo folder will be extracted and available through the item info file URLs.

For instance, if the structure of the uploaded file is as follows:

Zip file (*.mpk, *.lpk)
 |-- esriinfo (folder)
           |-- iteminfo.xml (item card)
                     |-- subfolder
                               |-- thumbnail.jpg

the iteminfo.xml file is available at the following URL:


And similarly, thumbnail.jpg is available at the following URL:


Further, iteminfo.xml represents the "item card". Users can provide some basic information for the item, such as name, title, thumbnail, and so on, in this file. If you specify the thumbnail and documentation properties in this item card, they should be paths relative to the esriinfo folder. In the above case, the thumbnail should be specified as follows:


You do not need to bundle this information with the file that you upload. This information can be submitted as query parameters, such as name, title, and so on, along with the file or URL parameters. Additionally, this information can be specified using the Update Item operation.

Request parameters

[Common Parameters]

For a complete listing, see Common parameters.


The file to be uploaded. If uploading a file, the request must be a multipart request.


The URL where the item can be downloaded. The resource will be downloaded and stored as a file type. Similar to uploading a file to be added, but instead of transferring the contents of the file, the URL of the data file is referenced and creates a file item.

Please see the implementation details section below which discusses this parameter in further details.


The URL of the item to be submitted. The URL can be a URL to a service, a web mapping application, or any other content available at that URL.



The JSON content for the item to be submitted.



The type of relationship between the two items. See Relationship types for a complete listing of types.



The item ID of the origin item of the relationship.



The item ID of the destination item of the relationship.


If true, the file is uploaded asynchronously. If false, the file is uploaded synchronously. The default is false.

Values: true | false


If true, the file is uploaded in multiple parts. See the Multipart Uploads section above for more information.

Values: true | false


The filename being uploaded in multipart mode. Required if multipart is true.

Values: true | false


A JSON object that provides rate limiting and referrer checks when accessing secured services.



If true, a service URL is added as a proxy item without embedding credentials. It can be used to take advantage of the portal sharing model for security, hide actual service URLs, rate limiting and referrer checks, etc.

Values: true | false


New at 10.8.1. The item ID of the item. The item ID must not exist and must be 32 alphanumeric values.


itemIdToCreate applies to ArcGIS Enterprise Portal only.


[Item Info Parameters]

For a complete listing of all item info parameters, see Item parameters.

Implementation details for using the dataURL parameter

  • The referenced dataUrl, has to be an unsecured URL where data can be downloaded.
  • This operation is asynchronous, therefore the client should check the item's status before using. If the status is "completed", the resource is downloaded and the file item is added successfully.
  • If the resource supports Byte Ranges and the content length is larger than 500kb, Range GET's are used to download the file in parts.
  • Multiple parallel threads download the file parts and perform a file-based merge on them. This is not performed in-memory as to avoid buffering. If a part can't be downloaded, it attempts once more before failing. All parts needs to be downloaded successfully before the item can be created.
  • If overwrite=true an existing file is updated.

Service Proxy parameters

ArcGIS Online and ArcGIS Enterprise portal users can register premium services, as well as services published on their own server, as secured service proxies. If working with secured services, you have the option to save the username and password credentials directly with the item. Setting the serviceProxyParams provides additional control over how these services are accessed by supplying rate limiting and referrer checks. In other words, by setting these parameters, you provide more control over who can access these services and how much they can use them.

The serviceProxyParams JSON object used to set rate limiting and referrer checks on secured services is described below.


Number of requests that will be allowed within a specified time interval of intervalInSeconds. Default value is "2".


Integer value indicating the interval time in seconds. Default value is "60".


Array of referrers allowed to access service.

If rate limit is exceeded, an error will occur.

  "error": {
    "code": 429,
    "messageCode": "CONT_0049",
    "message": "Rate limit exceeded. Please try again later.",
    "details": []

Both hitPerInterval and IntervalSeconds need to be greater than zero (0) in order for rate limiting to work.

A sample serviceProxyParams JSON object is as follows:

  "referrers":["https://server1","https://server2"],"https://*]  //* allows any subdomain from to be added

Response properties


Indicates if the operation was successful.


The ID of the created item.


The folder in which the item was created.


URL for Add Item
title=My Mapping Application
type=Web Mapping Application
tags=web, mapping, application

dataUrl for Add Item - this example shows adding a reference to a CSV file

tags=restaurants, web

Adding a datastore item to a portal with the datastore's JSON information
Parameters (datastore JSON information formatted in pJSON)
  "info": {
    "isManaged": false,
    "connectionString": {
      "accessKeyId": "example_input_key",
      "secretAccessKey": "secret_key",
      "region": "cn-east-2",
      "defaultEndpointProtocol": "https",
      "credentialType": "accesskey"
    "objectStore": "bucketName/folderName"
  "path": "/cloudStores/storeName",
  "provider": "Huawei"
type=Data Store

JSON Response syntax

  "success": true | false,
  "id": "<item id>",
  "folder": <folder id>

JSON Response example

  "success": true,
  "id": "17dd19b627b74068a6f3292c7ae0d88a",
  "folder": null