FogBugz API Version 4

This document describes API version 4 which ships with FogBugz 6.0. The FogBugz API is implemented as an ASP page that accepts GET or POST params and returns XML after a user has been authenticated. As of FogBugz 6, the API is included with FogBugz and does not need to be installed separately. Sample code that uses the API is included in your FogBugz\Accessories\API folder.

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.

The private tag can almost always be ignored by non-Fog Creek api clients. It is used by the FogBugz server to indicate to a client that a new version of some API client software is available on the FogBugz server. For example, the following tag might be interpreted by the FogBugz for Visual Studio Add-in to mean that version 3 is now available on the server where it can be downloaded from the URL setup-msvs.exe.

<private id="FogBugz for Visual Studio" version="3" url="setup-msvs.exe" />

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=BigMac

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 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=BigMac

General rules for API requests

1. You can use GET or POST.  If you are submitting files however, you must use a enctype="multipart/form-data" POST.
2. FogBugz is going to be religiously 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. The token can be used indefinitely, and will only be invalidated by executing a logoff command with that token.
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 months ago</filter>
    <filter type="shared" sFilter="98" status="current">Customer Service Top 10</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=saveFilter. 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 purposefully empty.

<response></response>

Listing Cases

cmd=search

Arguments:

q - the query term you are searching for.  Can be a string, a case number, a comma separated list of case numbers without spaces, e.g. 12,25,556 .  Note, to search for the number 123 and not the case 123, enclose your search in quotes.  This search acts exactly the same way the search box in FogBugz operates, so you can use that to debug.

If q is not present, returns the cases in your current filter.  If the current filter matches a saved or built-in filter, the sFilter is also returned.

cols - a comma separated list of columns you would like returned.  Available columns are listed here in the case xml output.  Additional columns: if you include events, you will also receive all the events for that case.  Include latestEvent to just get the latest event.

ix columns can be empty or 0 if they are not set.  All valid ix columns (ixPersonClosedBy for example) will be > 0 if they're is a valid person who closed this case.

max - the max number of bugs you want returned.  Leave off if you want them all.

Editing Cases

Each of the following commands accept "ixPersonEditedBy" and "dt" parameters from admins to enable accurate imports with the API.

cmd=new and cmd=edit and cmd=assign and cmd=reactivate and cmd=reopen

Arguments:

• ixBug (omitted for cmd=new)
• ixBugEvent (omitted for cmd=new - optional - if supplied, and this is not equal to the latest bug event for the case, you will receive error code 9 back to show that you were working with a "stale" view of the case).
• sTitle
• ixProject (or sProject)
• ixArea (or sArea)
• ixFixFor (or sFixFor - searches project first, then global fixfors)
• ixCategory (or sCategory)
• ixPersonAssignedTo (or sPersonAssignedTo)
• ixPriority (or sPriority)
• dtDue
• hrsCurrEst
• sVersion
• sComputer
• sCustomerEmail - only the API lets you set this
• ixMailbox - if you set sCustomerEmail, you'll want to set this too... otherwise you won't be able to reply to this case
• sScoutDescription - (used only for cmd=new) if you set this, and FogBugz finds a case with this sScoutDescription, it will append to that case unless fScoutStopReporting is true for that case, and then it will do nothing.
  
• sScoutMessage - the message you are supposed to display to users for this case
  
• fScoutStopReporting - set this to 1 if you don't want FogBugz to record any more of these types of cases
  
• sEvent - text description of the bugevent
• cols - the columns you want returned about this case
  

If any fields are omitted, they will not be changed.

You can also upload an unlimited number of files (constrained only by the max upload limit on the web server).

File1, File2, File3, etc.
To upload files, use the enctype="multipart/form-data" form type and you will need an additional argument nFileCount which contains the number of files (otherwise only the first one will upload).

For example, an html page which submits to the api to create a new case would look like this:

<html>
<form method="post" action="http://localhost/fb/api.asp" enctype="multipart/form-data" >
<input type=hidden name=cmd value=new />
<input type=hidden name=token value="CCECOGMBRTPJLFUVFUAAGZCEIEYAC2" />
<input type=file name=File1 />
<input type="submit">
</form>
</html>

You can read more about this encoding type in the RFC.

cmd=resolve

