The new APIv2 is available. Read the docs preview here.

The Redbooth API will allow you to connect your applications to Redbooth.

Some possibilities of what you will be able to do are:

  • Create desktop and mobile clients to access Redbooth.
  • Link your own GTD application with Redbooth tasks.
  • Post messages from other applications, like your own CRM.
  • Program custom behaviours on Redbooth.
  • Develop browser extensions.

We're here to help you understand how the Redbooth API is structured and how you can consume it.

First, you'll need to understand some basic concepts. After, we'll run some basic examples and learn how to handle authorization. Lastly, we'll jump to the documentation for models: Projects, users, tasks, etc.

What you should know already

This documentation assumes you are familiar with HTTP and its usual verbs: GET, POST, PUT, DELETE.

Redbooth uses a RESTful JSON API. Routes will be specified in this document, and the API will return the standard HTTP status codes.

For authentication, we support OAuth2 and HTTP Basic Authentication. We recommend you use OAuth2 if you are integrating Redbooth with third party services or clients. All Redbooth traffic uses HTTPS.

Your first request

Try this simple request from your command line to see how the API works:

curl https://teambox.com/api/1/projects -u username:password

It should return something like this:

{
  "id": 23216,
  "organization_id": 14076,
  "name": "Teambox Api Example Project",
  "permalink": "teambox-api-example-project",
  "archived": false,
  "created_at": "2010-07-30 20:16:55 +0000",
  "updated_at": "2010-08-28 14:20:35 +0000",
  "owner_user_id": 111245,
  "type": "Project",
  "references": [
    {
      "id": 14076,
      "name": "Projects from API Man",
      "permalink": "user-example_api_user",
      "language": "en",
      "time_zone": "Eastern Time (US & Canada)",
      "domain": null,
      "description": null,
      "logo_url": "/images/logos/original/missing.png",
      "created_at": "2010-08-28 14:20:34 +0000",
      "updated_at": "2013-11-11 14:41:34",
      "type": "Organization"
    },
    {
      "id": 111245,
      "first_name": "API",
      "last_name": "Man",
      "locale": "en",
      "username": "example_api_user",
      "time_zone": "Eastern Time (US & Canada)",
      "utc_offset": -14400,
      "created_at": "2010-07-30 20:16:55 +0000",
      "updated_at": "2014-04-20 10:08:35 +0000",
      "micro_avatar_url": "http://www.gravatar.com/avatar/db32dac52f3a034fa28a149f20bae5b4?size=24&default=mm",
      "avatar_url": "http://www.gravatar.com/avatar/db32dac52f3a034fa28a149f20bae5b4?size=48&default=mm",
      "first_day_of_week": "sunday",
      "type": "User"
    }
  ]
}

This is the way we will be handling API requests and data exchange with Redbooth.

With this simple command, you can get recent activities from Redbooth:

curl https://teambox.com/api/1/activities -u username:password

Try this code snippet from your terminal to post a comment to your projects:

curl -X POST -H 'Accept: application/json' -H 'Content-Type: application/json' -u username:password -d '{body: "Posting using the API!"}' https://teambox.com/api/1/projects/your_project/comments

Useful tools

There is a rather nice gem for ruby developers, redbooth-client.

If you have written a client for your favourite programming language, please let us know!