Introduction to the TeamworkPM API

The TeamworkPM API can respond 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.json will return the data and a DELETE verb call to /message/85872.json 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 avatar in the top right of the app. Choose "Edit my details" and 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. Detailed instructions...
  2. Now, open any web browser and browse to https://[your_site]/projects.json
  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 JSON format.

Important Note: The API Key is unique to each user. The API will function with the same permissions and create items credited to the user who is authenticated with each API key.


Try switching the format

We support both JSON and XML. To be honest, we hate XML, It's overweight and ugly like a bad date so by default all code samples are in JSON format. To switch to XML format, simply change the .json to .xml. So if you pefer XML for some strange reason browse to http://[your_site]/projects.xml instead.

For consistency, we use the JSON samples throughout this documentation but please feel free to use the bloated and verbose XML version if you want.


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/json' -H 'Content-Type: application/json' \
-u APIKEY0123456789:xxx -d '{"request": {"name": "some value"}}' https://yours.teamwork.com

Example with ColdFusion:

<cfset theURL = "https://yoursite.teamwork.com/projects.json">
<cfhttp url="#theURL#" method="GET" username="#username#" password="#password#"></cfhttp>

Your API token can be found by logging into your TeamworkPM account, clicking your avatar in the top right and choosing Edit my details. On the API tab of the dialog click the "Show your token" at the bottom (under "API 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 security@teamwork.com


Responses

If a request succeeds, it will return a status code in the 200 range and often a JSON (or XML 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 and performing a PUT/POST request, 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 guys from hammering our poor servers. So if 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'll let you back in!


Getting Help

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 api@teamwork.com


Comment on this page