API Documentation

List users

Get a list of users in your plan. This is you plus any invited users in projects you created.

GET /api_v1/users.xml

List projects

Get a list of all active and inactive projects you are a member of.

GET /api_v1/projects.xml

Show project

Show details for a specific project. Note: if you'd like to see the tasks in the project, refer to section 'List tasks'.

GET /api_v1/projects/#{id}.xml

Create project

Create a new project. Note: this is subject to plan limits.

POST /api_v1/projects.xml

Example request data:

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <name>My Website</name>
  <devurl>http://www.example.com</devurl>
</project>

Update project

Update settings for an existing project under your control (ie: only the ones you own).

When you set the status to inactive, the project will no longer count towards your plan limit (the sidebar will be disabled, but data is kept).

PUT /api_v1/projects/#{id}.xml

Example request data:

<project>
  <name>Example project</name>
  <devurl>http://www.example.com/</devurl>
  <is-active type="boolean">true</is-active>
</project>

Delete project

Permanently delete a project and all associated data. Use with care...!

DELETE /api_v1/projects/#{id}.xml

List tasks

Get a full list of tasks for a project, including archived tasks.

GET /api_v1/projects/#{project_id}/tasks.xml

Show task

List details of a task in a given project, includes a list of comments.

GET /api_v1/projects/#{project_id}/tasks/#{id}.xml

Example output:

<task>
  <id type="integer">123</id>
  <local-task-id type="integer">1</local-task-id>
  <description>Example task</description>
  <status-id type="integer">0</status-id>
  <priority-id type="integer">1</priority-id>
  <assigned-to-id type="integer">100</assigned-to-id>
  <url>/</url>
</task>

Create task

Add a new task in a project. Note that a new task always initially gets a status-id of 0 (backlog).

POST /api_v1/projects/#{project_id}/tasks.xml

Example request data:

<task>
  <description>Example task</description>
  <priority-id type="integer">1</priority-id>
</task>

Update task

Update one of the tasks in a project.

PUT /api_v1/projects/#{project_id}/tasks/#{id}.xml

Request data:

<task>
  <description>Example task</description>
  <status-id type="integer">0</status-id>
  <priority-id type="integer">1</priority-id>
</task>

List comments

Get a full list of comments for a task in chronological order.

Show comment

List details of a comment.

GET /api_v1/projects/#{project_id}/tasks/#{task_id}/comments/#{id}.xml

Create comment

Adds a new comment to the specified task.

Request data:

<comment>
  <text>Example comment</text>
</comment>

Ruby examples

To use the BugHerd API through ActiveResource, declare the classes below:

class BugHerd::User < ActiveResource::Base
  self.site = 'http://www.bugherd.com/api_v1'
end

class BugHerd::Project < ActiveResource::Base
  self.site = 'http://www.bugherd.com/api_v1'
end

class BugHerd::Task < ActiveResource::Base
  self.site = 'http://www.bugherd.com/api_v1/projects/:project_id'
end

class BugHerd::Comment < ActiveResource::Base
  self.site = 'http://www.bugherd.com/api_v1/projects/:project_id/tasks/:task_id'
end

# set user and password prior to making a call, eg:
BugHerd::Project.user = 'email'
BugHerd::Project.password = 'password'

Here are some examples of what you can do through the ActiveResource models:

# get a list of users in your plan
BugHerd::User.all

# get a list of projects you collaborate in
BugHerd::Project.all

# create a new project (note you must have remaining projects in your plan!)
BugHerd::Project.create(:name => 'My Website', :devurl => 'http://www.example.com')

# update a project
@project = BugHerd::Project.find(1)
@project.name = 'A New Name'
@project.save

# disable a project
@project = BugHerd::Project.find(1)
@project.is_active = false
@project.save

# get all tasks for a project
BugHerd::Task.all(:params => {:project_id => 1})

# quick create a new task
BugHerd::Task.create(:description => 'Performance of the site is slow', :project_id => 1)

# create a task specifying all parameters
BugHerd::Task.create(
  :description => 'Update the site color scheme, not 1970 anymore',
  :assigned_to_id => 3,
  :status_id => 1,
  :priority_id => 4,
  :project_id => 1,
)

# update the priority of a task to critical
@task = BugHerd::Task.find(123, :params => {:project_id => 1})
@task.priority_id = 1
@task.save

# close a task
@task = BugHerd::Task.find(123, :params => {:project_id => 1})
@task.status_id = 5
@task.save

# list all comments for a task
BugHerd::Comment.all(:params => {:task_id => 123, :project_id => 1})

# add a comment to a task
BugHerd::Comment.create(
  :text => 'This issue seems to reoccur frequently',
  :task_id => 123,
  :project_id => 1,
)

Community libraries

bugherd-api ruby gem by cored.

BugHerder C# API wrapper library by @djbyter.

BugHerd API PHP Library by Jonathan Bernardi.

Other languages?

If you have integrated with BugHerd using your favorite language (PHP, Python, etc) we and other fellow web folks would be super impressed if you shared some sample code with us so we can publish it here!