Shelvesets - Get

Get a single deep shelveset.

GET https://{instance}/{collection}/_apis/tfvc/shelvesets?shelvesetId={shelvesetId}&api-version=5.0
GET https://{instance}/{collection}/_apis/tfvc/shelvesets?shelvesetId={shelvesetId}&requestData.includeLinks={requestData.includeLinks}&requestData.includeWorkItems={requestData.includeWorkItems}&requestData.includeDetails={requestData.includeDetails}&requestData.maxChangeCount={requestData.maxChangeCount}&requestData.maxCommentLength={requestData.maxCommentLength}&requestData.owner={requestData.owner}&requestData.name={requestData.name}&api-version=5.0

URI Parameters

Name In Required Type Description
collection
path True

string

The name of the Azure DevOps collection.

instance
path True

string

Azure DevOps server name ({server:port})

api-version
query True

string

Version of the API to use. This should be set to '5.0' to use this version of the api.

shelvesetId
query True

string

Shelveset's unique ID

requestData.includeDetails
query

boolean

Whether to include policyOverride and notes Only applies when requesting a single deep shelveset

requestData.includeLinks
query

boolean

Whether to include the _links field on the shallow references. Does not apply when requesting a single deep shelveset object. Links will always be included in the deep shelveset.

requestData.includeWorkItems
query

boolean

Whether to include workItems

requestData.maxChangeCount
query

integer

int32

Max number of changes to include

requestData.maxCommentLength
query

integer

int32

Max length of comment

requestData.name
query

string

Shelveset's name

requestData.owner
query

string

Owner's ID. Could be a name or a guid.

Responses

Name Type Description
200 OK

TfvcShelveset

successful operation

Security

oauth2

Type: oauth2
Flow: accessCode
Authorization URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL: https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer

Scopes

Name Description
vso.code Grants the ability to read source code and metadata about commits, changesets, branches, and other version control artifacts. Also grants the ability to search code and get notified about version control events via service hooks.

Examples

Basic example
IncludeDetails
Owner
Shelveset by Id with maxCommentLength
ShelvesetId
top and skip
With maxCommentLength

Basic example

Sample Request

GET https://{instance}/fabrikam/_apis/tfvc/shelvesets?shelvesetId=My first shelveset;fabrikamfiber16@hotmail.com&api-version=5.0

Sample Response

{
  "count": 4,
  "value": [
    {
      "name": "My first shelveset",
      "id": "My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:37:52.277Z",
      "comment": "Here is a really long comment describing this shelveset.",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "More changes",
      "id": "More changes;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:29:45.91Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/More%20changes%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "Doc updates",
      "id": "Doc updates;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:27:25.18Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/Doc%20updates%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "Set this aside for now",
      "id": "Set this aside for now;8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
      "owner": {
        "id": "8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabrikamfiber3@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
      },
      "createdDate": "2014-03-24T20:32:25.37Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/Set%20this%20aside%20for%20now%3b8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
    }
  ]
}

IncludeDetails

Sample Request

GET https://{instance}/fabrikam/_apis/tfvc/shelvesets?shelvesetId=My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db&api-version=5.0

Sample Response

{
  "policyOverride": {
    "policyFailures": []
  },
  "notes": [],
  "name": "My first shelveset",
  "id": "My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db",
  "owner": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2014-07-18T03:37:52.277Z",
  "comment": "Here is a really long comment describing this shelveset.",
  "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db",
  "_links": {
    "self": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    "changes": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db/changes"
    },
    "workItems": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db/workitems"
    },
    "owner": {
      "href": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db"
    }
  }
}

Owner

Sample Request

GET https://{instance}/fabrikam/_apis/tfvc/shelvesets?api-version=5.0

Sample Response

{
  "count": 3,
  "value": [
    {
      "name": "My first shelveset",
      "id": "My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:37:52.277Z",
      "comment": "Here is a really long comment describing this shelveset.",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "More changes",
      "id": "More changes;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:29:45.91Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/More%20changes%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "Doc updates",
      "id": "Doc updates;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:27:25.18Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/Doc%20updates%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    }
  ]
}

Shelveset by Id with maxCommentLength

Sample Request

GET https://{instance}/fabrikam/_apis/tfvc/shelvesets?shelvesetId=My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db&api-version=5.0

Sample Response

{
  "name": "My first shelveset",
  "id": "My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db",
  "owner": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2014-07-18T03:37:52.277Z",
  "comment": "Here i",
  "commentTruncated": true,
  "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db",
  "_links": {
    "self": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    "changes": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db/changes"
    },
    "workItems": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db/workitems"
    },
    "owner": {
      "href": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db"
    }
  }
}

ShelvesetId

Sample Request

GET https://{instance}/fabrikam/_apis/tfvc/shelvesets?shelvesetId=My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db&api-version=5.0

Sample Response

{
  "name": "My first shelveset",
  "id": "My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db",
  "owner": {
    "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
    "displayName": "Normal Paulk",
    "uniqueName": "fabrikamfiber16@hotmail.com",
    "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
    "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
  },
  "createdDate": "2014-07-18T03:37:52.277Z",
  "comment": "Here is a really long comment describing this shelveset.",
  "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db",
  "_links": {
    "self": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    "changes": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db/changes"
    },
    "workItems": {
      "href": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db/workitems"
    },
    "owner": {
      "href": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db"
    }
  }
}

