Breeze API

The Breeze API is a REST style API that enables your application or script to access Breeze resources. It is designed to have predictable resource URLs and to use HTTP response codes for errors. JSON is used for all requests and responses from the API.

Accessing the API

Accessing the API uses the following URL schema:

http://api.breeze.pm/<resource>

Where resource is the resource you want to access (e.g. projects, cards, todos etc)

For example, getting a list of projects would result in the URL:

curl -u user:pass http://api.breeze.pm/projects.json 

To create or update something you also have to include the Content-Type header and the JSON data.

curl -u user:pass \
 -H 'Content-Type: application/json' \
 -d '{ "name": "New project" }' \
 http://api.breeze.pm/projects.json 

Authentication

Breeze API supports HTTP Basic auth and token based authentication.

Basic auth

To get you started with Breeze API you can just use HTTP Basic authentication with your login info.

curl -u username:password http://api.breeze.pm/projects.json 

API token

You can also authenticate by providing your API token in the request. The token has to be sent for each request your application makes to the Breeze API. Remember that anyone who has your api token can see and change everything you have access to. Keep it safe ! You can manage your API token from your profile.

curl -u 6dasdg782: http://api.breeze.pm/projects.json 

You can also pass the api token as a query parameter in the url.

curl http://api.breeze.pm/projects.json?api_token=6dasdg782

Help us improve it

We plan to extend and adapt the API to allow access to more resources in the future. If you have special needs for an API, let us know. Write to support@breeze.pm.

Projects

Get projects

GET /projects.json get all active projects

Response

[
  {
    "id": 1,
    "name": "Testing Breeze",
    "description": "testing api",
    "budget_amount": "13322.0",
    "budget_hours": 111,
    "hourly_rate": 12,
    "currency_symbol": "$",
    "total_planned": 480,
    "total_tracked": 182,
    "star": false,
    "created_at": "2012-12-13T10:41:28Z",
    "users": [
      {
        "id": 5,
        "email": "john@breeze.pm",
        "name": "John Doe"
      },
      {
        "id": 6,
        "email": "jake@breeze.pm",
        "name": null
      }
    ]
    },
    {
    "id": 2,
    "name": "Personal tasks",
    "description": "",
    "budget_amount": "0.0",
    "budget_hours": null,
    "hourly_rate": 0,
    "currency_symbol": "$",
    "total_planned": 0,
    "total_tracked": 0,
    "star": false,
    "created_at": "2013-01-11T09:13:29Z",
    "users": [
      {
        "id": 2,
        "email": "rene@breeze.pm",
        "name": "Rene"
      }
    ]
  }
]

Get project

GET /project/1.json get specific project

Response

{
  "id": 1,
  "name": "Testing Breeze",
  "description": "testing api",
  "budget_amount": "13322.0",
  "budget_hours": 111,
  "hourly_rate": 12,
  "currency_symbol": "$",
  "total_planned": 480,
  "total_tracked": 182,
  "star": false,
  "created_at": "2012-12-13T10:41:28Z",
  "users": [
    {
      "id": 5,
      "email": "john@breeze.pm",
      "name": "John Doe"
    },
    {
      "id": 6,
      "email": "jake@breeze.pm",
      "name": null
    }
  ]
}

Create a project

POST /projects.json create a new project

Request

{
  "name": "New project",
  "description": "nww project from api",
  "budget_amount": "10000.0",
  "budget_hours": 100,
  "hourly_rate": 59,
  "currency_symbol": "$",
  "invitees": ["john@breeze.pm","jake@breeze.pm"]
}

Update a project

PUT /projects/1.json update a specific project

Request

{
  "name": "New project",
  "description": "nww project from api",
  "budget_amount": "10000.0",
  "budget_hours": 100,
  "hourly_rate": 59,
  "currency_symbol": "$",
}

Delete a project

DELETE /projects/1.json delete a specific project

Archive a project

GET /projects/1/archive.json archive a specific project

Reactivate a project

GET /projects/1/reactivate.json reactivate a specific project

Get people

GET /projects/1/people.json get all the project users

Response

[
  {
    "id": 5,
    "email": "john@breeze.pm",
    "name": "John Doe"
  },
  {
    "id": 6,
    "email": "jake@breeze.pm",
    "name": null
  }
]

Add people

POST /projects/people.json add people to project

Request

{
  "invitees": ["john@breeze.pm","jake@breeze.pm"]
}

Delete person

DELETE /projects/1/people/5.json delete a person from project

Cards

Get cards

GET /projects/1/cards.json get all the cards(tasks) for a specific project

Response

