Lists and list items REST API reference

Learn about lists, list items, views, and other list-related resources and endpoints in the REST API.

Applies to: apps for SharePoint | SharePoint Foundation 2013 | SharePoint Online | SharePoint Server 2013

In this article
About the request examples in this article
Explore the SharePoint 2013 lists and list items REST syntax
List resource
ListCollection resource
ListItem resource
ListItemCollection resource
View resource
ViewCollection resource
ViewFieldCollection resource
Additional resources

About the request examples in this article

The request examples in this article assume that you’re using the cross-domain library (SP.RequestExecutor.js) to make cross-domain requests, so they use SP.AppContextSite in the endpoint URI. See How to: Access SharePoint 2013 data from apps using the cross-domain library for more information.

Before you use a request example, do the following:

• Change <app web url>, <host web url>, and other placeholder data such as any IDs, names, or paths of SharePoint entities.

• If you’re not using the cross-domain library, include an X-RequestDigest header to send the form digest value in all POST requests and a content-length header for POST requests that send data in the request body.

• If you're not making cross-domain requests, remove SP.AppContextSite(@target) and ?@target='<host web url>' from the endpoint URI.

• If you’re using OAuth, include an Authorization header ("Authorization": "Bearer " + <access token>) to send the OAuth access token.

• Remove the line breaks from the url and body property values in the request examples. Line breaks are added to the examples to make them easier to read.

• If you want the server to return responses in Atom format, remove the "accept": "application/json; odata=verbose" header.

See Additional resources for links to more information about using the cross-domain library, OAuth, and the SharePoint REST service. See How REST requests differ by environment and Properties used in REST requests for information about request formats.

Tip

The SharePoint Online REST service supports combining multiple requests into a single call to the service by using the OData $batch query option. For details and links to code samples, see Make batch requests with the REST APIs. This option is not yet supported for on-premise SharePoint.

Explore the SharePoint 2013 lists and list items REST syntax

Visually explore the SharePoint 2013 lists and list items REST syntax. Explore other SharePoint REST syntax diagrams: Files and folders | Users and groups Download the combined PDF of all the SharePoint REST syntax diagrams.

Note

The OData $skip query option does not work when querying items of a particular list. It does work when querying the lists endpoint.

List resource

Represents a SharePoint list. A list is a type of SP.SecurableObject.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/web/lists(guid'<list id>')

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Request examples

GET request example: Get a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can use the GetByTitle method from the ListCollection resource to get a list by its title. Example: …/web/lists/getbytitle('Access Requests').

POST request example: Create a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100,
    'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test title' }",
  headers: { "content-type": "application/json;odata=verbose" },
  success: successHandler,
  error: errorHandler
});

MERGE request example: Change a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100,
    'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test title' }",
  headers: { 
    "IF-MATCH”: "*",
    "X-HTTP-Method": "MERGE",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "POST",
  headers: { 
    "IF-MATCH”: "*",
    "X-HTTP-Method": "DELETE"
  },
  success: successHandler,
  error: errorHandler
});

If you want to recycle a list and get the GUID of the recycle bin item, use the list's Recycle method to remove the file.

List properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
AllowContentTypes	Boolean	R	Yes	Gets a value that specifies whether the list supports content types.
BaseTemplate	Int32	R	Yes	Gets the list definition type on which the list is based. Represents a ListTemplateType value. See ListTemplateType in the .NET client object model reference for template type values.
BaseType	Int32	R	Yes	Gets the base type for the list. Represents an SP.BaseType value: Generic List = 0; Document Library = 1; Discussion Board = 3; Survey = 4; Issue = 5.
BrowserFileHandling	Int32	R	No	Gets a value that specifies the override of the web application's BrowserFileHandling property at the list level. Represents an SP.BrowserFileHandling value: Permissive = 0; Strict = 1.
ContentTypes	SP.ContentTypeCollection	R	No	Gets the content types that are associated with the list.
ContentTypesEnabled	Boolean	RW	Yes	Gets or sets a value that specifies whether content types are enabled for the list.
Created	DateTime	R	Yes	Gets a value that specifies when the list was created.
DataSource	SP.ListDataSource	R	No	Gets the data source associated with the list, or null if the list is not a virtual list. Returns null if the HasExternalDataSource property is false.
DefaultContentApprovalWorkflowId	GUID	RW	Yes	Gets or sets a value that specifies the default workflow identifier for content approval on the list. Returns an empty GUID if there is no default content approval workflow.
DefaultDisplayFormUrl	String	RW	No	Gets or sets a value that specifies the location of the default display form for the list. Clients specify a server-relative URL, and the server returns a site-relative URL
DefaultEditFormUrl	String	RW	No	Gets or sets a value that specifies the URL of the edit form to use for list items in the list. Clients specify a server-relative URL, and the server returns a site-relative URL.
DefaultNewFormUrl	String	RW	No	Gets or sets a value that specifies the location of the default new form for the list. Clients specify a server-relative URL, and the server returns a site-relative URL.
DefaultView	SP.View	R	No
DefaultViewUrl	String	R	No	Gets the URL of the default view for the list.
Description	String	RW	Yes	Gets or sets a value that specifies the description of the list.
Direction	String	RW	Yes	Gets or sets a value that specifies the reading order of the list. Returns "NONE", "LTR", or "RTL".
DocumentTemplateUrl	String	RW	Yes	Gets or sets a value that specifies the server-relative URL of the document template for the list. Returns a server-relative URL if the base type is DocumentLibrary, otherwise returns null.
DraftVersionVisibility	Int32	RW	Yes	Gets or sets a value that specifies the minimum permission required to view minor versions and drafts within the list. Represents an SP.DraftVisibilityType value: Reader = 0; Author = 1; Approver = 2.
EffectiveBasePermissions	SP.BasePermissions	R	No	Gets a value that specifies the effective permissions on the list that are assigned to the current user.
EffectiveBasePermissionsForUI	SP.BasePermissions	R	No
EnableAttachments	Boolean	RW	Yes	Gets or sets a value that specifies whether list item attachments are enabled for the list.
EnableFolderCreation	Boolean	RW	Yes	Gets or sets a value that specifies whether new list folders can be added to the list.
EnableMinorVersions	Boolean	RW	Yes	Gets or sets a value that specifies whether minor versions are enabled for the list.
EnableModeration	Boolean	RW	Yes	Gets or sets a value that specifies whether content approval is enabled for the list.
EnableVersioning	Boolean	RW	Yes	Gets or sets a value that specifies whether historical versions of list items and documents can be created in the list.
EntityTypeName	String	R	Yes
EventReceivers	SP.EventReceiverDefinitionCollection	R	No
Fields	SP.FieldCollection	R	No	Gets a value that specifies the collection of all fields in the list.
FirstUniqueAncestorSecurableObject	SP.SecurableObject	R	No	Gets the object where role assignments for this object are defined. If role assignments are defined directly on the current object, the current object is returned.
ForceCheckout	Boolean	RW	Yes	Gets or sets a value that indicates whether forced checkout is enabled for the document library.
Forms	SP.FormCollection	R	No	Gets a value that specifies the collection of all list forms in the list.
HasExternalDataSource	Boolean	R	Yes	Gets a value that specifies whether the list is an external list.
HasUniqueRoleAssignments	Boolean	R	No	Gets a value that specifies whether the role assignments are uniquely defined for this securable object or inherited from a parent securable object.
Hidden	Boolean	RW	Yes	Gets or sets a Boolean value that specifies whether the list is hidden. If true, the server sets the OnQuickLaunch property to false.
Id	GUID	R	Yes	Gets the GUID that identifies the list in the database.
ImageUrl	String	R	Yes	Gets a value that specifies the URI for the icon of the list.
InformationRightsManagementSettings	SP.InformationRightsManagementSettings	R	No
IrmEnabled	Boolean	RW	Yes
IrmExpire	Boolean	RW	Yes
IrmReject	Boolean	RW	Yes
IsApplicationList	Boolean	RW	Yes	Gets or sets a value that specifies a flag that a client application can use to determine whether to display the list.
IsCatalog	Boolean	R	Yes	Gets a value that specifies whether the list is a gallery.
IsPrivate	Boolean	R	Yes
IsSiteAssetsLibrary	Boolean	R	No	Gets a value that indicates whether the list is designated as a default asset location for images or other files which the users upload to their wiki pages.
ItemCount	Int32	R	Yes	Gets a value that specifies the number of list items in the list.
Items	SP.ListItemCollection	R	No	Gets all the items in the list. You can use OData query operations to filter items (example: …/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/items?$filter=Status eq 'not started'&$select=Title&$top=5).
LastItemDeletedDate	DateTime	R	Yes	Gets a value that specifies the last time a list item was deleted from the list.
LastItemModifiedDate	DateTime	RW	Yes	Gets a value that specifies the last time a list item, field, or property of the list was modified.
ListItemEntityTypeFullName	String	R	Yes
MultipleDataList	Boolean	RW	Yes	Gets or sets a value that indicates whether the list in a Meeting Workspace site contains data for multiple meeting instances within the site.
NoCrawl	Boolean	RW	Yes	Gets or sets a value that specifies that the crawler must not crawl the list.
OnQuickLaunch	Boolean	RW	No	Gets or sets a value that specifies whether the list appears on the Quick Launch of the site. If true, the server sets the Hidden property to false.
ParentWeb	SP.Web	R	No	Gets a value that specifies the site that contains the list.
ParentWebUrl	String	R	Yes	Gets a value that specifies the server-relative URL of the site that contains the list.
RoleAssignments	SP.RoleAssignmentCollection	R	No	Gets the role assignments for the securable object.
RootFolder	SP.Folder	R	No	Gets the root folder that contains the files in the list and any related files.
SchemaXml	String	R	No	Gets a value that specifies the list schema of the list.
ServerTemplateCanCreateFolders	Boolean	R	Yes	Gets a value that indicates whether folders can be created within the list.
TemplateFeatureId	GUID	R	Yes	Gets a value that specifies the feature identifier of the feature that contains the list schema for the list. Returns an empty GUID if the list schema is not contained within a feature.
Title	String	RW	Yes	Gets or sets the displayed title for the list. Its length must be <= 255 characters.
UserCustomActions	SP.UserCustomActionCollection	R	No	Gets a value that specifies the collection of all user custom actions for the list.
ValidationFormula	String	RW	No	Gets or sets a value that specifies the data validation criteria for a list item. Its length must be <= 1023.
ValidationMessage	String	RW	No	Gets or sets a value that specifies the error message returned when data validation fails for a list item. Its length must be <= 1023.
Views	SP.ViewCollection	R	No	Gets a value that specifies the collection of all public views on the list and personal views of the current user on the list.
WorkflowAssociations	SP.Workflow.WorkflowAssociationCollection	R	No	Gets a value that specifies the collection of all workflow associations for the list.

