Introduction to the TeamworkPM API


The TeamworkPM API can response to XML or JSON requests over HTTP using all four standard HTTP verbs (GET/PUT/POST/DELETE). All objects like messages, comments, task lists and tasks have their own URL and can be accessed in a standard and intuitive manner - eg. a GET verb call on a message like /message/85872.xml will return the data and a DELETE verb call to /message/85872.xml will delete it.

So how do you get started?

  1. OK, first things first... lets get your API key. Log into your Teamwork site and go to your "My Details" page in the upper right of the screen. On this page you will see an option to enable the API for your account. Enable the API and you will be provided with an API key. This is your unique code for exclusive use with the API. Copy this API key. Details instructions...
  2. Now, open any web browser and browse to http://[your_site]/projects.xml
  3. Now a dialog should appear asking for your username and password. Paste your API key from step 1 into the username field and hit "OK". (Any password will do).

That's it, you will now be looking at the full list of projects (that you have permissions to see) in XML format.

Try switching the format

To be honest, I hate XML, It's overweight and ugly like a bad prom date. To switch to JSON format, simply change the ".xml" to ".json". So browse to http://[your_site]/projects.json instead. There that's much better. However for consistency, we use the XML samples throughout this documentation but please feel free to use the slimmer sexier JSON.

Authentication

Authentication is managed using HTTP authentication (only "Basic" is supported right now). Every request must include the Authorization HTTP header. Use your API token as the username, and "X" (or some otherwise bogus text) as the password (only the API token is used for authenticating API requests).

Example with Curl:

curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
-u APIKEY0123456789:xxx -d '<request>...</request>' http://yours.teamworkpm.net

Example with ColdFusion:

<cfset theURL = "http://yoursite.teamworkpm.net/projects.xml">
<cfhttp url="#theURL#" method="GET" username="#username#" password="#password#"></cfhttp>

Your API token can be found by logging into your TeamworkPM account, clicking on the "My Info" link in the upper-right, and then clicking the "Show your tokens" at the bottom (under "Authentication tokens").

Responses

If a request succeeds, it will return a status code in the 200 range and often, an XML (or JSON if requested) response.
Creating new objects like messages or tasks will usually will usually return a "201 Created" status.
And updating records will usually return a "200 OK" status code.

If a request fails, a non-200 status code will be returned, possibly with error information

Things to note

There are a few important things to know when using the API.

  • Any items created are seen as created by the current user the API Key belongs to.
    • For example: Creating a task will set the creator-id to the ID of the current user whose API key is used to make the call
  • If you are using XML, do not forget to wrap your API Entry in <request></request>

 

Rate limiting

OK, we had to add in rate limiting to keep you guy from hammering our poor servers. So it we receive more that 120 requests per minute, we will send you to the sin bin. ie. you will receive a HTTP 400 Error code in response. The status text returned will be "You have exceeded your rate limit. Please try again in a little while."

After 15 seconds, we will leave you back in.

Comment on this page