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:

https://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 https://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" }' \
 https://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 https://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: https://api.breeze.pm/projects.json 

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

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

Multiple teams

If the user is part of multiple teams/organizations then you must add the team ID to every call. You can append it to every call with team_id or add it to the HTTP header HTTP_X_TEAM_ID. You can get all the team IDs from the user endpoint.

curl https://api.breeze.pm/projects.json?api_token=6dasdg782&team_id=5612

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,
    "workspace_id": 189,
    "created_at": "2022-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": "2022-01-11T09:13:29Z",
    "users": [
      {
        "id": 2,
        "email": "rene@breeze.pm",
        "name": "Rene"
      }
    ]
  }
]

Get project

GET /projects/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,
  "workspace_id": 189,
  "created_at": "2022-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": "$",
  "workspace_id": 189,
  "invitees": ["john@breeze.pm","jake@breeze.pm"]
}

Update a project

PUT /projects/:project_id.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": "$",
  "workspace_id": 189,
	
}

Delete a project

DELETE /projects/:project_id.json delete a specific project

Archive a project

GET /projects/:project_id/archive.json archive a specific project

Reactivate a project

GET /projects/:project_id/reactivate.json reactivate a specific project

Get people

GET /projects/:project_id/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/:project_id/people.json add people to project

Request

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

Delete person

DELETE /projects/:project_id/people/:user_id.json delete a person from project

Workspaces

Projects can belong to one workspace.

Get a workspaces

GET /workspaces get a list of all workspaces

[
 {
   "id": 1,
   "name": "Workspace name 1",	
   "position": 1,
   "created_at": "2022-12-13T10:41:28Z",
  
 },
 {
   "id": 2,
   "name": "Workspace name 2",	
   "position": 2,
   "created_at": "2022-12-12T10:41:28Z",
 }
]
		

Get a workspace

GET /workspaces/1.json get a workspace

{
  "id": 1,
  "name": "Workspace name",	
  "position": 1,
  "created_at": "2022-12-13T10:41:28Z",
   "projects": [
     {
       "id": 7,
       "name": "Project 3"
     },
     {
       "id": 8,
       "name": "Project 4"
     }
   ]
}

Create a workspace

POST /workspaces.json create a new workspace

Request

{
  "name": "Workspace name",	
}

Update a workspace

PUT /workspaces/:workspace_id.json update a specific workspace

{
  "name": "Workspace name",	
}

Delete a workspace

DELETE /workspaces/:workspace_id.json delete a specific workspace

Cards

Get cards

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

Request
{
  "archived": false
} 

Response

[
  {
    "id": 995,
    "name": "Todo list",
    "cards": [
      {
        "id": 2742,
        "name": "This is a task",
        "description": "Task description",
        "position": 1,
        "stage_id": 995,
        "swimlane_id": 2,
        "color": "",
        "duedate": null,
        "startdate": null,
        "planned_time": 0,
        "total_tracked": 2,
        "todos_count": 5,
        "done_todos": 1,
        "created_at": "2022-11-05T06:04:35Z",
        "updated_at": "2022-02-23T16:39:06Z",
	"user": 
	      {
	      "id": 5,
	      "email": "john@breeze.pm",
	      "name": "John Doe"
	      "avatar": "https://avatarurl.com/avatar.jpg"
	     },
					
        "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": "2022-02-23T16:38:54Z",
        "updated_at": "2022-02-23T16:39:05Z",
        "users": [],
        "todos": [],
        "time_entries": []
        "custom_fields": []
        
      }]
  },
  {
    "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": "2022-02-22",
        "startdate": "2022-02-20",
        "planned_time": 120,
        "total_tracked": 60,
        "todos_count": 1,
        "done_todos": 0,
        "created_at": "2022-12-13T10:52:53Z",
        "updated_at": "2022-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
          }
        ],
        "custom_fields": [
          {
            "name": "Rating",
            "value": "***"
          }
        ]
        
      }]
  }
]

Get cards V2

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

The respons is paginated 100 items per page. To get the next page append ?page=XX to the query.

Request
{
  "archived": false,
  "only_archived": false,
  "status": "status name",
  "hidden": true,
  "done": true
} 

Response

Same as V1 except it's a plain array and not grouped by stages.

Get cards in stage

GET /projects/:project_id/stages/:stage_id/cards.json get all the cards(tasks) for a specific stage

Request
{
  "archived": false,
  "only_archived": false
} 

Response

Same as "Get cards V2"

Get cards in swimlane

GET /projects/:project_id/swimlanes/:swimlane_id/cards.json get all the cards(tasks) for a specific swimlane

Request
{
  "archived": false,
  "only_archived": false
} 

Response

Same as "Get cards V2"

Get cards created by user

GET /v2/projects/:project_id/cards.json get all the cards(tasks) created by user

GET /v2/cards.json get all the cards(tasks) created by user in all projects

Request
{
  "creator_id": 2
} 

Response

Same as "Get cards V2"

Get cards assigned to user

GET /v2/projects/:project_id/cards.json get all the cards(tasks) assigned to a user

