The FogBugz API (version 2.0, which works with FogBugz 5.0+)

FogBugz 6 comes with a newer version of the API (version 3). See the documentation for information about version 3 of the FogBugz API.

This document describes the second version (2.0) of the FogBugz API, a simple web API that can be used to obtain lists of FogBugz cases assigned to a given user.

The API contains only basic functionality. It is intended to make it easy to create add-ins for integrated development environments, like Visual Studio or Eclipse, which show the user their FogBugz cases in a small tool window.

If you need to do something that is beyond the scope of this simple API, the only choice is to go directly to the FogBugz database. Fog Creek Software publishes detailed documentation on the schema for FogBugz databases.

However, if you can, we recommend using the API to insure that the database data remains consistent.

Future versions of FogBugz will contain an enhanced API that will allow for more functionality. We look forward to hearing your feedback on this API; please email us to let us know what improvements you would find useful.

Version Numbers

The FogBugz API has its own version numbers, which do not correspond to FogBugz version numbers.

This document describes API version 2.

FogBugz 5.0 did not ship with an API. However, API version 2, as described in this document, can be added to any FogBugz 5.0 installation. This can be done just by dropping a couple of files into the FogBugz website directory. The files you need and installation instructions are here. All later versions of FogBugz, starting with 6.0, will have some version of the API built in.

We will strive to make all future API changes backwards compatible. Usually, when new versions of the API come out, new methods will become available, and you might get more results in the XML result file, but the old results will still be there. If we need to change semantics of something, we'll usually introduce a new method with the new semantics but keep the old method around for backwards compatibility.

If we are ever forced to make a non-backwards compatible API change, the API version file will warn you about this (see next section).

An API client should always silently ignore any XML tags and attributes that it doesn't recognize, those are harmless, new, extra data that a future version of the api is passing back; if you don't need it it's not going to hurt you, so ignore it. If we ever add new tags or attributes that old clients can't ignore, clients will know about this because the minversion will go up.

About API Version 2

Version 2 of the API is extremely limited and is designed to provide the minimal support for IDE add-ins. It provides rudimentary support for listing cases and just about nothing else.

Checking the API Version and location

API clients must first hit the URL fogbugz/api.xml.

For example, if the URL is http://www.example.com/fogbugz, hit http://www.example.com/fogbugz/api.xml.

If this returns an HTTP error (file missing) you can safely assume that either FogBugz is not installed at that location, or else it is installed, but it is a version of FogBugz that does not include the API.

If the FogBugz URL includes an id (e.g. id=xxx for a FogBugz trial or hosted version of FogBugz), you can leave this out for the purpose of downloading api.xml.

api.xml simply tells you what version of the FogBugz API is supported, and gives you the URL for further calls to the API. The file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <version>2</version>
   <minversion>1</minversion>
   <url>api.asp?</url>
</response>

The url field gives you the beginning of the URL you should use for all further calls to the API. This would be api.asp? (for a typical ASP install), api.php? (for a php install), or api.asp?id=xxxx& (for a multi-homed install like the FogBugz trial server).

The minversion field is used to warn you if the current version of the API is not backwards compatible. For example, if this version is 3, and it is backwards compatible with clients written for version 2 but not backwards compatible with version 1, you'll see:

<version>3</version>
<minversion>2</minversion>

API clients must check minversion and make sure it's less than or equal to the version that was current when they were written.

Logging On

FogBugz itself supports several methods of logging on, however, the only method supported by the API is by providing an email address and password in the logon method:

   http://www.example.com/api.asp?cmd=logon&email=xxx@example.com&password=BiteMe

Three things can happen.

1) Failed logon - email or password doesn't match:

<response><error code="1">Error Message To Show User</error></response>

2) Successful logon - you get back an opaque string token which you will use for all subsequent requests:

<response><token>24dsg34lok43un23</token></response>

3) Ambiguous logon - there is more than one FogBugz user with that email address. FogBugz will supply you with a list of full names; you must provide the appropriate full name in place of an email address to log on.

