Intervals API Introduction

The Intervals API allows you to perform actions on various resources available within Intervals in a RESTful manner. For most resources, you can perform actions on them using all four verbs: you can retrieve information (GET), update items (PUT), create new items (POST), and delete items (DELETE).

The API root URL is located at https://api.myintervals.com/

Please note that "https" (TLS/SSL) will be required to access the API for all accounts, even if you're not on an SSL plan.

The Intervals API is available to all Intervals accounts (including free accounts). Each request must include user credentials in the Authorization HTTP header of the user on whose behalf you are making the request. Most API requests return either XML or JSON formatted data, depending on the accept type header used (either application/xml or application/json). A few resources can return image data accompanied by the image/* accept type header.

API Response

In general, if a request on a resource is successful, an HTTP status code in the 200s will be returned. For example, if a new item is created, the API will return "201 Created"; if an update takes place, "202 Accepted" will be returned; otherwise "200 OK" will be returned.

If a request fails, the error information is returned with the HTTP status code, along with a more detailed explanation of what happened in xml or json format (depending on what was requested). A list of error codes and their associated HTTP status codes can be found on the errors page.

Data Formats

Requests must meet the following conditions:

• All data should be UTF-8 encoded
• Date and timestamp values must be in ISO 8601 format (YYYY-MM-DD), and unless otherwise stated should be in the account's local time.
• All numbers (including quantities of time) should be represented with the "." character (period, stop, full stop, ASCII 46) as the decimal separator, and the digit group separator should be omitted.
• Booleans are either 't'(true) or 'f'(false)
• To set a value to null in XML, construct your field thusly: <fieldname />; for JSON, just use null

API Rate Limits

All Plans (Except Unlimited):

• 100 requests per minute per IP
• 6000 requests per day per customer account

The Unlimited Plan:

• 100 requests per minute per IP
• 12000 requests per day per customer account

These rate limits are in place to ensure everyone’s requests are handled in a timely manner and that runaway processes don’t overwhelm the API. Exceeding these numbers will trigger a temporary suspension on further API requests. If the daily limit is exceeded, it is lifted after midnight (GMT).

In the interest of staying within these rate limits, here are some tips to keep in mind when developing your application:

1. Pay close attention to the control flow of your program. Make sure that any requests made in loops have escape conditions and that infinite loops are detected and prevented.
2. Plan for and handle all possible errors returned by the server. Even if your request is perfectly formed, there is still the possibility that errors could be returned.
3. Implement and utilize efficient caching techniques, and be judicious in deciding which requests to make. Certain resources change so infrequently (clients, projects, milestones, statuses, modules, worktypes) that it may not make sense to pull information about them each time you need to refresh a task.

Please be respectful of other users and other developers when using the API. Repeated suspensions may trigger a ban on API access to your user and/or customer account. Please see our terms of service for more information.

Getting Help

If you need help with the API there are two ways to get it:

1. Fill out the Submit a Bug or Feature Request from within your Intervals account.
2. Email our API support team at api@myintervals.com