List methods

AddItem
BreakRoleInheritance
DeleteObject
GetChanges
GetItemById
GetItems
GetListItemChangesSinceToken
GetRelatedFields
GetUserEffectivePermissions
GetView
Recycle
RenderListData
RenderListFormData
ReserveListItemId
ResetRoleInheritance

AddItem method

The recommended way to add a list item is to send a POST request to the ListItemCollection resource endpoint, as shown in ListItemCollection request examples.

BreakRoleInheritance method

Creates unique role assignments for the securable object.

Endpoint	/breakroleinheritance(copyroleassignments, clearsubscopes)
Parameters	copyroleassignments Type: Boolean true to copy the role assignments from the parent securable object; false to remove the inherited role assignments except one that contains the current user. clearsubscopes Type: Boolean Optional. true to make all child securable objects inherit role assignments from the current object; false (default) to leave role assignments unchanged for child securable objects that do not inherit role assignments from their parent object.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'a290086b-2d43-4151-add4-893474a930a9')
    /breakroleinheritance(copyroleassignments=false, clearsubscopes=true)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

DeleteObject method

The recommended way to delete a list is to send a DELETE request to the List resource endpoint, as shown in List request examples.

GetChanges method

Returns the collection of changes from the change log that have occurred within the list, based on the specified query.

Endpoint	/getchanges
Parameters	query Type: SP.ChangeQuery The change query. Pass this parameter in the request body, as shown in the request example.
HTTP method	POST
Response	Type: SP.ChangeCollection The changes to the list that match the criteria of the specified change query.

  Request example

var metadata = "{ 'query' : { '__metadata': { 'type': 'SP.ChangeQuery' },
    'Add': 'True', 'Item': 'True' }}";

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getchanges
    ?@target='<host web url>'",
  method: "POST",
  body: metadata,
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

  Response example

    {"d":
      {"results":[{
        "__metadata":{
          "id":"https://<site url>/_api/SP.ChangeItema7e7c6e9-2c41-47c3-aae9-2b4a63b7a087",
          "uri":"https://<site url>/_api/SP.ChangeItem",
          "type":"SP.ChangeItem"
        },
        "ChangeToken":{"__metadata":{"type":"SP.ChangeToken"}, "StringValue":"1;3;482e418a-0900-414b-8902-02248c2e44e8;634955266749500000;5749111"},
        "ChangeType":1,
        "SiteId":"ce11bfbb-cf9d-4b2b-a642-8673bd48cceb",
        "Time":"2013-02-03T22:17:54Z",
        "ItemId":1,
        "ListId":"482e418a-0900-414b-8902-02248c2e44e8",
        "WebId":"a975b994-fc67-4203-a519-b160175ca967"
      }]
    }}

GetItemById method

Returns the list item with the specified list item identifier.

Endpoint	/getitembyid(<item id>)
Parameters	Type: Int32 The ID of the list item.
HTTP method	GET
Response	Type: SP.ListItem The list item with the specified ID.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'a290086b-2d43-4151-add4-893474a930a9')
    /getitembyid(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can pass the list item ID to the ListItemCollection resource. Example: …/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/items(2).

GetItems method

Returns a collection of items from the list based on the specified query.

Endpoint	/getitems
Parameters	query Type: SP.CamlQuery The filter query. Pass this parameter in the request body, as shown in the request example.
HTTP method	POST
Response	Type: SP.ListItemCollection The list items that match the specified query.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'47f89cf2-359d-4792-9dc4-8da877a5050a')
    /getitems
    ?@target='<host web url>'",
  method: "POST",
  body: "{ 'query' : {'__metadata': { 'type': 'SP.CamlQuery' }, "ViewXml": "<View><Query><Where><Contains><FieldRef Name='Status'/><Value Type='CHOICE'>in progress</Value></Contains></Where></Query></View>" } }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json; odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

GetListItemChangesSinceToken method

Endpoint	/getlistitemchangessincetoken
Parameters	query Type: SP.ChangeLogItemQuery The query that contains the change token. Pass this parameter in the request body, as shown in the request example.
HTTP method	POST
Response	Type: GetListItemChangesSinceTokenResult A Stream that contains an XML representation of the changes to the list items that have happened after the specified change.

  Request example

