Skip To Content
ArcGIS Developer
Dashboard

/addItem: Add Item

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

Example usage

Note:

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 following is a sample ArcGIS Online POST request for the addItem operation:

POST /sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: org.arcgis.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

url=https://www.mymappingapplication.com&title=My Mapping Application&type=Web Mapping Application&tags=web, mapping, application&f=pjson

The following is a sample ArcGIS Enterprise POST request for the addItem operation:

POST /webadaptor/sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

url=https://www.mymappingapplication.com&title=My Mapping Application&type=Web Mapping Application&tags=web, mapping, application&f=pjson

Description

The addItem operation allows a user 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.

Note:

When submitting the item to a specified user folder, the user who owns the folder automatically becomes the owner of the item. The item is flagged as private by default, and will not be shared with any group. This can be changed using the Share Item operation. Once shared, the added item is available at the item resource level. This item is also available to the owner at the user item resource level, which supports the Update, Delete, Move, Share, and Unshare items operations. The file name or URL used for an item must be unique within the particular user's folder.

This operation is available only to the specified user. This operation also allows users to optionally create a relationship and share an item in one call. 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 returned.
  • The destination item will inherit all the sharing permissions of the origin item.

The relationship creation is finished 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.

Additional considerations

The following sections outline additional behaviors or features for the addItem that should be considered before performing this operation

Asynchronous uploads

Large files take a long time to process when uploaded. Rather than processing the request to add an item synchronously, this operation can be performed asynchronously. In this mode, the client checks back with the server for the job's status. To utilize asynchronous mode, the async parameter should be set to true. Once the request is submitted, the JSON response will return the item ID of the added item, as well as the request's current status and status message:

{
  "status": "processing",
  "statusMessage": "processing",
  "itemId": "ddb1838f5a76478894698d371be3a2b6"
}

The status can be checked using the Status operation. When polled, the status can return as one of three possible states: processing, completed, or failed. The status message will return information relevant to the job's current status. For example, the status message below details why the request failed:

{
  "status": "failed",
  "statusMessage": "Item 'mexicoWebMercator.sd' already exists. Set the 'overwrite' flag to true if you want to overwrite."
  "itemId": "ddb1838f5a76478894698d371be3a2b6"
}

Multipart uploads

Clients that have the ability to split large files into smaller parts can utilize multipart uploads. To initiate a multipart upload, the multipart parameter should be set to true. When uploading multiple file parts, only the multipart and filename parameters are required. All other parameters will be ignored. Once the multipart upload has been initiated, the Add Part operation is used to upload each part of the file, which are then committed 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, the Update Item operation must be called to update the item's information.

Item information

If the item is an uploaded .zip file, or an ArcGIS package, and it contains an esriinfo folder, all files and subfolders in the esriinfo folder will be extracted and available through the Item Info File resource. To demonstrate, the example below represents the structure of an uploaded .zip file:

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

The iteminfo.xml in the structure above will be available from the Item Info File resource:

https://machine.domain.com/webadaptor/sharing/rest/content/items/[itemID]/info/iteminfo.xml

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

<ESRI_ItemInformation>
   ...
   <thumbnail>subfolder/thumbnail.jpg</thumbnail>
   ...
</ESRI_ItemInformation>

However, you do not need to bundle this information with the file at the time of uploading. This information can be submitted as query parameters (such as name and title) along with the file or url parameters. This information can also be specified using the Update Item operation.

In addition to thumbnail information being returned in the iteminfo.xml file, the thumbnail file is available at the following location:

https://server/sharing/rest/content/items/<itemId>/info/<subfolder>/thumbnail.jpg

Request parameters

ParameterDetails
file

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

dataUrl

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. The referenced URL must be an unsecured URL where the data can be downloaded. This parameter requires the operation to be performed asynchronously. Once the job status returns as complete, the item can be downloaded and the item is added successfully.

If the item supports Byte Ranges, and the content length is larger than 500kb, a Range GET is 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 in order to avoid buffering. If a part cannot be downloaded, the system will attempt once more before failing. All parts must be downloaded successfully before the item can be created.

Note:

If overwrite is true, an existing file is updated.

url

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.

Example

url=https://server.arcgisonline.com/ArcGIS/rest/services/ESRI_Imagery_World_2D/MapServer
text

The JSON content for the item to be submitted.

Example

text={'myAttribute':'myValue'}
relationshipType

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

Example

relationshipType=WMA2Code
originItemId

The item ID of the origin item of the relationship.

Example

originItemId=bb297e5eac6d489e85993d5e4d4e4a20
destinationItemId

The item ID of the destination item of the relationship.

destinationItemId=8d292f9b0cd5457bbdad84c02223ffb8
multipart

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

Values: true | false

filename

The file name being uploaded in multipart mode. Required if multipart is true.

Values: true | false

serviceProxyParams

A JSON object that provides rate limiting and referrer checks when accessing secured services. For more information on serviceProxyParams properties, see the Service proxy properties section below.

Example

serviceProxyParams={"hitsPerInterval":2,"intervalSeconds":60,"referrers":["https://<servername>"]}
createAsServiceProxy

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, for rate limiting, for referrer checks, and so on.

