Share via

Items - Get

  • Reference
Service:
Tfvc
API Version:
7.1

Get Item Metadata and/or Content for a single item. The download parameter is to indicate whether the content should be available as a download or just sent as a stream in the response. Doesn't apply to zipped content which is always returned as a download.

GET https://dev.azure.com/{organization}/{project}/_apis/tfvc/items?path={path}&api-version=7.1
With optional parameters: 
GET https://dev.azure.com/{organization}/{project}/_apis/tfvc/items?path={path}&fileName={fileName}&download={download}&scopePath={scopePath}&recursionLevel={recursionLevel}&versionDescriptor.version={versionDescriptor.version}&versionDescriptor.versionOption={versionDescriptor.versionOption}&versionDescriptor.versionType={versionDescriptor.versionType}&includeContent={includeContent}&api-version=7.1

URI Parameters

Name In Required Type Description
organization
 path True

string

The name of the Azure DevOps organization.
project
 path

string

Project ID or project name
api-version
 query True

string

Version of the API to use. This should be set to '7.1' to use this version of the api.
path
 query True

string

Version control path of an individual item to return.
download
 query

boolean

If true, create a downloadable attachment.
fileName
 query

string

file name of item returned.
includeContent
 query

boolean

Set to true to include item content when requesting json. Default is false.
recursionLevel
 query

VersionControlRecursionType

None (just the item), or OneLevel (contents of a folder).
scopePath
 query

string

Version control path of a folder to return multiple items.
versionDescriptor.version
 query

string

Version object.
versionDescriptor.versionOption
 query

TfvcVersionOption

Version descriptor. Default is null.
versionDescriptor.versionType
 query

TfvcVersionType

Version descriptor. Default is null.

Responses

Name Type Description
200 OK

TfvcItem

successful operation

Media Types: "text/plain", "application/octet-stream", "application/zip", "application/json"

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

GET item metadata and/or content for a single item.

Sample request

GET https://dev.azure.com/{organization}/_apis/tfvc/items?path=$/MyFirstProject/ExampleFolder/TestFile01.txt&api-version=7.1

Sample response

Status code:
200 
{
  "version": 10,
  "changeDate": "2019-05-29T18:00:23.457Z",
  "size": 4,
  "hashValue": "CY9rzUYh03PK3k6DJie09g==",
  "encoding": 65001,
  "path": "$/MyFirstProject/ExampleFolder/TestFile01.txt",
  "contentMetadata": {
    "encoding": 65001,
    "contentType": "text/plain",
    "fileName": "TestFile01.txt",
    "extension": ".txt",
    "vsLink": "vsweb://vs/?Product=Visual_Studio&Gen=2013&EncFormat=UTF8&tfslink=dnN0ZnM6Ly8vVmVyc2lvbkNvbnRyb2wvTGF1bmNoTGF0ZXN0VmVyc2lvbmVkSXRlbS8lMjQlMmZNeUZpcnN0UHJvamVjdCUyZkV4YW1wbGVGb2xkZXIlMmZUZXN0RmlsZTAxLnR4dD9wcm9qZWN0PTg3NDQ2MjJkLTdmMGUtNDZlZi04ZjViLWUxNzk2MjNhNGI1YyZ1cmw9aHR0cHMlM0ElMkYlMkZjb2RlZGV2Lm1zJTJGa2V2aW5tY3B6NDIwJTJG"
  },
  "url": "https://codedev.ms/fabrikam/_apis/tfvc/items/$/MyFirstProject/ExampleFolder/TestFile01.txt?versionType=Latest&versionOptions=None",
  "_links": {
    "self": {
      "href": "https://codedev.ms/fabrikam/_apis/tfvc/items/$/MyFirstProject/ExampleFolder/TestFile01.txt?versionType=Changeset&version=10"
    }
  }
}

Definitions

Name Description
FileContentMetadata
ReferenceLinks

The class to represent a collection of REST reference links.
TfvcItem

Metadata for an item.
TfvcVersionOption

Defaults to None.
TfvcVersionType

Defaults to Latest.
VersionControlRecursionType

Defaults to OneLevel.

FileContentMetadata

Name Type Description
contentType

string

encoding

integer

extension

string

fileName

string

isBinary

boolean

isImage

boolean

vsLink

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.

TfvcItem

Metadata for an item.

Name Type Description
_links

ReferenceLinks

The class to represent a collection of REST reference links.
changeDate

string

Item changed datetime.
content

string

contentMetadata

FileContentMetadata

deletionId

integer

Greater than 0 if item is deleted.
encoding

integer

File encoding from database, -1 represents binary.
hashValue

string

MD5 hash as a base 64 string, applies to files only.
isBranch

boolean

True if item is a branch.
isFolder

boolean

isPendingChange

boolean

True if there is a change pending.
isSymLink

boolean

path

string

size

integer

The size of the file, if applicable.
url

string

version

integer

Changeset version Id.

TfvcVersionOption

Defaults to None.

Name Type Description
none

string

None.
previous

string

Return the previous version.
useRename

string

Only usuable with versiontype MergeSource and integer versions, uses RenameSource identifier instead of Merge identifier.

TfvcVersionType

Defaults to Latest.

Name Type Description
change

string

Version is treated as a Change.
changeset

string

Version is treated as a ChangesetId.
date

string

Version is treated as a Date.
latest

string

If Version is defined the Latest of that Version will be used, if no version is defined the latest ChangesetId will be used.
mergeSource

string

Version will be treated as a MergeSource.
none

string

Version is treated as a ChangesetId.
shelveset

string

Version is treated as a Shelveset name and owner.
tip

string

Version will be treated as a Tip, if no version is defined latest will be used.

VersionControlRecursionType

Defaults to OneLevel.

Name Type Description
full

string

Return specified item and all descendants
none

string

Only return the specified item.
oneLevel

string

Return the specified item and its direct children.
oneLevelPlusNestedEmptyFolders

string

Return the specified item and its direct children, as well as recursive chains of nested child folders that only contain a single folder.