var metadata = "{ 'query': { '__metadata': { 'type': 'SP.ChangeLogItemQuery' },
    'ChangeToken': '1;3;79cc20e6-adda-438e-8a96-792041b33168;635103901830230000;33050019' }}";

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getlistitemchangessincetoken
    ?@target='<host web url>'",
  method: "POST",
  body: metadata,
  headers: { "content-type": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

See Synchronize SharePoint items using the REST service for an example of how to specify a filtered query.

  Response example

<?xml version="1.0" encoding="utf-8" ?>
<GetListItemChangesSinceTokenResult>
  <listitems MinTimeBetweenSyncs='0' RecommendedTimeBetweenSyncs='180' MaxBulkDocumentSyncSize='500' MaxRecommendedEmbeddedFileSize='500' EffectivePermMask='FullMask' xmlns:s='uuid:BDC6E3F0-6DA3-11d1-A2A3-00AA00C14882' xmlns:dt='uuid:C2F41010-65B3-11d1-A29F-00AA00C14882' xmlns:rs='urn:schemas-microsoft-com:rowset' xmlns:z='#RowsetSchema'>
    <Changes LastChangeToken="1;3;79cc20e6-adda-438e-8a96-792041b33168;635110802324330000;33811711">
    <List DocTemplateUrl="" DefaultViewUrl="/Lists/TestList/AllItems.aspx" MobileDefaultViewUrl="" ID="{79CC20E6-ADDA-438E-8A96-792041B33168}" Title="TestList" Description="" ImageUrl="/_layouts/15/images/itgen.png?rev=26" Name="{79CC20E6-ADDA-438E-8A96-792041B33168}" BaseType="0" FeatureId="00bfea71-de22-43b2-a848-c05709900100" ServerTemplate="100" Created="20130725 22:22:35" Modified="20130802 22:43:52" LastDeleted="20130725 22:22:35" Version="4" Direction="none" ThumbnailSize="" WebImageWidth="" WebImageHeight="" Flags="545263616" ItemCount="2" AnonymousPermMask="0" RootFolder="/Lists/TestList" ReadSecurity="1" WriteSecurity="1" Author="11" EventSinkAssembly="" EventSinkClass="" EventSinkData="" EmailAlias="" WebFullUrl="/" WebId="a975b994-fc67-4203-a519-b160175ca967" SendToLocation="" ScopeId="ad9949be-be16-4946-b5de-66c912eda54a" MajorVersionLimit="0" MajorWithMinorVersionsLimit="0" WorkFlowId="" HasUniqueScopes="False" NoThrottleListOperations="False" HasRelatedLists="" Followable="False" AllowDeletion="True" AllowMultiResponses="False" EnableAttachments="True" EnableModeration="False" EnableVersioning="False" HasExternalDataSource="False" Hidden="False" MultipleDataList="False" Ordered="False" ShowUser="True" EnablePeopleSelector="False" EnableResourceSelector="False" EnableMinorVersion="False" RequireCheckout="False" ThrottleListOperations="False" ExcludeFromOfflineClient="False" CanOpenFileAsync="True" EnableFolderCreation="False" IrmEnabled="False" IsApplicationList="False" PreserveEmptyValues="False" StrictTypeCoercion="False" EnforceDataValidation="False" MaxItemsPerThrottledOperation="5000">
      <Fields>
        <Field ID="{03e45e84-1992-4d42-9116-26f756012634}" RowOrdinal="0" Type="ContentTypeId" Sealed="TRUE" ReadOnly="TRUE" Hidden="TRUE" DisplayName="Content Type ID" Name="ContentTypeId" DisplaceOnUpgrade="TRUE" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="ContentTypeId" ColName="tp_ContentTypeId" FromBaseType="TRUE"/>
        <Field ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}" Type="Text" Name="Title" DisplayName="Title" Required="TRUE" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="Title" FromBaseType="TRUE" ColName="nvarchar1"/>
        <Field ID="{34ad21eb-75bd-4544-8c73-0e08330291fe}" ReadOnly="TRUE" Type="Note" Name="_ModerationComments" DisplayName="Approver Comments" Hidden="TRUE" CanToggleHidden="TRUE" Filterable="FALSE" Sortable="FALSE" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="_ModerationComments" FromBaseType="TRUE" ColName="ntext1"/>
        <Field ID="{39360f11-34cf-4356-9945-25c44e68dade}" ReadOnly="TRUE" Hidden="TRUE" Type="Text" Name="File_x0020_Type" DisplaceOnUpgrade="TRUE" DisplayName="File Type" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="File_x0020_Type" FromBaseType="TRUE" ColName="nvarchar2"/>
        <Field ID="{fc2e188e-ba91-48c9-9dd3-16431afddd50}" Name="WorkAddress" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="WorkAddress" Group="Core Contact and Calendar Columns" DisplayName="Address" Type="Note" NumLines="2" Sortable="FALSE" ColName="ntext2" RowOrdinal="0"/>
        <Field ID="{fce16b4c-fe53-4793-aaab-b4892e736d15}" Name="EMail" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="EMail" Group="Core Contact and Calendar Columns" DisplayName="E-Mail" ReadOnly="FALSE" Type="Text" FromBaseType="TRUE" AllowDeletion="TRUE" ColName="nvarchar3" RowOrdinal="0"/>
        <Field Type="Lookup" DisplayName="anewishlisttitle" Required="FALSE" EnforceUniqueValues="FALSE" List="{482e418a-0900-414b-8902-02248c2e44e8}" ShowField="Title" UnlimitedLengthInDocumentLibrary="FALSE" RelationshipDeleteBehavior="None" ID="{9919f3f8-88fb-43fc-b4cb-658b1db1bfe3}" SourceID="{79cc20e6-adda-438e-8a96-792041b33168}" StaticName="anewishlisttitle" Name="anewishlisttitle" ColName="int1" RowOrdinal="0"/>
        <Field Type="Lookup" DisplayName="Books title" Required="FALSE" EnforceUniqueValues="FALSE" List="{90146606-81fd-410d-9fdd-d03b6349fbcd}" ShowField="Title" UnlimitedLengthInDocumentLibrary="FALSE" RelationshipDeleteBehavior="None" ID="{879a1cba-91b6-4c0a-99fb-29f877aae3ea}" SourceID="{79cc20e6-adda-438e-8a96-792041b33168}" StaticName="Books_x0020_title" Name="Books_x0020_title" ColName="int2" RowOrdinal="0"/>
        <Field ID="{1d22ea11-1e32-424e-89ab-9fedbadb6ce1}" ColName="tp_ID" RowOrdinal="0" ReadOnly="TRUE" Type="Counter" Name="ID" PrimaryKey="TRUE" DisplayName="ID" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="ID" FromBaseType="TRUE"/>
        <Field ID="{c042a256-787d-4a6f-8a8a-cf6ab767f12d}" Type="Computed" DisplayName="Content Type" Name="ContentType" DisplaceOnUpgrade="TRUE" RenderXMLUsingPattern="TRUE" Sortable="FALSE" SourceID="https://schemas.microsoft.com/sharepoint/v3" StaticName="ContentType" Group="_Hidden" PITarget="MicrosoftWindowsSharePointServices" PIAttribute="ContentTypeID" FromBaseType="TRUE">
          <FieldRefs>
            <FieldRef Name="ContentTypeId"/>
          </FieldRefs>
          <DisplayPattern>
            <MapToContentType>
              <Column Name="ContentTypeId"/>
            </MapToContentType>
          </DisplayPattern>
        </Field>
        <…>
      </Fields>
      <RegionalSettings>
        <Language>1033</Language>
        <Locale>1033</Locale>
        <AdvanceHijri>0</AdvanceHijri>
        <CalendarType>1</CalendarType>
        <Time24>False</Time24>
        <TimeZone>480</TimeZone>
        <SortOrder>2070</SortOrder>
        <Presence>True</Presence>
      </RegionalSettings>
      <ServerSettings>
        <ServerVersion>16.0.1810.1236</ServerVersion>
        <RecycleBinEnabled>True</RecycleBinEnabled>
        <ServerRelativeUrl>/</ServerRelativeUrl>
       </ServerSettings>
      </List>
    </Changes>
    <rs:data ItemCount="1">
      <z:row ows_ContentTypeId='0x0100C8CFB1DE383F1B49A44ABD2EB9AC7322' ows_Title='<item title>' ows_ID='2' ows_ContentType='Item' ows_Modified='2013-07-25T23:21:50Z' ows_Created='2013-07-25T23:21:50Z' ows_Author='<author>' ows_Editor='<editor>' ows_owshiddenversion='1' ows_WorkflowVersion='1' ows__UIVersion='512' ows__UIVersionString='1.0' ows_Attachments='0' ows__ModerationStatus='0' ows_LinkTitleNoMenu='<item title>' ows_LinkTitle='<item title>' ows_LinkTitle2='<item title>' ows_SelectTitle='2' ows_Order='200.000000000000' ows_GUID='{D38981C3-2735-4FDF-9B41-91F3ADA8F3F0}' ows_FileRef='2;#Lists/TestList/2_.000' ows_FileDirRef='2;#Lists/TestList' ows_Last_x0020_Modified='2;#2013-07-25T23:21:50Z' ows_Created_x0020_Date='2;#2013-07-25T23:21:50Z' ows_FSObjType='2;#0' ows_SortBehavior='2;#0' ows_PermMask='0x7fffffffffffffff' ows_FileLeafRef='2;#2_.000' ows_UniqueId='2;#{4D719C3B-B8AB-46A0-A080-402DF6EE31C1}' ows_ProgId='2;#' ows_ScopeId='2;#{AD9949BE-BE16-4946-B5DE-66C912EDA54A}' ows__EditMenuTableStart='2_.000' ows__EditMenuTableStart2='2' ows__EditMenuTableEnd='2' ows_LinkFilenameNoMenu='2_.000' ows_LinkFilename='2_.000' ows_LinkFilename2='2_.000' ows_ServerUrl='/Lists/TestList/2_.000' ows_EncodedAbsUrl='https://<site url>.sharepoint.com/Lists/TestList/2_.000' ows_BaseName='2_' ows_MetaInfo='2;#' ows__Level='1' ows__IsCurrentVersion='1' ows_ItemChildCount='2;#0' ows_FolderChildCount='2;#0' ows_ServerRedirected='0' />
    </rs:data>
  </listitems>
</GetListItemChangesSinceTokenResult>

GetRelatedFields method

Returns a collection of lookup fields that use this list as a data source and that have FieldLookup.IsRelationship set to true.

Endpoint	/getrelatedfields
Parameters	None
HTTP method	GET
Response	Type: SP.RelatedFieldCollection A collection of SP.RelatedField objects with information about the relationship between a field in a list and a lookup field in another list.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getrelatedfields
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetUserEffectivePermissions method

