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?
- 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...
- Now, open any web browser and browse to https://[your_site]/projects.xml
- 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, we 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 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>' https://yours.teamwork.com
Example with ColdFusion:
<cfset theURL = "https://yoursite.teamwork.com/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").
We advise making all calls to your Teamwork account over SSL. If you have any security concerns or questions just drop us an email to email@example.com
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 and performing a PUT/POST, 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"
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.
We're here to help! If you have any questions on the API or have built something cool and would like us to help publicize it, just drop us an email to firstname.lastname@example.org