[
  {
    "id": 995,
    "name": "Todo list",
    "cards": [
      {
        "id": 2742,
        "name": "This is a task",
        "description": "Task description",
        "position": 1,
        "stage_id": 995,
        "color": "",
        "duedate": null,
        "startdate": null,
        "planned_time": 0,
        "total_tracked": 2,
        "todos_count": 5,
        "done_todos": 1,
        "created_at": "2012-11-05T06:04:35Z",
        "updated_at": "2013-02-23T16:39:06Z",
        "users": [
          {
            "id": 5,
            "email": "john@breeze.pm",
            "name": "John Doe"
          },
          {
            "id": 6,
            "email": "jake@breeze.pm",
            "name": null
          }
        ],
        "todos": [
          {
            "id": 372,
            "name": "first todo",
            "done": false
          },
          {
            "id": 6,
            "name": "second todo",
            "done": false
          }
        ] ,
        "time_entries": [
          {
            "user_id": 5,
            "user_email": "rene@breeze.pm",
            "user_name": Rene,
            "tracked": 120
          }
        ]              
      },
      {
        "id": 4105,
        "name": "Update API",
        "description": null,
        "position": 2,
        "stage_id": 995,
        "color": null,
        "duedate": null,
        "startdate": null,
        "planned_time": 0,
        "total_tracked": 0,
        "todos_count": 0,
        "done_todos": 0,
        "created_at": "2013-02-23T16:38:54Z",
        "updated_at": "2013-02-23T16:39:05Z",
        "users": [],
        "todos": [],
        "time_entries": []
        
      }]
  },
  {
    "id": 993,
    "name": "Done list",
    "cards": [
      {
        "id": 3532,
        "name": "Try out our API",
        "description": "API is still beta",
        "position": 1,
        "stage_id": 993,
        "color": "",
        "duedate": "2013-02-22",
        "startdate": "2013-02-20",
        "planned_time": 120,
        "total_tracked": 60,
        "todos_count": 1,
        "done_todos": 0,
        "created_at": "2012-12-13T10:52:53Z",
        "updated_at": "2013-02-25T10:12:23Z",
        "users": [
          {
            "id": 5,
            "email": "john@breeze.pm",
            "name": "John Doe"
          }
        ],
        "todos": [],
        "time_entries": [
          {
            "user_id": 5,
            "user_email": "rene@breeze.pm",
            "user_name": Rene,
            "tracked": 120
          }
        ]  
      }]
  }
]

Get card

GET /projects/1/cards/3532.json get a specific card(task)

Response

{
  "id": 3532,
  "name": "Try out our API",
  "description": "API is still beta",
  "position": 1,
  "stage_id": 993,
  "color": "",
  "duedate": "2013-02-22",
  "startdate": "2013-02-20",
  "planned_time": 120,
  "total_tracked": 60,
  "todos_count": 1,
  "done_todos": 0,
  "created_at": "2012-12-13T10:52:53Z",
  "updated_at": "2013-02-25T10:12:23Z",
  "users": [
    {
      "id": 5,
      "email": "john@breeze.pm",
      "name": "John Doe"
    },
    {
      "id": 6,
      "email": "jake@breeze.pm",
      "name": null
    }
  ],
  "todos": [
    {
      "id": 372,
      "name": "first todo",
      "done": false
    },
    {
      "id": 6,
      "name": "second todo",
      "done": false
    }
  ] ,
  "time_entries": [
    {
      "user_id": 5,
      "user_email": "rene@breeze.pm",
      "user_name": Rene,
      "tracked": 120
    }
  ]  
}

Create a card

POST /projects/1/cards.json create a new card

Request

{
  "name": "new task from API",
  "description": "no description",
  "duedate": "2013-02-22",
  "startdate": "2013-02-20",
  "planned_time": 120,
  "stage_id": 9,
  "invitees": ["john@breeze.pm","jake@breeze.pm"]
  
}

Update a card

PUT /projects/1/cards/4.json update a specific card

Request

{
  "name": "new task from API",
  "description": "no description",
  "duedate": "2013-02-22",
  "startdate": "2013-02-20",
  "planned_time": 120
  "stage_id": 9
  
}

Delete a card

DELETE /projects/1/cards/4.json delete a specific card

Add people

POST /projects/1/cards/4/people.json assign people to card

Request

{
  "invitees": ["john@breeze.pm","jake@breeze.pm"]
}

Remove people

DELETE /projects/1/cards/4/people/273.json remove person from card

Lists

Get lists

GET /projects/1/stages.json get all lists in the project

Response

[
  {
    "id": 31,
    "name": "Todo",
    "position": "1",
    "created_at": "2012-12-12T10:41:28Z",
  },
  {
    "id": 42,
    "name": "Doing",
    "position": "2",
    "created_at": "2012-12-13T10:41:28Z",
  }
]