<response><error code="2">Ambiguous Logon</error>
   <people><person>John Hancock</person>
   <person>Fred Astaire</person></people>
</response>

If, for example, you got that response, you would prompt the user with a combo box to choose if they are John Hancock or Fred Astaire. If they're John, you would try logging on again with this URL:

http://www.example.com/api.asp?cmd=logon&email=John%20Hancock&password=BiteMe

General rules for API requests

  1. You can use GET or POST
  2. FogBugz always uses UTF-8
  3. All API requests will have a cmd argument indicating what you want to do, like cmd=logon in the logon example.
  4. All API requests must have a token argument indicating the logon session except cmd=logon.
  5. The response is a valid XML file in UTF-8 format containing an outer <response> tag at the root.
  6. If the first child node is <error>, something went wrong.
  7. If the token is not supplied, or if the token does not correspond to a logged-in user, you'll get error code 3:
<response><error code="3">Not logged on</error></response>

Logging Off

To log off, send cmd=logoff. For example:

http://www.example.com/api.asp?cmd=logoff&token=24dsg34lok43un23

Filters

Once logged on, you can get a list of filters available to the current user.

FogBugz has three kinds of filters:

  1. Built-in filters are always present, and include "My Cases" and sometimes the main Inbox if FogBugz is used to read mail
  2. Users can save their own private filters
  3. Administrators can share filters which will be available to all users

To list filters:

cmd=listFilters

The result:

<response>
   <filters>
      <filter type="builtin" sFilter="ez349">My Cases</filter>
      <filter type="saved" sFilter="304">Cases I should have closed</filter>
      <filter type="shared" sFilter="98" status="current">Other</filter>
   </filters>
</response>

Notes:

type is "builtin", "saved", or "shared". FogBugz users will probably expect to see the three types of filters grouped as they are in FogBugz itself. The list of filters is already in the same order that users are used to seeing it in the FogBugz user interface and should be preserved.

sFilter is an opaque string that can be passed back to cmd=listCases. The meaning is internal to FogBugz.

Zero or one of the filters may have the status="current" attribute indicating that this is the users' current filter. (If none of these filters has status="current", the user is probably looking at an ad-hoc filter which hasn't been saved.)

Currently the builtin filters won't be listed as "current" even if you are currently looking at one.

To change the current filter (pass in the sFilter attribute from the listFilters cmd):

cmd=saveFilter&sFilter=402

The result is, intentionally, empty.

<response></response>

Listing Cases

Version 1 of the API only lets you list cases that correspond to the user's current filter.

To list cases:

cmd=list

The result:

<response>
<description>All open cases in SnooDog with the status of Active that must be fixed for SnooDog Beta 1: 1/1/2007</description>
<cases>
   <case ixBug="1235" operations="edit,assign,resolve,close,move">
      <category ixCategory="2">Feature</category>
      <title>Kiwi can't fly</title>
      <project ixProject="23">SnooDog</project>
      <area ixArea="10">Misc</area>
      <fixfor ixFixFor="24">SnooDog Beta 1
      <priority ixPriority="1">Life or Death</priority>
      <assigned-to ixPerson="23" sEmail="spolsky@fogcreek.com">Joel Spolsky</assigned-to>
      <status ixStatus="1">ACTIVE</status>
      <estimate>
      <original>16</original>
      <current>8</current>
      <elapsed>1.02</elapsed>
      <remain>6.98</remain>
      </estimate>
   </case>
...
</cases>
</response>

If you want, you can change the filter to one of the saved filters with another API call, by using one of the sFilter values that you got back from cmd=listFilters. This will change the user's filter in the web interface, too:

cmd=saveFilter&sFilter=ez349

In the case tag, possible operations are edit, spam, assign, resolve, move, reactivate, close, reopen, and remind. This is the list of operations that are currently possible for the given bug. If the API client allows the user to multiply-select cases, it should only allow operations that are possible for all the selected bugs.