Endpoint	/getusereffectivepermissions(@user)?@user='<user login name>'
Parameters	Type: String The login name of the user to get permissions for, passed as an alias in the query string. For example:   SharePoint Online or on-premises using forms: …/getusereffectivepermissions(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'   On-premises using Windows claims: …/getusereffectivepermissions(@v)?@v='i%3A0%23.w%7Cdomain\user'   On-premises using SAML claims: …/getusereffectivepermissions(@v)?@v='i%3A05%3At%7Cadfs+with+roles%7Cuser%40domain.com'
HTTP method	GET
Response	Type: SP.BasePermissions The set of permissions for the specified user: Int64 values for high- and low-order parts of the permissions.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getusereffectivepermissions(@user)?@user='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetView method

Returns the list view with the specified view identifier.

Endpoint	/getview('<view id>')
Parameters	Type: String The unique identifier for the list view.
HTTP method	GET
Response	Type: SP.View The specified list view.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /getview('4814949d-3e17-444c-a1a3-cb69bc77e95f')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the view ID on the ViewCollection resource. Example: …/_api/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/views('4814949d-3e17-444c-a1a3-cb69bc77e95f')

Recycle method

Moves the list to the Recycle Bin and returns the identifier of the new Recycle Bin item.

Endpoint	/recycle
Parameters	None
HTTP method	POST
Response	Type: GUID The GUID of the recycled list.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RenderListData method

Endpoint	/renderlistdata('<view xml>')
Parameters	Type: String A CAML query that defines the items and fields that you want returned.
HTTP method	POST
Response	Type: String The requested list data in the view defined by the specified XML.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /renderlistdata(@viewXml)?@viewXml='<View><RowLimit>10</RowLimit></View>'
    &@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RenderListFormData method

Endpoint	/renderlistformdata(itemid, formid, mode)
Parameters	itemid Type: Int32 The identifier of the list item to be rendered. formid Type: String The identifier of the form. mode Type: Int32 The SP.ControlMode of the control used to display the item: 1 = Display; 2 = Edit; 3 = New.
HTTP method	POST
Response	Type: String The field values and field schema attributes for a list item.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /renderlistformdata(itemid=4, formid='e8b2f6e3-1081-4b18-833b-475f76473cde', mode=2)
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ReserveListItemId method

Reserves a list item ID for idempotent list item creation.

Endpoint	/reservelistitemid
Parameters	None
HTTP method	POST
Response	Type: Int32 The list item identifier to be reserved.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    /reservelistitemid
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ResetRoleInheritance method

Resets the role inheritance for the securable object and inherits role assignments from the parent securable object.

Endpoint	/resetroleinheritance
Parameters	None
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /resetroleinheritance
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a List resource in JSON format.

    {"d":{
      "__metadata":{
        "id":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')",
        "uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')",
        "etag":"\"0\"",
        "type":"SP.List"
      },
      "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/FirstUniqueAncestorSecurableObject"}},
      "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/RoleAssignments"}},
      "ContentTypes":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/ContentTypes"}},
      "DefaultView":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/DefaultView"}},
      "EventReceivers":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/EventReceivers"}},
      "Fields":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/Fields"}},
      "Forms":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/Forms"}},
      "InformationRightsManagementSettings":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'8ade7551-f53c-48c5-9d2b-e89f6528cf47')/InformationRightsManagementSettings"}},
      "AllowContentTypes":true, 
      "BaseTemplate":100, 
      "BaseType":0, 
      "ContentTypesEnabled":false, 
      "Created":"2013-02-02T21:11:56Z",
      "DefaultContentApprovalWorkflowId":"00000000-0000-0000-0000-000000000000",
      "Description":"",
      "Direction":"none",
      "DocumentTemplateUrl":null, 
      "DraftVersionVisibility":0, 
      "EnableAttachments":true, 
      "EnableFolderCreation":false, 
      "EnableMinorVersions":false, 
      "EnableModeration":false, 
      "EnableVersioning":false,
      "EntityTypeName":"ANewList",
      "ForceCheckout":false, 
      "HasExternalDataSource":false, 
      "Hidden":false, 
      "Id":"8ade7551-f53c-48c5-9d2b-e89f6528cf47",
      "ImageUrl":"/_layouts/15/images/itgen.png?rev=23",
      "IrmEnabled":false, 
      "IrmExpire":false, 
      "IrmReject":false, 
      "IsApplicationList":false, 
      "IsCatalog":false, 
      "IsPrivate":false, 
      "ItemCount":1, 
      "LastItemDeletedDate":"2013-02-02T21:11:56Z",
      "LastItemModifiedDate":"2013-02-03T22:17:55Z",
      "ListItemEntityTypeFullName":"SP.Data.ANewListItem",
      "MultipleDataList":false, 
      "NoCrawl":false, 
      "ParentWebUrl":"/",
      "ServerTemplateCanCreateFolders":true, 
      "TemplateFeatureId":"00bfea71-de22-43b2-a848-c05709900100",
      "Title":"ANewList"
    }}

ListCollection resource

Represents a collection of lists.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/web/lists

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get the lists at the root site

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a list by title

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists/getbytitle('Access Requests')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a list by ID

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Create a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.List' }, 'AllowContentTypes': true, 'BaseTemplate': 100,
    'ContentTypesEnabled': true, 'Description': 'My list description', 'Title': 'Test title' }",
  headers: { "content-type": "application/json;odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ListCollection methods

EnsureSiteAssetsLibrary
EnsureSitePagesLibrary
GetById
GetByTitle

EnsureSiteAssetsLibrary method

Gets a list that is the default asset location for images or other files, which the users upload to their wiki pages.

Endpoint	/ensuresiteassetslibrary
Parameters	None
HTTP method	POST
Response	Type: SP.List The list that is the default location for wiki page assets.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    /ensuresiteassetslibrary
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

EnsureSitePagesLibrary method

Gets a list that is the default location for wiki pages.

Endpoint	/ensuresitepageslibrary
Parameters	None
HTTP method	POST
Response	Type: SP.List The list that is the default location for wiki pages.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    /ensuresitepageslibrary
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GetById method

Returns the list with the specified list identifier.

Endpoint	/getbyid
Parameters	Type: String The list identifier.
HTTP method	GET
Response	Type: SP.List The list with the specified identifier.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    /getbyid('51925dd7-2108-481a-b1ef-4bfa4e69d48b')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can just pass the list ID to the ListCollection resource. Example: …/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b').

GetByTitle method

Returns the list with the specified title from the collection.

Endpoint	/getbytitle
Parameters	Type: String The list title.
HTTP method	GET
Response	Type: SP.List The list with the specified title.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web/lists
    /getbytitle('Access Requests')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents an ListCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{"id":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')",
        "uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-
    4bfa4e69d48b')",
        "etag":"\"6\"",
        "type":"SP.List"
      },
      "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/FirstUniqueAncestorSecurableObject"}},
      "RoleAssignments":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/RoleAssignments"}},
      "ContentTypes":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/ContentTypes"}},
      "DefaultView":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/DefaultView"}},
      "EventReceivers":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/EventReceivers"}},
      "Fields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Fields"}},
      "Forms":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Forms"}},
      "InformationRightsManagementSettings":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/InformationRightsManagementSettings"}},
      "Items":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Items"}},
      "ParentWeb":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/ParentWeb"}},
      "RootFolder":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/RootFolder"}},
      "UserCustomActions":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/UserCustomActions"}},
      "Views":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/Views"}},
      "WorkflowAssociations":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/WorkflowAssociations"}},
      "AllowContentTypes":true,
      "BaseTemplate":160,"BaseType":0,
      "ContentTypesEnabled":true,
      "Created":"2013-06-10T17:14:49Z",
      "DefaultContentApprovalWorkflowId":"00000000-0000-0000-0000-000000000000",
      "Description":"Use this list to track access requests to a site or uniquely permissioned items in the site.",
      "Direction":"none",
      "DocumentTemplateUrl":null,
      "DraftVersionVisibility":0,
      "EnableAttachments":false,
      "EnableFolderCreation":false,
      "EnableMinorVersions":false,
      "EnableModeration":false,
      "EnableVersioning":true,
      "EntityTypeName":"Access_x0020_Requests",
      "ForceCheckout":false,
      "HasExternalDataSource":false,
      "Hidden":true,
      "Id":"51925dd7-2108-481a-b1ef-4bfa4e69d48b",
      "ImageUrl":"/_layouts/15/images/itgen.gif?rev=26",
      "IrmEnabled":false,
      "IrmExpire":false,
      "IrmReject":false,
      "IsApplicationList":false,
      "IsCatalog":false,
      "IsPrivate":false,
      "ItemCount":3,
      "LastItemDeletedDate":"2013-06-10T17:14:49Z",
      "LastItemModifiedDate":"2013-06-10T17:20:48Z",
      "ListItemEntityTypeFullName":"SP.Data.Access_x0020_RequestsItem",
      "MultipleDataList":false,
      "NoCrawl":true,
      "ParentWebUrl":"/",
      "ServerTemplateCanCreateFolders":true,
      "TemplateFeatureId":"a0f12ee4-9b60-4ba4-81f6-75724f4ca973",
      "Title":"Access Requests"},
      {
        "__metadata":{
          "id":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')",
          "uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-
    02248c2e44e8')",
          "etag":"\"1\"",
          "type":"SP.List"
        },
        "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902- 
    02248c2e44e8')/FirstUniqueAncestorSecurableObject"}},
        "RoleAssignments":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/RoleAssignments"}},
        "ContentTypes":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/ContentTypes"}},
        "DefaultView":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/DefaultView"}},
        "EventReceivers":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/EventReceivers"}},
        "Fields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Fields"}},
        "Forms":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Forms"}},
        "InformationRightsManagementSettings":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/InformationRightsManagementSettings"}},
        "Items":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Items"}},
        "ParentWeb":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/ParentWeb"}},
        "RootFolder":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/RootFolder"}},
        "UserCustomActions":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/UserCustomActions"}},
        "Views":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/Views"}},
        "WorkflowAssociations":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'482e418a-0900-414b-8902-02248c2e44e8')/WorkflowAssociations"}},
        "AllowContentTypes":true,
        "BaseTemplate":100,
        "BaseType":0,
        "ContentTypesEnabled":false,
        "Created":"2013-02-02T21:11:56Z",
        "DefaultContentApprovalWorkflowId":"00000000-0000-0000-0000-000000000000",
        "Description":"",
        "Direction":"none",
        "DocumentTemplateUrl":null,
        "DraftVersionVisibility":0,
        "EnableAttachments":true,
        "EnableFolderCreation":false,
        "EnableMinorVersions":false,
        "EnableModeration":false,
        "EnableVersioning":false,
        "EntityTypeName":"AList",
        "ForceCheckout":false,
        "HasExternalDataSource":false,
        "Hidden":false,
        "Id":"482e418a-0900-414b-8902-02248c2e44e8",
        "ImageUrl":"/_layouts/15/images/itgen.png?rev=23",
        "IrmEnabled":false,
        "IrmExpire":false,
        "IrmReject":false,
        "IsApplicationList":false,
        "IsCatalog":false,
        "IsPrivate":false,
        "ItemCount":3,
        "LastItemDeletedDate":"2013-02-02T21:11:56Z",
        "LastItemModifiedDate":"2013-06-26T22:31:03Z",
        "ListItemEntityTypeFullName":"SP.Data.AListListItem",
        "MultipleDataList":false,
        "NoCrawl":false,
        "ParentWebUrl":"/",
        "ServerTemplateCanCreateFolders":true,
        "TemplateFeatureId":"00bfea71-de22-43b2-a848-c05709900100",
        "Title":"AList"
      }]
    }}