top and skip

Sample Request

GET https://{instance}/fabrikam/_apis/tfvc/shelvesets?api-version=5.0

Sample Response

{
  "count": 2,
  "value": [
    {
      "name": "Doc updates",
      "id": "Doc updates;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:27:25.18Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/Doc%20updates%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "Set this aside for now",
      "id": "Set this aside for now;8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
      "owner": {
        "id": "8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabrikamfiber3@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
      },
      "createdDate": "2014-03-24T20:32:25.37Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/Set%20this%20aside%20for%20now%3b8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
    }
  ]
}

With maxCommentLength

Sample Request

GET https://{instance}/fabrikam/_apis/tfvc/shelvesets?api-version=5.0

Sample Response

{
  "count": 4,
  "value": [
    {
      "name": "My first shelveset",
      "id": "My first shelveset;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:37:52.277Z",
      "comment": "Here i",
      "commentTruncated": true,
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/My%20first%20shelveset%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "More changes",
      "id": "More changes;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:29:45.91Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/More%20changes%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "Doc updates",
      "id": "Doc updates;d6245f20-2af8-44f4-9451-8107cb2767db",
      "owner": {
        "id": "d6245f20-2af8-44f4-9451-8107cb2767db",
        "displayName": "Normal Paulk",
        "uniqueName": "fabrikamfiber16@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/d6245f20-2af8-44f4-9451-8107cb2767db",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=d6245f20-2af8-44f4-9451-8107cb2767db"
      },
      "createdDate": "2014-07-18T03:27:25.18Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/Doc%20updates%3bd6245f20-2af8-44f4-9451-8107cb2767db"
    },
    {
      "name": "Set this aside for now",
      "id": "Set this aside for now;8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
      "owner": {
        "id": "8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
        "displayName": "Chuck Reinhart",
        "uniqueName": "fabrikamfiber3@hotmail.com",
        "url": "https://fabrikam:8080/tfs/_apis/Identities/8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d",
        "imageUrl": "https://fabrikam:8080/tfs/_api/_common/identityImage?id=8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
      },
      "createdDate": "2014-03-24T20:32:25.37Z",
      "url": "https://fabrikam:8080/tfs/_apis/tfvc/shelvesets/Set%20this%20aside%20for%20now%3b8c8c7d32-6b1b-47f4-b2e9-30b477b5ab3d"
    }
  ]
}

Definitions

Name Description
AssociatedWorkItem
CheckinNote
IdentityRef
ItemContent
ItemContentType
ReferenceLinks

The class to represent a collection of REST reference links.

TfvcChange
TfvcMergeSource
TfvcPolicyFailureInfo
TfvcPolicyOverrideInfo
TfvcShelveset

This is the deep shelveset class

VersionControlChangeType

The type of change that was made to the item.

AssociatedWorkItem

Name Type Description
assignedTo

string

id

integer

Id of associated the work item.

state

string

title

string

url

string

REST Url of the work item.

webUrl

string

workItemType

string

CheckinNote

Name Type Description
name

string

value

string

IdentityRef

Name Type Description
_links

ReferenceLinks

This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject.

descriptor

string

The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and collections.

directoryAlias

string

displayName

string

This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider.

id

string

imageUrl

string

inactive

boolean

isAadIdentity

boolean

isContainer

boolean

isDeletedInOrigin

boolean

profileUrl

string

uniqueName

string

url

string

This url is the full route to the source resource of this graph subject.

ItemContent

Name Type Description
content

string

contentType

ItemContentType

ItemContentType

Name Type Description
base64Encoded

string

rawText

string

The class to represent a collection of REST reference links.

Name Type Description
links

object

The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

TfvcChange

Name Type Description
changeType

VersionControlChangeType

The type of change that was made to the item.

item

string

Current version.

mergeSources

TfvcMergeSource[]

List of merge sources in case of rename or branch creation.

newContent

ItemContent

Content of the item after the change.

pendingVersion

integer

Version at which a (shelved) change was pended against

sourceServerItem

string

Path of the item on the server.

url

string

URL to retrieve the item.

TfvcMergeSource

Name Type Description
isRename

boolean

Indicates if this a rename source. If false, it is a merge source.

serverItem

string

The server item of the merge source

versionFrom

integer

Start of the version range

versionTo

integer

End of the version range

TfvcPolicyFailureInfo

Name Type Description
message

string

policyName

string

TfvcPolicyOverrideInfo

Name Type Description
comment

string

policyFailures

TfvcPolicyFailureInfo[]

TfvcShelveset

This is the deep shelveset class

Name Type Description
_links

ReferenceLinks

The class to represent a collection of REST reference links.

changes

TfvcChange[]

comment

string

commentTruncated

boolean

createdDate

string

id

string

name

string

notes

CheckinNote[]

owner

IdentityRef

policyOverride

TfvcPolicyOverrideInfo

url

string

workItems

AssociatedWorkItem[]

VersionControlChangeType

The type of change that was made to the item.

Name Type Description
add

string

all

string

branch

string

delete

string

edit

string

encoding

string

lock

string

merge

string

none

string

property

string

rename

string

rollback

string

sourceRename

string

targetRename

string

undelete

string