Values: true | false

itemIdToCreate

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

Note:

itemIdToCreate applies only to ArcGIS Enterprise.

Example

itemIdToCreate=832157e321df46f721f9ededbe34ac58
title

The title of the item. This is the only name that users and applications use for the item. There is no concept of display names or aliases in the Sharing API.

Example

title=Landmarks
thumbnail

The pathname to the thumbnail image to be used for the item. For best results, images that are 600 x 400 pixels or larger with an aspect ratio of 1.5:1 are recommended. Supported file formats are PNG, GIF, and JPEG with a maximum file size of 10 MB. This will not be a reference to the file but the file itself that is stored on the sharing servers.

Item thumbnail can be retrieved at different dimensions by specifying a URL parameter w for the desired image width:

Example

https://www.arcgis.com/sharing/rest/content/items/[itemid]/info/thumbnail/thumbnail.png?w=400

Supported retrievable thumbnail widths for item are 200 pixels (default), 400 pixels, 800 pixels, and 2400 pixels, with an aspect ratio of 1.5:1. Other specified sizes will be snapped to the next highest supported dimension for query. If the original image dimension is smaller than the size queried, the original image will be returned.

Example

thumbnail=subfolder/thumbnail.jpg
thumbnailurl

The URL to the thumbnail image to be used for the item. The recommended image size is 200 x 133 pixels. Acceptable image formats are PNG, GIF, and JPEG. The maximum file size for an image is 1 MB.

Example

thumbnailurl=https://server/arcgis/subfolder/thumbnail.jpg
metadata

The file that stores the metadata information on an item. It's stored in the metadata folder under esriinfo, for example, /sharing/rest/content/items/<itemid>/info/metadata/metadata.xml.

Example

metadata=metadata.xml
metadataEditable

Indicates if the organization has metadata enabled. If true, all members of the organization can view the metadata. Only item owners and administrators can update metadata. If false, no one in the organization can access the metadata.

Values: true | false

metadataFormats

Metadata style used for organization. The default style is iso19139.

Values: fgdc | inspire | iso19139 | iso19139-3.2 | iso19115

type

The type of the item. Must be drawn from the list of supported types. See Items and item types for a list of the supported types.

Example

type=Web Mapping Application
typeKeywords

Adds additional type keywords to the item. Type keywords describe the type and should logically apply to all items of that type. Type keywords can be applied to any type of item, including hosted feature services. See Items and item types for a list of the different predefined type keywords that will be automatically added based on the supplied type.

Syntax

typeKeywords=<keyword1>, <keyword2>

Example

typeKeywords=Static
description

An item description less than 64 Kb.

Example

description=This application represents point locations within the United States and Canada for common institution landmark types including hospitals, educational institutions, religious institutions, government centers, and cemeteries.
tags

A comma-delimited list of tags for the item. Tags are words or short phrases that describe the specific item.

Syntax

tags=<tag1>, <tag2>

Example

tags=landmarks, United States, Canada
snippet

Snippet or summary for the item. Limit this brief descriptive text to 2048 characters.

Example

snippet=Landmarks in United States and Canada.
extent

The item's bounding rectangle.

Example

extent=<xmin>, <ymin>, <xmax>, <ymax>

Example

extent=-110.05, 44.13, -110, 44.98
spatialReference

The coordinate system of the item.

Example

spatialReference=GCS_North_American_1983
accessInformation

Credits the source of the item.

Example

accessInformation=Copyright:© 2008 ESRI, AND, TANA, ESRI Japan, UNEP-WCMC
licenseInfo

Includes any license information or restrictions.

Example

licenseInfo=This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License
culture

The item locale (language and country) information. If the added item is a package, the culture parameter in the ESRI_ItemInformation tag is read and used if available. If the culture is not specified by the user, or not provided in the package, the culture is set using the Accept-Language HTTP header sent by the browser. If the browser does not provide a locale, no default is set. The record will have no locale, and it will not be indexed under a certain language or country.

The format for a culture code is based on a language code and country code, separated by a dash. The language code is based on the two-letter codes found at Library of Congress' Codes for the Representation of Names of Languages. The country code is based on the two-letter codes found by searching the ISO Online Browsing Platform.

properties

A JSON object that primarily applies to system requirements, Terms and Conditions, version, supported platforms, YouTube video ID, etc associated with the application.

appCategories

An array that primarily applies to a list of categories that the application item is applicable to.

industries

An array that primarily applies to industries associated with the application.

languages

An array that primarily applies to languages associated with the application.

largeThumbnail

The URL to the thumbnail used for the application. This parameter primarily applies to thumbnail associated with an application.

banner

The URL to the banner used for the application. This parameter primarily applies to the banner associated with an application.

screenshot

The URL to the screenshots used for the application. This parameter primarily applies to screenshots associated with an application.

listingProperties

A JSON object consists of listing properties when the item is listed in ArcGIS Marketplace. For information on the listingProperties properties, see the Listing properties section below.

