Introduction to the Teamwork Projects API

Follow us on twitter for updates regarding our API. 

Sometimes we need to update the API, deprecate some features and add new API calls. Subscribe to our mailing list to get notifications on important API changes and updates to ensure your existing app doesn't break due to changes we make.

The Teamwork Projects 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're not big fans of XML 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 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"}}'

Example with ColdFusion:

<cfset theURL = "">
<cfhttp url="#theURL#" method="GET" username="#username#" password="#password#"></cfhttp>

Your API token can be found by logging into your Teamwork Projects 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"). 

EU Hosted Customers accounts should use instead of

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

HTTPS Protocols

Our API endpoints currently use the following HTTPS Protocols on

  • TLS v1 (This protocol will be depreciated on 1st September 2017)
  • TLS v1.1 (This protocol will be depreciated on 1st January 2019)
  • TLS v1.2 (This is the recommended Protocol to use)


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 150 requests per minute, we will send you to the sin bin. ie. you will receive a HTTP 429 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!

If you are syncing data and pulling paged data constantly you might find your rate limits reduced with a response header "Syncing data requires an 'updatedAfterDate' to be passed. Rate limit reduced...."

Syncing / Update After Date

Most API calls that use pagination has support for updatedAfterDate. The updatedAfterDate parameter is a string in YYYYMMDDHHMMSS format and is UTC based. Passing &updatedAfterDate=20160101050000 to an API call will only return items updated/added since 5am, January 1st 2016 UTC which makes syncing data faster and less request intensive.

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

Mailing List

Subscribe to our mailing list to get notifications on important API changes and updates.