Create a list

POST /projects/1/stages.json create a new list for the project

Request
{
  "name": "todo list"
} 

Update a list

PUT /projects/1/stages/1287.json update specific stage for a project

Request
{
  "name": "new name text"
} 

Remove a list

DELETE /projects/1/stages/1287.json delete list from project

Move ist

PUT /projects/1/stages/1287/move.json move list after previous list

Request
{
  "prev_id": 1285
} 

Time entries

Get time entries

Time entries are included in the card get responses, see Cards documentation.

Create a time entry

POST /projects/1/cards/4160/time_entry.json create a new time entry for a card, time entry will be added to the current user

Request
{
  "tracked": 120
} 

Update a time entry

POST /projects/1/cards/4160/time_entry.json update a time entry for a card, time entry will be updated for the current user

Request
{
  "tracked": 60
} 

Remove time entry

DELETE /projects/1/cards/4160/time_entry.json delete time entry from specific card and user

Comments

Get comments

GET /projects/1/cards/4160/comments.json get all comments for a card

Response
[
  {
    "card_id": 4160,
    "comment": "comment text",
    "created_at": "2013-03-01T09:07:43Z",
    "id": 466,
    "updated_at": "2013-03-01T09:07:43Z",
    "user_id": 5
  },
  {
    "card_id": 4160,
    "comment": "second comment text",
    "created_at": "2013-02-01T08:07:13Z",
    "id": 467,
    "updated_at": "2013-02-01T08:07:13Z",
    "user_id": 5
  }
] 

Create a comment

POST /projects/1/cards/4160/comments.json create a new comment for a card

Request
{
  "comment": "comment text"
} 

Update comment

PUT /projects/1/cards/4160/comments/466.json update specific comments for a card

Request
{
  "comment": "comment text"
} 

Remove comment

DELETE /projects/1/cards/4160/comments/466.json delete comment from card

Todos

Get todos

GET /projects/1/cards/4160/todos.json get all todos for a card

Response
[
  {
    "card_id": 4160,
    "name": "Todo 1",
    "done": false,
    "created_at": "2013-03-01T09:07:43Z",
    "id": 369,
    "updated_at": "2013-03-01T09:07:43Z",
  },
  {
    "card_id": 4160,
    "done": true,
    "name": "Todo 2",
    "created_at": "2013-02-01T08:07:13Z",
    "id": 370,
    "updated_at": "2013-02-01T08:07:13Z",
  }
] 

Create a todo

POST /projects/1/cards/4160/todos.json create a new todo for a card

Request
{
  "name": "todo item text",
  "done": false
} 

Update todo

PUT /projects/1/cards/4160/todos/369.json update specific todo for a card

Request
{
  "name": "todo item text",
  "done": true
} 

Remove todo

DELETE /projects/1/cards/4160/toos/369.json delete todo from card

Time entries

Get time entries

Time entries are included in the card get responses, see Cards documentation.

Create a time entry

POST /projects/1/cards/4160/time_entry.json create a new time entry for a card, time entry will be added to the current user

Request
{
  "tracked": 120
} 

Update a time entry

POST /projects/1/cards/4160/time_entry.json update a time entry for a card, time entry will be updated for the current user

Request
{
  "tracked": 60
} 

Remove time entry

DELETE /projects/1/cards/4160/time_entry.json delete time entry from specific card and user

Activity and audit log

All activity responses are paginated 50 items per page. To get the next page append ?page=XX to the query.

Get activity from all projects

GET /activities.json get all activity entries

Response
[
  {
    "id": 4160,
    "created_at": "2013-03-01T09:07:43Z",
    "user": "Jake",
    "project_id": 1723,
    "card_id": 324785,
    "message": "logged <b>9h</b> of work for <a href="https://app.breeze.pm/projects/4186-name-the-project/cards/71399-asd-asd">Task name</a>",
  },
  {
   "id": 1040,
   "created_at": "2013-03-01T02:07:43Z",
   "user": "John",
   "project_id": 123,
   "card_id": 16485,
   "message": "<b>tagged</b> <a href="https://app.breeze.pm/projects/4186-aaaaaname-the-project/cards/70327-asdasd">Task name</a> with <b> bugs</b>",
  }
] 

Get activity from all projects by a user

GET /activities/:user_id.json get activity entries

Response is same as for all activities query.

Get activity from a project

GET /projects/:project_id/activities.json get all activity entries

Response is same as for all activities query.

Get activity from a projects by a user

GET /projects/:project_id/activities/:user_id.json get activity entries

Response is same as for all activities query.