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 click your name in the top right of the app. Choose "My Profile" and click the "Edit my profile" button on the right hand side. On the API tab 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 your name in the top right, choosing My Profile and then clicking the "Edit my profile" button. On the API tab of the dialog click 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

CORS Enabled

JavaScript and the web programming has grown by leaps and bounds over the years, but the same-origin policy still remains. This prevents JavaScript from making requests across domain boundaries, and has spawned various hacks for making cross-domain requests. CORS introduces a standard mechanism that can be used by all browsers for implementing cross-domain requests and the Teamwork API fully supports CORS.

You can read more about CORS here

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>
  • Archived Projects: You can not modify the data contained in an Archived Project. You can read the data from archived projects but if you try and modify any data you will get a status of type "Error" and a message of type "Unauthorized"

 

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