Interstate API v2

Introducing the second version of the Interstate API. Rewritten from the ground up, it's faster, easier and even more powerful. Start developing with it now and help reshape the world of project management.

Welcome to the documentation for the v2 Interstate API. Since we launched the first version of the Interstate API last year, we have seen some great apps be built using the API. Whilst the v1 API was great, we felt it had a few too many issues. For us here at Interstate, the most notable issues were the amount of methods the API had and the fact our API codebase was too separated from the main Interstate code which meant it was harder than we would have liked to develop the API rapidly.

To combat this we decided to rewrite the entire Interstate API codebase from the ground-up for the v2 API (which has since proved to be a great decision). The new API is more efficient, less bloated and much easier to use. But why take it from us, take a look for yourself!


This is the API which you should be used to. This is the API which you'll use to do most of the work. This API lets you make individual GET requests to retrieve specific information about a user's Interstate account, POST to create roadmaps, roads, road updates, PUT to update roadmaps & roads and DELETE to remove stuff.

The major changes between the v2 REST API and the v1 REST API is that the 2nd is well… more RESTful. Unlike the previous API, we now actually respond to HTTP verbs correctly which means the amount of API methods has been drastically reduced.

This means, instead of requiring a method like /road/delete/id/:road_id you now just request /road/:road_id using the DELETE HTTP verb.

Streaming API

This is new. Behind the scenes (well not really, see the roadmap here) at Interstate we're working on a native Mac App to enhance the Interstate experience. When we were planning the app we agreed that for us to be happy with it, it has to do be as powerful as (if not more than) the real thing. What did this spell for us? Real-time notifications.

We agreed that the best experience in project management is when you're notified of your colleagues activities, without you having to do anything. But, in order for the app to receive updates in real-time we were required to build a new API endpoint that would stream events from the Interstate server to the Mac App in near real-time. After a few weeks of work we had built such a thing and quickly realised that this thing was pretty awesome and so we decided to open it up to all Interstate developers.

Discuss API

This is also new! We recently launched a new Interstate feature called Discuss and so we've built a new API so that you can interact with it directly.

The new Discuss API offers both a streaming endpoint and a regular REST endpoint; so no matter how you want to work with Discuss - we've got you covered.

The Discuss API spec is still being finalised and so the API is not yet 100% supported.

Unfortunately, the v2 is not very compatible with the v1 API. We made a conscious decision to rewrite the API from the ground-up and this included changing the API's response structure, authentication process and many other fundamental aspects of the API. We also made the decision to remove OAuth1 support and we will only support OAuth 2.0 for third party authentication. Due to the major changes between the v1 and the v2 API, we plan to keep the v1 API online for the foreseeable future to give developers more than enough time to migrate their apps over to the new API.

If you have any questions regarding migrating to the new API, feel free to post a message on our GetSatisfaction here.