GET /v2/cards.json get all the cards(tasks) assigned to a user in all projects

Request
{
  "assigned_id": 2
} 

Response

Same as "Get cards V2"

Get card

GET /projects/:project_id/cards/:card_id.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": "2022-02-22",
  "startdate": "2022-02-20",
  "planned_time": 120,
  "total_tracked": 60,
  "todos_count": 1,
  "done_todos": 0,
  "created_at": "2022-12-13T10:52:53Z",
  "updated_at": "2022-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/:project_id/cards.json create a new card

Request

{
  "name": "new task from API",
  "description": "no description",
  "duedate": "2022-02-22",
  "startdate": "2022-02-20",
  "planned_time": 120,
  "stage_id": 9,
  "swimlane_id": 1,
  "invitees": ["john@breeze.pm","jake@breeze.pm"],
  "custom_fields": [
    {
      "name": "Rating",
      "value": "***"
    }
  ]
}

Update a card

PUT /projects/:project_id/cards/:card_id.json update a specific card

Request

{
  "name": "new task from API",
  "description": "no description",
  "duedate": "2022-02-22",
  "startdate": "2022-02-20",
  "planned_time": 120,
  "stage_id": 9,
  "new_project_id": 19,
  "custom_fields": [
    {
      "name": "Rating",
      "value": "***"
    }
  ]
}

Archive a card

GET /projects/:project_id/cards/:card_id.json archive a specific card

Request

{
  "deleted_at": "2022-05-06"  
}

Delete a card

DELETE /projects/:project_id/cards/:card_id.json delete a specific card

Move a card

POST /projects/:project_id/cards/:card_id/move.json move a card

Request

{
  "stage_id": 9,
  "prev_id": 9
}

Add people

POST /projects/:project_id/cards/:card_id/people.json assign people to card

Request

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

Remove people

DELETE /projects/:project_id/cards/:card_id/people/:user_id.json remove person from card

Lists

Get lists

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

Response

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

Create a list

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

Request
{
  "name": "todo list"
} 

Update a list

PUT /projects/:project_id/stages/:stage_id.json update specific stage for a project

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

Remove a list

DELETE /projects/:project_id/stages/:stage_id.json delete list from project

Move list

PUT /projects/:project_id/stages/:stage_id/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.

GET /projects/:project_id/cards/:card_id/time_entry.json get all the time entries for the task

Response

[
{
  "id": 31,
  "card_id": 23764,
  "desc": "description",
  "logged_date": 2022-12-21,
  "tracked": 120
  "user_id": 2,
  "created_at": "2022-12-12T10:41:28Z",
},
{
  "id": 32,
  "card_id": 23764,
  "desc": "description",
  "logged_date": 2022-12-22,
  "tracked": 120
  "user_id": 2,
  "created_at": "2022-12-13T10:41:28Z",
}
]

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

Create a time entry

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

Request
{
  "tracked": 120
  "logged_date": "2022-01-05"
  "desc": "Description here"
	
} 

Update a time entry

PUT /projects/:project_id/cards/:card_id/time_entry/:timeentry_id.json update a time entry for a card, time entry will be updated for the current user

Request
{
  "tracked": 60
  "logged_date": "2022-01-05"
  "desc": "Description here"
	
} 

Remove time entry

DELETE /projects/:project_id/cards/:card_id/time_entry/:timeentry_id.json delete time entry from specific card and user

Swimlanes

Get swimlanes

GET /projects/:project_id/swimlanes.json get all swimlanes for a project

Response
[
  {
    "id": 3,
    "name": "swimlane name",
    "project_id": 23,
    "position": 5,
    "updated_at": "2022-03-01T09:07:43Z",
    "created_at": "2022-03-01T09:07:43Z"
  },
  {
    "id": 4,
    "name": "swimlane name two",
    "project_id": 23,
    "position": 5,
    "updated_at": "2022-03-01T09:07:43Z",
    "created_at": "2022-03-01T09:07:43Z"
  }
] 

Create a swimlane

POST /projects/:project_id/swimlanes.json create a new swimlane for a project

Request
{
  "name": "swimlane name",
  "position": 2
} 

Update swimlane

PUT /projects/:project_id/swimlanes/:swimlane_id.json update specific swimlane for a project

Request
{
  "name": "swimlane namespan",
  "position": 2
} 

Remove swimlane

DELETE /projects/:project_id/swimlanes/:swimlane_id.json delete a swimlane from project

Comments

Get comments

GET /projects/:project_id/cards/:card_id/comments.json get all comments for a card

Response
[
  {
    "card_id": 4160,
    "comment": "comment text",
    "created_at": "2022-03-01T09:07:43Z",
    "id": 466,
    "updated_at": "2022-03-01T09:07:43Z",
    "user_id": 5,
    "user": 
	    {
	    "id": 5,
	    "email": "john@breeze.pm",
	    "name": "John Doe"
	    "avatar": "https://avatarurl.com/avatar.jpg"
	   }
  },
  {
    "card_id": 4160,
    "comment": "second comment text",
    "created_at": "2022-02-01T08:07:13Z",
    "id": 467,
    "updated_at": "2022-02-01T08:07:13Z",
    "user_id": 5,
    "user": 
	    {
	    "id": 5,
	    "email": "john@breeze.pm",
	    "name": "John Doe"
	    "avatar": "https://avatarurl.com/avatar.jpg"
	   }
  }
] 