ListItem resource

Represents an item or row in a list. A list item is a type of SP.SecurableObject.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Note

The OData $skip query option does not work with this endpoint.

Endpoint URI

http://<site url>/web/lists(guid'<list id>')/items(<item id>)
http://<site url>/web/lists/getbytitle('<list title>')/items(<item id>)

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE

Request examples

GET request example: Get a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

POST request example: Create a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.Data.Team_x0020_tasksListItem' },
    'Title': 'Teams incorporate feedback', 'AssignedToId': {"results":[1]},
    'StartDate':'2014-01-29T08:00:00Z', 'DueDate':'2014-01-31T08:00:00Z',
    'PredecessorsId': {"results":[4]}}",
  headers: { 
    "accept": "application/json;odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

Note

To create or change a list item, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.

See ListItemCollection request examples for an example that shows how to create a list item.

MERGE request example: Change a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.Data.Team_x0020_tasksListItem' },
    'Priority': '(1) High', 'Status': 'In Progress', 'PercentComplete': 0.3 }",
  headers: { 
    "IF-MATCH": "*",
    "content-type": "application/json;odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

Note

To create or change a list item, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.

DELETE request example: Delete a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "POST",
  headers: { 
    "IF-MATCH”: "*",
    "X-HTTP-Method": "DELETE"
  },
  success: successHandler,
  error: errorHandler
});

If you want to get the GUID of the recycle operation, use the item's Recycle method.

ListItem properties

Property	Type	R/W	Returned with resource	Description
AttachmentFiles	SP.AttachmentCollection	R	No	Specifies the collection of attachments that are associated with the list item.
ContentType	SP.ContentType	R	No	Gets a value that specifies the content type of the list item.
DisplayName	String	R	Yes (displayed as the "Title" value)	Gets a value that specifies the display name of the list item.
EffectiveBasePermissions	SP.BasePermissions	R	Yes	Gets a value that specifies the effective permissions on the list item that are assigned to the current user.
EffectiveBasePermissionsForUI	SP.BasePermissions	R	Yes	Gets the effective base permissions for the current user, as they should be displayed in UI.
FieldValuesAsHtml	SP.FieldStringValues	R	No	Gets the values for the list item as HTML.
FieldValuesAsText	SP.FieldStringValues	R	No	Gets the list item's field values as a collection of string values.
FieldValuesForEdit	SP.FieldStringValues	R	No	Gets the formatted values to be displayed in an edit form.
File	SP.File	R	No	Gets the file that is represented by the item from a document library.
FileSystemObjectType	Int32	R	Yes	Gets a value that specifies whether the list item is a file or a list folder. Represents an SP.FileSystemObjectType value: Invalid = -1; File = 0; Folder = 1; Web = 2.
FirstUniqueAncestorSecurableObject	SP.SecurableObject	R	No	Gets the object where role assignments for this object are defined. If role assignments are defined directly on the current object, the current object is returned.
Folder	SP.Folder	R	No	Gets a folder object that is associated with a folder item.
HasUniqueRoleAssignments	Boolean	R	No	Gets a value that specifies whether the role assignments are uniquely defined for this securable object or inherited from a parent securable object.
Id	Int32	R	Yes	Gets a value that specifies the list item identifier.
ParentList	SP.List	R	No	Gets the parent list that contains the list item.
RoleAssignments	SP.RoleAssignmentCollection	R	No	Gets the role assignments for the securable object.

ListItem methods

BreakRoleInheritance
DeleteObject
GetUserEffectivePermissions
Recycle
ResetRoleInheritance
ValidateUpdateListItem

BreakRoleInheritance method

Creates unique role assignments for the securable object.

Endpoint	/breakroleinheritance(copyroleassignments, clearsubscopes)
Parameters	copyroleassignments Type: Boolean true to copy the role assignments from the parent securable object; false to remove the inherited role assignments except one that contains the current user. clearsubscopes Type: Boolean true to make all child securable objects inherit role assignments from the current object; false to leave role assignments unchanged for child securable objects that do not inherit role assignments from their parent object.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /breakroleinheritance(copyroleassignments=true, clearsubscopes=false)
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,par
  error: errorHandler
});

DeleteObject method

The recommended way to delete a list item is to send a DELETE request to the ListItem resource endpoint, as shown in ListItem request examples.

GetUserEffectivePermissions method

Gets the effective permissions that a specified user has on the list item.

Endpoint	/getusereffectivepermissions(@v)?@v='<user login name>'
Parameters	Type: String The login name of the user to get permissions for. For example:   SharePoint Online: …/getusereffectivepermissions(@v)?@v='i%3A0%23.f%7Cmembership%7C<user>%40<domain>.onmicrosoft.com'   On-premises using claims: …/getusereffectivepermissions(@v)?@v='i%3A0%23.w%7C<domain\user>'   On-premises using forms: …/getusereffectivepermissions(@v)?@v='<domain\user>'
HTTP method	GET
Response	Type: SP.BasePermissions The base permissions for the list item for the specified user: Int64 values for high- and low-order parts of the permissions.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /getusereffectivepermissions(@v)?@v='i%3A0%23.f%7Cmembership%7Cuser%40domain.onmicrosoft.com'
    &@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Recycle method

Moves the list item to the Recycle Bin and returns the identifier of the new Recycle Bin item.

Endpoint	/recycle
Parameters	None
HTTP method	POST
Response	Type: GUID The GUID of the recycled list item.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /recycle
    ?@target='<host web url>'",
  method: "POST",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ResetRoleInheritance method

Resets the role inheritance for the securable object and inherits role assignments from the parent securable object.

Endpoint	/resetroleinheritance
Parameters	None
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /resetroleinheritance
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

ValidateUpdateListItem method

Validates and sets the values of the specified collection of fields for the list item.