Same as cmd=edit, with the addition of the ixStatus field.  Note: the UI does not let you change the project, area, assigned to, and category on resolve.  The API does.

cmd=close

Same as cmd=edit.  Note: the UI does not let you change any fields on close.  The API does.  However, ixPersonAssignedTo will always be set to 2 (the CLOSED user).

cmd=email and cmd=reply and cmd=forward

Additional arguments: sSubject, sFrom, sTo, sCC, sBCC, ixBugEventAttachment (this is the ixBugEvent if you want to include any attachments from a previous email, for example when you want to do a "forward")

Note: You can supply any address for the sFrom field, although the UI restricts you to email addresses that FogBugz is actively checking (so that when a user replies to your email, it will actually go back into FogBugz).  The sFrom field you supply here should be one of the values returned from the cmd=listMailboxes command.

Same as cmd=edit.

Lists

cmd=listProjects  - list all undeleted projects (Arguments: fWrite=1 -- optional, do you want a list of projects you can write to? If this is left off, then the API assumes you are looking for projects that you can at least read. ixProject -- optional, if included will always list at least this project even if it is deleted)
cmd=listAreas - list all undeleted areas (Arguments: fWrite=1 -- optional, do you want a list of areas you can write to? If this is left off, then the API assumes you are looking for areas that you can at least read. ixProject -- list areas from this project, ixArea -- optional, if included will always list at least this area even if it is deleted)
cmd=listCategories - list all categories
cmd=listPriorities - list all priorities
cmd=listPeople - list people in the corresponding categories (Arguments: fIncludeNormal=1, fIncludeCommunity=1, fIncludeVirtual=1 -- if you don't supply any arguments, the API assumes you mean fIncludeNormal=1)
cmd=listStatuses - list status for a particular category (Arguments: ixCategory - optional, will list all if left off, fResolved=1 -- if fResolved = 1 then only resolved statuses are listed)
cmd=listFixFors - list fix fors ( Arguments: ixProject - only list fix fors for this project, if omitted will list all fix fors, ixFixFor - if listing all fix fors will include this fixfor even if it's unassignable (i.e. deleted), fIncludeDeleted=1 - include deleted fix fors (i.e. those that are marked unassignable)
cmd=listMailboxes - get a list of mailboxes that you have access to -- note the sTemplate field here will have placeholders you will need to replace ( such as {case} {subject} {ticketurl} etc).  See the Mailboxes edit screen in FogBugz for more info.

Creating

cmd=newProject

Arguments: sProject (sProject is the title of the new project), ixPersonPrimaryContact, fAllowPublicSubmit, ixGroup, fInbox

Returns: ixProject of the new project

cmd=newArea

Arguments: ixProject, sArea (sArea is the title of the new area), ixPersonPrimaryContact (if ixPersonPrimaryContact is -1, use project's primary)

Returns: ixArea of the new area

cmd=newPerson

Arguments: sEmail, sFullname, nType, fActive, ... (importBugzilla just needs sEmail, fActive=false)
(nType is 0 for a normal user, 1 for an administrator, 2 for a community user, and 3 for a virtual user)

Returns: ixPerson of the new person

cmd=newFixFor

Arguments: ixProject (set ixProject to -1 to create a global fixfor), sFixFor (sFixFor is the title of the new fixfor), dtRelease, fAssignable

Returns: ixFixFor of the new fixfor

Views

cmd=viewProject - display info about a particular project

Arguments: ixProject OR sProject

cmd=viewArea - display info about a particular area

Arguments: ixArea OR (sArea,ixProject)

cmd=viewPerson - display info about a particular person

Arguments: ixPerson OR sEmail (Optional: if this is left off the user currently logged in is returned)

cmd=viewFixFor - display info about a particular fixfor

Arguments: ixFixFor OR (sFixFor,ixProject) )

cmd=viewCategory - display info about a particular category

Arguments: ixCategory

cmd=viewPriority - display info about a particular priority

Arguments: ixPriority

cmd=viewStatus - display info about a particular status

Arguments: ixStatus

cmd=viewMailbox - display info about a particular mailbox

Arguments: ixMailbox

Working Schedule

cmd=listWorkingSchedule - list working schedule for a particular person

Arguments: ixPerson - If ixPerson is omitted, list the working schedule for the logged on user.

Returns <workingschedule> (see sample xml)

cmd=wsDateFromHours - Allows you to add hrs (in working hours time) to dt respecting the working hours.  For example, if you work 9-5 Monday to Friday, and it's Friday at 4pm and you want to know what date to set a case to that should be due in 8 working hours, it would return the next Monday at 3pm.  If it was Monday at 3pm and you wanted to know what the date would be for something due in 5 hours, it would give you back the next day, Tuesday at 12 noon.

Arguments

• ixPerson - If omitted, use the working schedule for the logged on user.
• hrs - the number of hours you want to add to the date
• dt - the UTC date you want to start at.

Returns <dt>2007-05-07T16:30:00Z</dt>  -- a UTC date

Time Tracking

cmd=startWork - start working on this case and charge time to it (start the stopwatch)

Arguments:  ixBug - the case you want to start working on

cmd=stopWork - stop working on everything (stop the stopwatch)

No arguments

cmd=newInterval - import a time interval that already happened

Arguments: ixBug, dtStart, dtEnd

cmd=listIntervals - returns all intervals that start between dtStart and dtEnd

Arguments: dtStart, dtEnd (if omitted, will list all intervals)

Source Control

cmd=newCheckin

Arguments: ixBug, sFile, sPrev, sNew, sRepo

cmd=listCheckins

Arguments: ixBug

Release Notes

You can reproduce the current behavior of getting release notes for a particular release using the following syntax:

cmd=search&q=fixfor:undecided&cols=ixBug,sCategory,sTitle,sReleaseNotes

Wikis

cmd=newWiki

Arguments: s, sTagLineHTML (s is the title of the new wiki)

cmd=editWiki

Arguments: ixWiki, s (optional), sTagLineHTML (optional), ixDictionary (optional), ixTemplate (optional)

cmd=deleteWiki

Arguments: ixWiki

cmd=newArticle

Arguments: ixWiki, sHeadline, sBody

cmd=editArticle

Arguments: ixWikiPage, sHeadline, sBody, sComment

cmd=listWikis

Arguments: (none)

cmd=listArticles

Arguments: ixWiki

cmd=listRevisions

Arguments: ixWikiPage

cmd=viewArticle

Arguments: ixWikiPage, nRevision (optional)

cmd=listTemplates

Arguments: (none)

cmd=listTemplateRevisions

Arguments: ixTemplate

cmd=viewTemplate

Arguments: ixTemplate, nRevision (optional)

cmd=deleteTemplate

Arguments: ixTemplate

cmd=newTemplate

Arguments: sTemplate, sBodyHTML, sBodyCSS, sComment

cmd=editTemplate

Arguments: ixTemplate, sTemplate (optional), sBodyHTML (optional), sBodyCSS (optional), sComment (optional)

cmd=wikiFileUpload

Arguments: ixWiki, File1 (multipart/form-data)

Discussion Groups

cmd=listDiscussGroups - list all readable discussion groups

cmd=listDiscussion Arguments: ixDiscussGroup, fFull (if you want every post fFull=1, just main topics fFull=2), m (month, omit for curent), y (year, omit for current)... i.e. ixDiscussGroup=1&fFull=1&m=2&y=2007 - all posts in discussion group 1 for February 2007.

cmd=listDiscussTopic Arguments: ixDiscussTopic

BugzScout

BugzScout cases can be handled directly by the API now.

cmd=listScoutCase Arguments: sScoutDescription - empty if no case is found -- limited to 255 chars.  See "Identifying Duplicate Crashes" 

To record a case, simply add the column sScoutDescription when executing a cmd=new

To edit scout info, simply add the columns sScoutMessage and/or fScoutStopReporting when you edit a case. 

Subscriptions

cmd=subscribe - Arguments: ixBug or ixWikiPage

cmd=unsubscribe - Arguments: ixBug or ixWikiPage

To check if you are subscribed to a case, use cmd=search&q=xxx&cols=fSubscribed (where xxx is the case number)

Mark as viewed

Cases marked as "viewed" will appear to be visited links in the FogBugz UI.

cmd=view

Arguments:
ixBug - must be a case number
ixBugEvent - If supplied will only mark case as being "viewed" up until this bugevent.  If omitted, will mark case as being viewed up to the latest bugevent.

 Settings

cmd=viewSettings - get back info on this person such as their timezone offset, preferred columns, etc.