Create a comment

POST /projects/:project_id/cards/:card_id/comments.json create a new comment for a card

Request
{
  "comment": "comment text"
} 

Update comment

PUT /projects/:project_id/cards/:card_id/comments/:comment_id.json update specific comments for a card

Request
{
  "comment": "comment text"
} 

Remove comment

DELETE /projects/:project_id/cards/:card_id/comments/:comment_id.json delete comment from card

Todo lists

Get todo lists

GET /projects/:project_id/cards/:card_id/todo_lists.json get all todo lists for a card

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

		
  }
] 

Create a todo list

POST /projects/:project_id/cards/:card_id/todo_lists.json create a new todo list for a card

Request
{
  "name": "todo list name"
} 

Update todo list

PUT /projects/:project_id/cards/:card_id/todo_lists/:todo_list_id.json update specific todo list for a card

Request
{
  "name": "todo list name"
} 

Remove todo

DELETE /projects/:project_id/cards/:card_id/todo_lists/:todo_list_id.json delete todo list from a card

Todos

Get todos

GET /projects/:project_id/cards/:card_id/todo_lists/:todo_list_id/todos.json get all todos for a todo list

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

Create a todo

POST /projects/:project_id/cards/:card_id/todo_lists/:todo_list_id/todos.json create a new todo for a todo list

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

Update todo

PUT /projects/:project_id/cards/:card_id/todo_lists/:todo_list_id/todos/:todo_id.json update specific todo for a todo list

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

Remove todo

DELETE /projects/:project_id/cards/:card_id/todo_lists/:todo_list_id/todos/:todo_id.json delete todo from todo list

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": "2022-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": "2022-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.

Notifications and mentions

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

Get notifications

GET /notifications.json get all unread notifications

Response
[
  {
    "id": 4160,
    "created_at": "2022-03-01T09:07:43Z",
    "project_id": 1723,
    "card_id": 324785,
    "comment_id": null,
    "marked": false,
    "description": "notifications from task description @Rene",
    "created_by": {
      "id": 5,
      "email": "john@breeze.pm",
      "name": "John Doe"
    }
  },
  {
    "id": 2040,
    "created_at": "2022-03-01T02:07:43Z",
    "project_id": 123,
    "card_id": 16485,
    "comment_id": 236622,
    "marked": false,
    "description": "notification from a comment @Rene",
    "created_by": {
      "id": 5,
      "email": "john@breeze.pm",
      "name": "John Doe"
    }
  }
] 

Mark notification

PUT /notifications/:id.json mark notification read/unread

{
  "marked": true
} 
															

Reports

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

Time tracking report

POST /reports.json generate time tracking report

To use relative time in the reports set the parameter start_date to last_month,last_week, yesterday, today, this_week, this_month .

Request
{
  "report_type": "timetracking",
  "start_date": "2015-06-01",
  "end_date": "2015-07-01",
  "projects": [1,2,3],
  "users": [9,8,7],
  "stages": ["todo","done"],
  "tags": ["bugs","features"]
	
} 
															
Response
[
  {
    "id": 4160,
    "created_at": "2022-03-01T09:07:43Z",
    "logged_date": "2022-03-01",
    "notbillable": false,
    "tracked": 120,
    "user_id": "Jake",
    "project_id": 1723,
    "card_id": 324785,
    "desc": "backend developement",
  },
  {
   "id": 1040,
   "created_at": "2022-03-01T02:07:43Z",
   "logged_date": "2022-03-01",
   "notbillable": false,
   "tracked": 60,
   "user_id": 2,
   "project_id": 123,
   "card_id": 16485,
   "desc": "testing",
  }
] 

Users

Info about yourself

GET /me.json shows info about yourself, includes also the API key

Response
{
  "id": 2,
  "name": "Robert,
  "avatar": "https://s3.amazonaws.com/x22h82gcqu/a7e2c39b721235f17cb4a0e2a90b/CORQ.jpg",
  "authentication_token": "28734uhjasdb8223",
  "created_at": "2022-03-01T09:07:43Z",
  "timezone": "UTC"
},
 "teams": 
  [
    {
      "team_id": 129,
      "owner_email": "rene@breeze.pm"
    },
    {
      "card_id": 234,
      "owner_email": "jake@breeze.pm"
    }
  ]

 

Get all users

GET /users.json lists all your team users

Response
[
  {
    "id": 2,
    "name": "Robert,
    "avatar":"https://s3.amazonaws.com/x22h82gcqu/a7e2c39b7b4a0e06cb52a90b/CORQ.jpg"
  } ,
  {
    "id": 3,
    "name": "Jake,
    "avatar":"https://s3.amazonaws.com/x22h82gcqu/a7e2c39b7212350b/avatar.jpg"
  }
]