Endpoint	/validateupdatelistitem
Parameters	formValues Type: SP.ListItemFormUpdateValue[] The fields to change and their new values. Pass this parameter in the request body, as shown in the request example. bNewDocumentUpdate Type: Boolean true if the list item is a document being updated after upload; otherwise false. Pass this parameter in the request body, as shown in the request example, or in the URI path.
HTTP method	POST
Response	Type: SP.ListItemFormUpdateValue[] An array of objects that represent the changed fields and values.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    /validateupdatelistitem
    ?@target='<host web url>'",
  method: "POST",
  body: "{ 'formValues':[{'FieldName':'Status', 'FieldValue':'Deferred'},
    {'FieldName':'StartDate', 'FieldValue':'12/31/2014'}], 'bNewDocumentUpdate': false }",
  headers: {
    "accept": "application/json; odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

  Response example

    {"d":{
      "ValidateUpdateListItem":{"results":[
        {
          "__metadata":{"type":"SP.ListItemFormUpdateValue"},
          "ErrorMessage":null,
          "FieldName":"Status",
          "FieldValue":"Deferred",
          "HasException":false
        },{
          "__metadata":{"type":"SP.ListItemFormUpdateValue"},
          "ErrorMessage":null,
          "FieldName":"StartDate",
          "FieldValue":"12/31/2014",
          "HasException":false
        }
      ]}
    }}

OData representation

The following example represents an ListItem resource in JSON format. The resource also returns its field values.

    {"d":{
      "__metadata":{,
        "id":"2bbdaee6-1172-4e36-9f90-ce35ec9b6207",
        "uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)",
        "etag":"\"1\"",
        "type":"SP.Data.Team_x0020_tasksListItem"
      },
      "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FirstUniqueAncestorSecurableObject"}},
      "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/RoleAssignments"}},
      "AttachmentFiles":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/AttachmentFiles"}},
      "ContentType":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ContentType"}},
      "FieldValuesAsHtml":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsHtml"}},
      "FieldValuesAsText":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsText"}},
      "FieldValuesForEdit":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesForEdit"}},
      "File":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/File"}},
      "Folder":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/Folder"}},
      "ParentList":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ParentList"}},
      "FileSystemObjectType":0,
      "Id":2,
      "ID":2,
      "ContentTypeId":"0x0108004F8963A897E4E64A83E990C1B6B65770",
      "Title":"Assign teams",
      "Modified":"2013-09-03T17:50:30Z",
      "Created":"2013-09-03T17:50:30Z",
      "AuthorId":1073741823,
      "EditorId":1073741823,
      "OData__UIVersionString":"1.0",
      "Attachments":false,
      "GUID":"ce6e516e-2da4-4a3e-9325-daf7d7f61490",
      "PredecessorsId":{"results":[1]},
      "Priority":"(2) Normal",
      "Status":"Not Started",
      "PercentComplete":0,
      "AssignedToId":{"results":[1]},
      "Body":null,
      "StartDate":"2014-01-02T08:00:00Z",
      "DueDate":"2014-01-02T08:00:00Z",
      "Checkmark":"0",
      "RelatedItems":null
    }}

ListItemCollection resource

Represents a collection of ListItem resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/web/lists(guid'<list id>')/items
http://<site url>/web/lists/getbytitle('<list title>')/items

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get all list items

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

You can use OData query operations to filter for particular items (example: …/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/items?$filter=Status eq 'not started'&$select=Title&$top=5).

POST request example: Create a list item

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.Data.Team_x0020_tasksListItem' },
    'Title': 'Teams incorporate feedback', 'AssignedToId': {"results":[1]},
    'StartDate':'2014-01-29T08:00:00Z', 'DueDate':'2014-01-31T08:00:00Z',
    'PredecessorsId': {"results":[4]} }",
  headers: { 
    "accept": "application/json;odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

Note

To create or change a list item, you must know the ListItemEntityTypeFullName property of the list and pass that as the value of type in the HTTP request body.

See ListItem request examples for examples that show how to change or delete a list item.

ListItemCollection methods

GetById

GetById method

Returns the list item with the specified list item identifier.

Endpoint	/getbyid(<item id>)
Parameters	Type: Int32 The ID of the list item.
HTTP method	GET
Response	Type: SP.ListItem The list item with the specified ID.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items
    /getbyid(2)
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or you can just specify the list item ID on the ListItemCollection resource. Example: …/_api/web/lists(guid'a290086b-2d43-4151-add4-893474a930a9')/items(2)

OData representation

The following example represents an ListItemCollection resource in JSON format, which returns a collection of ListItem resources.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"dd9ab60c-4653-4654-85de-1d090f0d416f",
          "uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)",
          "etag":"\"1\"",
          "type":"SP.Data.Team_x0020_tasksListItem"
        },
        "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FirstUniqueAncestorSecurableObject"}},
        "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/RoleAssignments"}},
        "AttachmentFiles":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/AttachmentFiles"}},
        "ContentType":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/ContentType"}},
        "FieldValuesAsHtml":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FieldValuesAsHtml"}},
        "FieldValuesAsText":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FieldValuesAsText"}},
        "FieldValuesForEdit":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/FieldValuesForEdit"}},
        "File":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/File"}},
        "Folder":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/Folder"}},
        "ParentList":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(1)/ParentList"}},
        "FileSystemObjectType":0,
        "Id":1,
        "ID":1,
        "ContentTypeId":"0x0108004F8963A897E4E64A83E990C1B6B65770",
        "Title":"Triage requests",
        "Modified":"2013-09-03T17:49:26Z",
        "Created":"2013-09-03T17:49:26Z",
        "AuthorId":1073741823,
        "EditorId":1073741823,
        "OData__UIVersionString":"1.0",
        "Attachments":false,
        "GUID":"e132ef1b-698e-4d21-ba1b-29fa5c38fe8e",
        "PredecessorsId":{"results":[]},
        "Priority":"(2) Normal",
        "Status":"Not Started",
        "PercentComplete":0,
        "AssignedToId":{"results":[1,21]},
        "Body":null,
        "StartDate":"2014-01-01T08:00:00Z",
        "DueDate":"2014-01-02T08:00:00Z",
        "Checkmark":"0",
        "RelatedItems":null
        },{
        "__metadata":{
          "id":"687e63a4-ed44-4bf2-881f-c83e5d3fd020",
          "uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)",
          "etag":"\"5\"",
          "type":"SP.Data.Team_x0020_tasksListItem"
        },
        "FirstUniqueAncestorSecurableObject":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FirstUniqueAncestorSecurableObject"}},
        "RoleAssignments":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/RoleAssignments"}},
        "AttachmentFiles":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/AttachmentFiles"}},
        "ContentType":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ContentType"}},
        "FieldValuesAsHtml":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsHtml"}},
        "FieldValuesAsText":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesAsText"}},
        "FieldValuesForEdit":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/FieldValuesForEdit"}},
        "File":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/File"}},
        "Folder":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/Folder"}},
        "ParentList":{"__deferred":{"uri":"http://<site url>/_api/Web/Lists(guid'a290086b-2d43-4151-add4-893474a930a9')/Items(2)/ParentList"}},
        "FileSystemObjectType":0,
        "Id":2,
        "ID":2,
        "ContentTypeId":"0x0108004F8963A897E4E64A83E990C1B6B65770",
        "Title":"Assign teams",
        "Modified":"2013-09-03T19:24:51Z",
        "Created":"2013-09-03T17:50:30Z",
        "AuthorId":1073741823,
        "EditorId":1073741823,
        "OData__UIVersionString":"1.0",
        "Attachments":false,
        "GUID":"ce6e516e-2da4-4a3e-9325-daf7d7f61490",
        "PredecessorsId":{"results":[1]},
        "Priority":"(1) High",
        "Status":"In Progress",
        "PercentComplete":0.3,
        "AssignedToId":{"results":[1]},
        "Body":null,
        "StartDate":"2014-01-02T08:00:00Z",
        "DueDate":"2014-01-02T08:00:00Z",
        "Checkmark":"0",
        "RelatedItems":null
        },{
        …
      }]
    }}

View resource

Specifies a list view.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/lists(guid'<list id>')/views('<view id>')

Supported HTTP methods

GET  |  POST  |  DELETE  |  MERGE  |  PUT

Request examples

GET request example: Get a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can use the GetByTitle method from the ViewCollection resource to get a view by its (case-sensitive) title. Example: …/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views/getbytitle('By Status').

MERGE request example: Change a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.View' }, 'Title': 'New Mobile Default View',
    'MobileDefaultView': true, 'RowLimit': 5 }",
  headers: { 
    "content-type": "application/json;odata=verbose",
    "X-HTTP-Method": "MERGE"
  },
  success: successHandler,
  error: errorHandler
});

DELETE request example: Delete a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "POST",
  headers: { "X-HTTP-Method": "DELETE" },
  success: successHandler,
  error: errorHandler
});

To create a view, see ViewCollection request examples.

View properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/<property name>
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
Aggregations	String	RW	Yes	Gets or sets a value that specifies fields and functions that define totals shown in a list view. If not null, the XML must conform to FieldRefDefinitionAggregation, as specified in [MS-WSSCAML].
AggregationsStatus	String	RW	Yes	Gets or sets a value that specifies whether totals are shown in the list view.
BaseViewId	String	R	Yes	Gets a value that specifies the base view identifier of the list view.
ContentTypeId	SP.ContentTypeId	RW	Yes	Gets or sets the identifier of the content type with which the view is associated so that the view is available only on folders of this content type.
DefaultView	Boolean	RW	Yes	Gets or sets a value that specifies whether the list view is the default list view.
DefaultViewForContentType	Boolean	RW	Yes	Gets or sets a value that specifies whether the list view is the default list view for the content type specified by contentTypeId.
EditorModified	Boolean	RW	Yes	Gets or sets a value that specifies whether the list view was modified in an editor.
Formats	String	RW	Yes	Gets or sets a value that specifies the column and row formatting for the list view. If not null, the XML must conform to ViewFormatDefinitions, as specified in [MS-WSSCAML].
Hidden	Boolean	RW	Yes	Gets or sets a value that specifies whether the list view is hidden.
HtmlSchemaXml	String	R	Yes	Gets a value that specifies the XML document that represents the list view.
Id	GUID	R	Yes	Gets a value that specifies the view identifier of the list view.
ImageUrl	String	R	Yes	Gets a value that specifies the URI (Uniform Resource Identifier) of the image for the list view.
IncludeRootFolder	Boolean	RW	Yes	Gets or sets a value that specifies whether the current folder is displayed in the list view.
JsLink	String	RW	Yes	Gets or sets the name of the JavaScript file used for the view.
ListViewXml	String	RW	Yes	Gets or sets a string that represents the view XML.
Method	String	RW	Yes	Gets or sets a value that specifies the view method for the list view. If not null, the XML must conform to Method, as specified in [MS-WSSCAP].
MobileDefaultView	Boolean	RW	Yes	Gets or sets a value that specifies whether the list view is the default mobile list view.
MobileView	Boolean	RW	Yes	Gets or sets a value that specifies whether the list view is a mobile list view.
ModerationType	String	R	Yes	Gets a value that specifies the content approval type for the list view.
OrderedView	Boolean	R	Yes	Gets a value that specifies whether list items can be reordered in the list view.
Paged	Boolean	RW	Yes	Gets or sets a value that specifies whether the list view is a paged view.
PersonalView	Boolean	R	Yes	Gets a value that specifies whether the list view is a personal view.
ReadOnlyView	Boolean	R	Yes	Gets a value that specifies whether the list view is read-only.
RequiresClientIntegration	Boolean	R	Yes	Gets a value that specifies whether the list view requires client integration rights.
RowLimit	Int32	RW	Yes	Gets or sets a value that specifies the maximum number of list items to display in a visual page of the list view.
Scope	Int32	RW	Yes	Gets or sets a value that specifies the scope for the list view. Represents a ViewScope value. DefaultValue = 0, Recursive = 1, RecursiveAll = 2, FilesOnly = 3.
ServerRelativeUrl	String	R	Yes	Gets a value that specifies the server-relative URL of the list view page.
StyleId	String	R	Yes	Gets a value that specifies the identifier of the view style for the list view.
Threaded	Boolean	R	Yes	Gets a value that specifies whether the list view is a threaded view.
Title	String	RW	Yes	Gets or sets a value that specifies the display name of the list view.
Toolbar	String	RW	Yes	Gets or sets a value that specifies the toolbar for the list view.
ToolbarTemplateName	String	R	Yes	Gets a value that specifies the name of the template for the toolbar that is used in the list view.
ViewData	String	RW	Yes	Gets or sets a value that specifies the view data for the list view. If not null, the XML must conform to FieldRefDefinitionViewData, as specified in [MS-WSSCAML].
ViewFields	SP.ViewFieldCollection	R	No	Gets a value that specifies the collection of fields in the list view.
ViewJoins	String	RW	Yes	Gets or sets a value that specifies the joins that are used in the list view. If not null, the XML must conform to ListJoinsDefinition, as specified in [MS-WSSCAML].
ViewProjectedFields	String	RW	Yes	Gets or sets a value that specifies the projected fields that will be used by the list view. If not null, the XML must conform to ProjectedFieldsDefinitionType, as specified in [MS-WSSCAML].
ViewQuery	String	RW	Yes	Gets or sets a value that specifies the query that is used by the list view. If not null, the XML must conform to CamlQueryRoot, as specified in [MS-WSSCAML].
ViewType	String	R	Yes	Gets a value that specifies the type of the list view. Can be HTML, GRID, CALENDAR, RECURRENCE, CHART, or GANTT.

View methods

DeleteObject
RenderAsHtml

DeleteObject method

The recommended way to delete a view is to send a DELETE request to the View resource endpoint, as shown in View request examples.

RenderAsHtml method

Returns the list view as HTML.

Endpoint	/renderashtml
Parameters	None
HTTP method	GET
Response	Type: String The list view rendered in HTML format.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    /renderashtml
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a View resource in JSON format.

    {"d":{
      "__metadata":{,
        "id":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
        "uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
        "type":"SP.View"
      },
      "ViewFields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/ViewFields"}},
      "Aggregations":null,
      "AggregationsStatus":null,
      "BaseViewId":"2",
      "ContentTypeId":{"__metadata":{"type":"SP.ContentTypeId"}, "StringValue":"0x"},
      "DefaultView":false,
      "DefaultViewForContentType":false,
      "EditorModified":false,
      "Formats":null,
      "Hidden":false,
      "HtmlSchemaXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\"><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><RowLimit Paged=\"TRUE\">100</RowLimit><Toolbar Type=\"Standard\" /><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><ViewData><FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" /></ViewData><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query></View>",
      "Id":"0dc42244-4bae-4da9-b074-8b8e9d8e50bc",
      "ImageUrl":"/_layouts/15/images/issuelst.png?rev=31",
      "IncludeRootFolder":false,
      "ViewJoins":null,
      "JSLink":"hierarchytaskslist.js",
      "ListViewXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\" ><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><RowLimit Paged=\"TRUE\">100</RowLimit><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><Toolbar Type=\"Standard\"/></View>",
      "Method":null,
      "MobileDefaultView":false,
      "MobileView":true,
      "ModerationType":null,
      "OrderedView":false,
      "Paged":true,
      "PersonalView":false,
      "ViewProjectedFields":null,
      "ViewQuery":"<Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy>",
      "ReadOnlyView":false,
      "RequiresClientIntegration":false,
      "RowLimit":100,
      "Scope":0,
      "ServerRelativeUrl":"/Lists/Backlog items/late.aspx",
      "StyleId":null,
      "Threaded":false,
      "Title":"Late Tasks",
      "Toolbar":"",
      "ToolbarTemplateName":null,
      "ViewType":"HTML",
      "ViewData":"<FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" />"
    }}

ViewCollection resource

Represents a collection of View resources.

Endpoint URI  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/lists(guid'<list id>')/views

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get all views for a list

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

GET request example: Get a specific view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can use the GetByTitle method from the ViewCollection resource to get a view by its (case-sensitive) title. Example: …/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views/getbytitle('By Status').

POST request example: Create a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    ?@target='<host web url>'",
  method: "POST",
  body: "{ '__metadata': { 'type': 'SP.View' }, 'Title': 'By Status',
    'PersonalView': false }",
  headers: { 
    "accept": "application/json;odata=verbose",
    "content-type": "application/json;odata=verbose"
  },
  success: successHandler,
  error: errorHandler
});

When you create a view, the server returns the view. To add, remove, or change the order of view fields for the new view, use the ViewFieldCollection methods.

ViewCollection methods

GetById
GetByTitle

GetById method

Gets the list view with the specified ID.

Endpoint	/getbyid('<view id>')
Parameters	Type: String The ID of the view.
HTTP method	GET
Response	Type: SP.View The specified view.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    /getbyid('0dc42244-4bae-4da9-b074-8b8e9d8e50bc')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Or, you can just pass the view ID to the ViewCollection resource. Example: …/web/lists(guid'51925dd7-2108-481a-b1ef-4bfa4e69d48b')/views('0dc42244-4bae-4da9-b074-8b8e9d8e50bc').

GetByTitle method

Gets the list view with the specified title.

