Overview
Statuses
Time Entries
Groups
Agendas
Memberships
Users
Harvest Credentials

Questions? support@harvestapp.com

Introduction to the Co-op API

Co-op provides an API for interacting with the statuses of a Co-op workstream. This includes looking back in history day-by-day and user-by-user. Group, user, and agenda interactions are also provided to allow interacting with almost every area of Co-op.

Examples

To help you get started with the Co-op API, we have sample scripts in several languages. These scripts depict basic API actions. Visit the Co-op API Samples GitHub project to take a look at the scripts.

API Authentication

Co-op API authentication is performed via HTTP (only "Basic" is supported), and you'll need to transmit your username and password along with your request.

How to test

To interact with Co-op you'll need to send and interpret simple XML over HTTP. You must encode the preferred format inside Content-Type and Accept headers. A simple example with curl:

$curl http://coopapp.com/groups -H 'Accept: application/xml' \
  -H 'Content-Type: application/xml' -u user@email.com:password

Co-op will check your authorization on each request, actions that are invisible to you on the UI will return HTTP 404 on the API as well.

All successful requests return HTTP response codes in the 2xx range (e.g. 200, 201, etc.). Other response codes indicate a failed request, in which case an error message may be provided.

Firefox Users: Consider using the RestTest plugin to help you make requests to and see responses from the Harvest API. You need to set up your request headers with the following:

Accept: application/xml
Content-Type: application/xml
Authorization: Basic (insert your authentication string here)

You can get your authentication string by encoding, for example, with Ruby:

Base64.encode64("my@email.com:password").delete("\r\n")

Please write your application carefully, caching as much as possible. In case of abuse you may be blocked, disallowing further API access. As an act of courtesy you should also provide User-Agent strings denoting your application.

JSON API

Co-op also offers a JSON API. To interact with it, simply change your headers from application/xml to application/json.

API throttle limit - HTTP 503

We have an API throttle that blocks accounts emitting more than 100 calls per 15 seconds. We reserve the right to tune the limitations, but they are always set high enough to allow a well-behaving interactive program to do its job.

For batch processes and API developers who still need to perfect their code, this throttle may be an inadvertent blocker. Just wait and make no API calls (the throttle is reset with each call). The throttle will lift itself in few minutes and API calls may resume.

When the rate limit is exceeded Harvest will send an HTTP 503 status code. The number of seconds until the throttle is lifted is sent via the "Retry-After" HTTP header, as specified in RFC 2616.

Notational conventions

Throughout our documentation you'll find the following set of notational conventions:


Have more questions? Please email us at: support@harvestapp.com.