Microsoft TFS API Python client
Clone or download
allburov Merge pull request #51 from devopshq/docs/rest-client
URI parameters for running WIQL
Latest commit 47d67f2 Oct 5, 2018

Microsoft TFS Python Library (TFS API Python client)

docs dohq-tfs build status dohq-tfs code quality dohq-tfs code coverage dohq-tfs on PyPI dohq-tfs license

Table of Contents


Microsoft Team Foundation Server Python Library is a Microsoft TFS API Python client that can work with Microsoft TFS workflow and workitems.

This python library allows:

  1. Get WorkItems (WI)
  2. Set WI fields
  3. Run WI search queries
  4. Run WIQL
  5. Work with TFVC changesets
  6. Work with TFS Projects


pip install dohq-tfs

Create connection

from tfs import TFSAPI


# Use DefaultCollection
client = TFSAPI("", user=user, password=password)

# Use CustomCollection
client = TFSAPI("", project="DefaultCollection", user=user, password=password)

# Set path to ProjectName in project parameter
client = TFSAPI("", project="DefaultCollection/ProjectName", user=user, password=password)

workitem = client.get_workitem(100) # Test connection with Workitem id


You can use password or personal access token in password field.

# DEFAULT - Use HTTP Basic Auth
client = TFSAPI("", user=user, password=password)
client = TFSAPI("", user=user, password=personal_access_token)

# Use NTLM authorization
from requests_ntlm import HttpNtlmAuth
client = TFSAPI("", user=user, password=password, auth_type=HttpNtlmAuth)

# Use HttpNegotiateAuth for single-sign-on with Kerberos
# see more
import requests
from requests_negotiate_sspi import HttpNegotiateAuth
client = TFSAPI("", auth_type=HttpNegotiateAuth)

Timeout connection

You can set CONNECT and READ timeouts (read more)

from tfs import TFSAPI
client = TFSAPI("", user=user, password=password, connect_timeout=30, read_timeout=None)


# For single Workitem
workitem = client.get_workitem(100)

# For multiple
workitem = client.get_workitems([100,101,102]) # list
workitem = client.get_workitems("100,101,102") # string separated with comma

# Get all fields

# Case insensetive. Remove space in field name

# Workitem Parent Workitem
parent = workitem.parent
if parent: # Parent is None if Workitem hasn't Parent link
    print("Workitem with id={} have parent={}".format(,

# Workitem Childs Workitem
childs = workitem.childs
if childs: # Child is empty list if Workitem hasn't Child link
    print("Workitem with id={} have Childs={}".format(, ",".join([ for x in childs])))

# Workitem revisions
revisions = workitem.revisions

Create or copy workitem

# Create new bug
workitem = client.create_workitem('Bug')

# Create new task with some fields (use field reference names, e.g. System.*)
fields = {'System.Title': 'My task', 
          'System.Description': 'My description', 
          'System.AssignedTo': 'John Doe',
          'MyCompany.MyCustomField': 'MyCustomValue'}
workitem = client.create_workitem('Task', fields=fields)

# Copy with links and attachments and without sending notifications
new_wi = client.copy_workitem(workitem, with_links_and_attachments=True, suppress_notifications=True)

Update workitem

# Update field
workitem['state'] = 'Complete' 

# Add comment
workitem['History'] = "Omg, it is a good issue!"

Workitem attachments

If workitem has attachments, you can download it and get info about.

attachments = workitem.attachments
attachment = attachments[0]
# Internal TFS UID

# Filename

# TFS Download URL

# You can download file to folder'/home/user/folder') 

# All raw data

Run Saved Queries

You can run Saved Queries and get Workitems

# Set path to ProjectName in project parameter
client = TFSAPI("", project="DefaultCollection/ProjectName", user=user, password=password)

# Run New query 1 in Shared Queries folder
quiery = client.run_query('Shared Queries/New query 1')

# result content raw data
result = quiery.result

# Get all found workitems
workitems = quiery.workitems


You can run Work Item Query Language

# Set path to ProjectName in project parameter
client = TFSAPI("", project="DefaultCollection/ProjectName", user=user, password=password)

# Run custom query
### NOTE: Fields in SELECT really ignored, wiql return Work Items with all fields
query = """SELECT
FROM workitems
    [System.WorkItemType] = 'Bug'
ORDER BY [System.ChangedDate]"""

wiql = client.run_wiql(query)

# Get found Work Item ids
ids = wiql.workitem_ids
print("Found WI with ids={}".format(",".join(ids)))

# Get RAW query data - python dict
raw = wiql.result

# Get all found workitems
workitems = wiql.workitems

You can add extra URI parameters as a dictionary (only works for parameters that come at the end of the link):

wiql = client.run_query(query, params={'$top': 10, 'timePrecision': True, 'api-version': '1.0'})



If you cannot create or update a work item, here are some possible reasons:

  • check if the account you use has enough permissions in the collection/project;
  • make sure you follow your workflow, work items might have required fields or any other sort of restrictions;
  • verify that the api version fits your team foundation server version;

If neither of these helped your case, look through our issues list. If there is no similar issue, create one.


If you use this library, put a star on this repository. This motivates us and other developers to develop the library :)


  • Tested with Python.3.4
  • TFS 2015
  • TFS 2017


About contribute