Endpoint	/getbytitle('<view title>')
Parameters	Type: String The case-sensitive title of the view.
HTTP method	GET
Response	Type: SP.View The specified view.

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views
    /getbytitle('By Status')
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a ViewCollection resource in JSON format.

    {"d":{
      "results":[{
        "__metadata":{
          "id":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
          "uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
          "type":"SP.View"
        },
        "ViewFields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/ViewFields"}},
        "Aggregations":null,
        "AggregationsStatus":null,
        "BaseViewId":"1",
        "ContentTypeId":{"__metadata":{"type":"SP.ContentTypeId"},"StringValue":"0x"},
        "DefaultView":true,
        "DefaultViewForContentType":false,
        "EditorModified":false,
        "Formats":null,
        "Hidden":false,
        "HtmlSchemaXml":"<View Name=\"{9824C4FF-14FD-4F24-B481-FA33D90F2D85}\" DefaultView=\"TRUE\" MobileView=\"TRUE\" MobileDefaultView=\"TRUE\" Type=\"HTML\" DisplayName=\"All Tasks\" Url=\"/Lists/Backlog items/AllItems.aspx\" Level=\"1\" BaseViewID=\"1\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\"><Toolbar Type=\"Standard\" /><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /><FieldRef Name=\"Status0\" /></ViewFields><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><RowLimit Paged=\"TRUE\">100</RowLimit><ViewData><FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" /></ViewData></View>"
        "Id":"9824c4ff-14fd-4f24-b481-fa33d90f2d85",
        "ImageUrl":"/_layouts/15/images/issuelst.png?rev=31",
        "IncludeRootFolder":false,
        "ViewJoins":null,
        "JSLink":"hierarchytaskslist.js",
        "ListViewXml":"<View Name=\"{9824C4FF-14FD-4F24-B481-FA33D90F2D85}\" DefaultView=\"TRUE\" MobileView=\"TRUE\" MobileDefaultView=\"TRUE\" Type=\"HTML\" DisplayName=\"All Tasks\" Url=\"/Lists/Backlog items/AllItems.aspx\" Level=\"1\" BaseViewID=\"1\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\" ><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /><FieldRef Name=\"Status0\" /></ViewFields><RowLimit Paged=\"TRUE\">100</RowLimit><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><Toolbar Type=\"Standard\"/></View>",
        "Method":null,
        "MobileDefaultView":true,
        "MobileView":true,
        "ModerationType":null,
        "OrderedView":false,
        "Paged":true,
        "PersonalView":false,
        "ViewProjectedFields":null,
        "ViewQuery":null
        "ReadOnlyView":false,
        "RequiresClientIntegration":false,
        "RowLimit":100,
        "Scope":0,
        "ServerRelativeUrl":"/Lists/Backlog items/AllItems.aspx",
        "StyleId":null,
        "Threaded":false,
        "Title":"All Tasks",
        "Toolbar":"",
        "ToolbarTemplateName":null,
        "ViewType":"HTML",
        "ViewData":"<FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" />"}}"
      },{
        "__metadata":{
          "id":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
          "uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')",
          "type":"SP.View"
        },
        "ViewFields":{"__deferred":{"uri":"https://<site url>/_api/Web/Lists(guid'da58632f-faf0-4a78-8219-99c307747741')/Views(guid'0dc42244-4bae-4da9-b074-8b8e9d8e50bc')/ViewFields"}},
        "Aggregations":null,
        "AggregationsStatus":null,
        "BaseViewId":"2",
        "ContentTypeId":{"__metadata":{"type":"SP.ContentTypeId"},"StringValue":"0x"},
        "DefaultView":false,
        "DefaultViewForContentType":false,
        "EditorModified":false,
        "Formats":null,
        "Hidden":false,
        "HtmlSchemaXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\"><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><RowLimit Paged=\"TRUE\">100</RowLimit><Toolbar Type=\"Standard\" /><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><ViewData><FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" /></ViewData><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query></View>",
        "Id":"0dc42244-4bae-4da9-b074-8b8e9d8e50bc",
        "ImageUrl":"/_layouts/15/images/issuelst.png?rev=31",
        "IncludeRootFolder":false,
        "ViewJoins":null,
        "JSLink":"hierarchytaskslist.js",
        "ListViewXml":"<View Name=\"{0DC42244-4BAE-4DA9-B074-8B8E9D8E50BC}\" MobileView=\"TRUE\" Type=\"HTML\" DisplayName=\"Late Tasks\" Url=\"/Lists/Backlog items/late.aspx\" Level=\"1\" BaseViewID=\"2\" ContentTypeID=\"0x\" ImageUrl=\"/_layouts/15/images/issuelst.png?rev=31\" ><Query><Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy></Query><ViewFields><FieldRef Name=\"Checkmark\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" /><FieldRef Name=\"AssignedTo\" /></ViewFields><RowLimit Paged=\"TRUE\">100</RowLimit><JSLink>hierarchytaskslist.js</JSLink><XslLink Default=\"TRUE\">main.xsl</XslLink><Toolbar Type=\"Standard\"/></View>",
        "Method":null,
        "MobileDefaultView":false,
        "MobileView":true,
        "ModerationType":null,
        "OrderedView":false,
        "Paged":true,
        "PersonalView":false,
        "ViewProjectedFields":null,
        "ViewQuery":"<Where><And><Or><IsNull><FieldRef Name=\"PercentComplete\" /></IsNull><Neq><FieldRef Name=\"PercentComplete\" /><Value Type=\"Number\">1</Value></Neq></Or><Lt><FieldRef Name=\"DueDate\" /><Value Type=\"DateTime\"><Today /></Value></Lt></And></Where><OrderBy><FieldRef Name=\"DueDate\" /><FieldRef Name=\"Priority\" /></OrderBy>",
        "ReadOnlyView":false,
        "RequiresClientIntegration":false,
        "RowLimit":100,
        "Scope":0,
        "ServerRelativeUrl":"/Lists/Backlog items/late.aspx",
        "StyleId":null,
        "Threaded":false,
        "Title":"Late Tasks",
        "Toolbar":"",
        "ToolbarTemplateName":null,
        "ViewType":"HTML",
        "ViewData":"<FieldRef Name=\"PercentComplete\" Type=\"StrikeThroughPercentComplete\" /><FieldRef Name=\"DueDate\" Type=\"TimelineDueDate\" />"
      },{
        …
      }]
    }}

ViewFieldCollection resource

Represents a collection of fields in a list view.

Endpoint URI  |  Properties  |  Methods  |  OData representation

Endpoint URI

http://<site url>/_api/web/lists(guid'<list id>')/views('<view id>')/viewfields

Supported HTTP methods

GET  |  POST

Request examples

GET request example: Get all the fields in a view

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

ViewFieldCollection properties

To get a property, send a GET request to the property endpoint, as shown in the following example.

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields/schemaxml
    ?@target='<host web url>'",
  method: "GET",
  headers: { "accept": "application/json; odata=verbose" },
  success: successHandler,
  error: errorHandler
});

Property	Type	R/W	Returned with resource	Description
SchemaXml	String	R	Yes	Gets a value that specifies the XML schema that represents the collection.
Items	Collection(String)	R	Yes	Specifies the XML schema of the collection of fields. The Items property is returned with the resource, but it doesn't have a URI-addressable endpoint.

ViewFieldCollection methods

AddViewField
MoveViewFieldTo
RemoveAllViewFields
RemoveViewField

AddViewField method

Adds the field with the specified field internal name or display name to the collection.

Endpoint	/addviewfield('<field name>')
Parameters	Type: String The case-sensitive internal name or display name of the field to add.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /addviewfield('AssignedTo')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

MoveViewFieldTo method

Moves the field with the specified field internal name to the specified position in the collection.

Endpoint	/moveviewfieldto
Parameters	field Type: String The case-sensitive internal name of the field to move. Send this parameter and the index parameter in the request body, as shown in the example. index Type: Int32 The zero-based index of the new position for the field. Send this parameter and the field parameter in the request body, as shown in the example.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /moveviewfieldto
    ?@target='<host web url>'",
  method: "POST",
  body: "{ 'field': 'DueDate', 'index': 0 }",
  headers: { "content-type": "application/json;odata=verbose" },
  success: successHandler,
  error: errorHandler
});

RemoveAllViewFields method

Removes all the fields from the collection.

Endpoint	/removeallviewfields
Parameters	None
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /removeallviewfields
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

RemoveViewField method

Removes the field with the specified field internal name from the collection.

Endpoint	/removeviewfield('<field name>')
Parameters	Type: String The case-sensitive internal name of the field to remove from the view.
HTTP method	POST
Response	None

  Request example

executor.executeAsync({
  url: "<app web url>/_api/SP.AppContextSite(@target)/web
    /lists(guid'da58632f-faf0-4a78-8219-99c307747741')
    /views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields
    /removeviewfield('AssignedTo')
    ?@target='<host web url>'",
  method: "POST",
  success: successHandler,
  error: errorHandler
});

OData representation

The following example represents a ViewFieldCollection resource in JSON format.

    {"d":{
      "__metadata":{
        "id":"https://<site url>/_api/SP.AppContextSite(@target)/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields",
        "uri":"https://<site url>/_api/SP.AppContextSite(@target)/web/lists(guid'da58632f-faf0-4a78-8219-99c307747741')/views('d82d3e67-f317-413c-8f27-590317a40f20')/viewfields",
        "type":"SP.ViewFieldCollection"
      },
      "SchemaXml":"<FieldRef Name=\"Checkmark\" /><FieldRef Name=\"Status\" /><FieldRef Name=\"LinkTitle\" /><FieldRef Name=\"DueDate\" />",
      "Items":{"results":["Checkmark", "Status", "LinkTitle", "DueDate"]}
    }}

Additional resources

• Working with lists and list items with REST

• How to: Complete basic operations using SharePoint 2013 REST endpoints

• How to: Access SharePoint 2013 data from apps using the cross-domain library

• OAuth authentication and authorization flow for cloud-hosted apps

• Use OData query operations in SharePoint REST requests

• How to: Set custom permissions on a list by using the REST interface

• REST API reference and samples

• Get started with the SharePoint 2013 REST service