{
  "licenseType": "<free | ela | consumption | preprovisioned>",
  "listingAccess": "<private | public>",
  "priceDesc": "<priceDesc>",
  "creditsPerTransaction": <creditsPerTransaction>,
  "trialSupported": <true | false>,
  "trialDuration": <trialDuration>,
  "ecommerceEnabled": <true | false>,
  "licenseBy": <licenseByOrg | licenseByUser>
}
serviceUsername

Set the username on a secure on-premise ArcGIS Server service. It is valid on Map Services, Feature Services and Image Services only.

Example

serviceUsername = myuser1
servicePassword

Set the password on a secure on-premise ArcGIS Server service. It is valid on Map Services, Feature Services, and Image Services only.

Example

servicePassword = mypassword1
serviceProxyFilter

A JSON object with category, sourceCountry and searchExtent properties that is used to restrict service item response results based on specified filter, such as limit results returned from a geocode service based on defined filters. This parameter is only applicable to Geocoding Service type items. The three properties can be used independently or in any combination. When combined, they are applied as an Boolean AND operator.

Syntax

{
  "sourceCountry": "<country>",//2- or 3-digit country code supported by the Geocoding service
  "searchExtent": {<extent object}, //A JSON envelope object used to limit the geocode to a specific search area
  "category": "<category,category>" //A comma-delimited list of one or more categories from the geocoding service
}

Example

{
  "sourceCountry": "USA",
  "searchExtent": {
    "xmin": -13184700,
    "ymin": 3988556,
    "xmax": -13004945,
    "ymax": 4061479,
    "spatialReference": {
      "wkid": 102100
    }
  }
}

//or 
{
  "category": "MGRS"
}
categories

A JSON array or comma separated list of categories to add to the item.

Example

["/Categories/Basemaps", "/Categories/Transportation"]

//or

/Categories/Basemaps, /Categories/Transportation
async

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

Values: true | false

f

The response format. The default format is html.

Values: html | json | pjson

Listing properties

A listing is specified as a JSON object. Its syntax and properties are as follows:

PropertyDetails
licenseType

The type of license offered by the listing. The free value specifies whether the listing will be provisioned to the customer for free. The ela value specifies whether an Enterprise Level Agreement needs to be agreed upon between the vendor and the customer. The consumption value specifies a consumption-based model, which typically applies to data services. The preprovisioned value specifies whether the item is preprovisioned and ready to use.

Values: free | ela | consumption | preprovisioned

listingAccess

Indicates whether the listing is public or private.

Values: public | private

priceDesc

Text that describes the pricing details of this listing. This property is not required for free listings.

creditsPerTransaction

The number of credits that will be charged to the customer per transaction. This property only applies to consumption-based listings.

trialSupported

Indicates whether or not the listing supports trials.

Values: true | false

trialDuration

Duration of the trial (in days). This property only applies when trialSupported is true.

ecommerceEnabled

Indicates whether or not the listing is e-commerce enabled.

Values: true | false

licenseBy

Listing licensing model. The default is licenseByOrg if the property is missing.

Values: licenseByUser | licenseByOrg

Service proxy properties

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 limitations, 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.

PropertyDetails
hitsPerInterval

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

Note:

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

intervalSeconds

Integer value indicating the interval time in seconds. The default value is 60.

referrers

Array of referrers allowed to access service.

The example below demonstrates a sample serviceProxyParams JSON object:

{
  "hitsPerInterval":2,
  "intervalSeconds":60,
  "referrers":["https://server1","https://server2"],"https://*arcgis.com]  //*.arcgis.com allows any subdomain from arcgis.com to be added
}

When serviceProxyParams has been defined, if the rate limit is exceed an error message will be returned:

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

Additional example usage

Add a reference to a .csv file

The following examples for ArcGIS Online and ArcGIS Enterprise are sample POST requests that demonstrate using the addItem operation to add a reference to a .csv file.

ArcGIS Online:

POST /sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: org.arcgis.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

dataUrl=https://mysharedserver/CSV/restaurants.csv&title=Restaurants&type=CSV&tags=restaurants, web

ArcGIS Enterprise:

POST /webadaptor/sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

dataUrl=https://mysharedserver/CSV/restaurants.csv&title=Restaurants&type=CSV&tags=restaurants, web

Add item using the data store's information

The following example for ArcGIS Enterprise is sample POST requests that demonstrate adding a data store item to a portal with the data store's JSON information. The sample request below have been formatted for readability.

POST /webadaptor/sharing/rest/content/users/jsmith/addItem HTTP/1.1
Host: machine.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

https://machine.domain.com/webadaptorname/sharing/rest/content/users/jsmith/addItem&text={
  "type": "cloudstore",
  "info": {
    "isManaged": false,
    "connectionString": {
      "accessKeyId": "example_input_key",
      "secretAccessKey": "secret_key",
      "region": "us-west-2",
      "defaultEndpointProtocol": "https",
      "credentialType": "accesskey"
    },
    "objectStore": "bucketName/folderName"
  },
  "path": "/cloudStores/storeName",
  "provider": "amazon"
}&title=myCloudStore&type=Data Store

JSON Response properties

PropertyDetails
success

Indicates if the operation was successful

id

The ID of the created item

folder

The folder in which the item was created

JSON Response syntax

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

JSON Response example

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