FogBugz XML API version 8

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

  • If you are getting started with the XML API, we strongly recommend checking out the FogBugz XML API Development Wiki which will give you an introduction to using the API with Python.
  • Several members of our community have written API wrappers and other development tools to help with using the FogBugz XML API. Check them out in the Developer Tools section in FogBugz Extras.

Checking the API Version and location

API clients must first hit the [FogBugz URL]/api.xml.

For example, if the URL is http://www.example.com/fogbugz, hit http://www.example.com/fogbugz/api.xml. Or if your FogBugz On Demand account is https://example.fogbugz.com, hit https://example.fogbugz.com/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 FogBugz install (FogBugz 7 or later) or “api.php?” for a php install (FogBugz 6.1 or earlier).

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

NOTE: Only Admin and Normal users are able to generate valid API tokens.

FogBugz itself supports several methods of logging on, however, the only method supported by the API is by providing an email address (or full name, just like FogBugz sign-in) 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. All arguments to the API are name/value pairs in the GET or POST request. e.g. a GET request:http://www.example.com/api.asp?token=24dsg34lok43un23&cmd=new&sTitle=New%20Case&sEvent=something
  3. FogBugz is going to be religiously UTF-8.
  4. All dates should be in ISO 8601 UTC format, e.g. 2013-01-21T14:24:06Z
  5. All API requests will have a cmd argument indicating what you want to do, like cmd=logon in the logon example.
  6. 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 or by changing the user’s password.
  7. The response is a valid XML file in UTF-8 format containing an outer <response> tag at the root.
  8. If the first child node is <error>, something went wrong.
  9. 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=setCurrentFilter. The meaning is internal to FogBugz. Zero or one of the filters may have the status=”current” attribute indicating that this is the user’s 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 built-in 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=setCurrentFilter&sFilter=402

The result is purposefully empty.

<response></response>

Listing and Viewing Cases

The API differs from the web interface in that, rather than listing cases in one action and viewing specific cases in another, you can return both a list of cases and the exact information you want about them all at the same time using the cols parameter.

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
    • The information you would like returned with each case in the list.  The parameter should be a comma-separated list of column names (e.g., cols=sTitle,sStatus).  Available columns are listed below 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. For Custom Fields and other plugin fields, see this article.
    • ix columns can be empty or 0 if they are not set.  All valid ix columns (ixPersonClosedBy for example) will be > 0 if there 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. Note that settingixPersonEditedBy when using the command cmd=new sets who opened the case.  For Custom Fields and other plugin fields, see this article.

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

Arguments:

  • ixBug  - omitted for cmd=new – optional
    • If supplied, the new case is assigned this number. This functionality is provided for importing cases from another system. You must import them in order from lowest to highest case number.
  • ixBugParent
    • Make this case a subcase of another case
  • 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.
  • tags
    • When searching for the tags column via the API, returns a <tags> element with a <tag> for each tag in the case.
  • sTags
    • When editing a case, use the sTags column and submit a comma-delimited list of the tags associated with 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
  • hrsElapsedExtra
    • This sets additional non-timesheet time on a case. (i.e. if there was an hour long time interval for the case and you set hrsElapsedExtra to 2, then the total hrsElapsed would be 3)
  • 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 with 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
  • File1, File2, File3, etc
    • Upload files to the case, no limit to the number of files (constrained only by the max upload limit on the web server).  Use the enctype=”multipart/form-data” form type
  • nFileCountRequired with File1, File2, etc
    • Number of file parameters included in the request. If this is absent, only File1 will upload.

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

An example of an html page which submits to the api to create a new case and upload a file 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=editNote: the UI does not let you change any fields on close.  The API does.  However, ixPersonAssignedTo will always be set to 1 (the CLOSED user).

cmd=email, cmd=reply, and cmd=forward

Same as cmd=edit, with additional arguments: sFrom (required), sTo (required), ixBug (required), sSubject, sCC, sBCC and 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

It is not required, but we recommend making sure the case you email from has sCustomerEmail and ixMailbox set.

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, and best practices suggest using a matching ixMailbox value for the case.

Lists

cmd=listProjects - List all undeleted Projects

Arguments:

  • fWrite=0 – optional
    • Set to 1 if you only want the list of projects you have permission to write to (i.e. can edit the cases in this project). If this is left off or set to 0, then the API assumes you are looking for all areas that you have permission to read.
  • ixProject - optional
    • If included will always list at least this project even if it is deleted.
  • fIncludeDeleted=0 – optional
    • Set to 1 to include deleted projects in the results.

cmd=listAreas - List all undeleted Areas

Arguments:

  • fWrite=0 - optional
    • Set to 1 if you only want the list of areas you have permission to write to (i.e. can edit the cases in this area). If this is left off or set to 0, then the API assumes you are looking for all projects that you have permission to read.
  • ixProject  - optional
    • Only list areas from this project
  • ixAreaoptional
    • 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:

  • fIncludeActive=1 – default 1
  • fIncludeNormal=1 - default 1
  • fIncludeDeleted=0 - default 0
  • fIncludeCommunity=0 - default 0
  • fIncludeVirtual=0 - default 0

cmd=listStatuses - List Status

Arguments:

  • ixCategory – optional
    • If included, limits results to statuses within this Category only
  • fResolved=0
    • Set to 1 to have only resolved statuses in the result

cmd=listFixFors - List milestones

Arguments:

  • ixProject – optional
    • Only list milestones for this project, default behavior is to list all milestones
  • ixFixFor - optional
    • If listing all milestones will include this milestone even if it’s unassignable (i.e. inactive),
  • fIncludeDeleted=0 - default 0
    • Set to 1 to include inactive milestones (i.e. those that are marked unassignable)
  • fIncludeReallyDeleted=0 - default 0
    • Set to 1 to include completely deleted milestones (i.e. no longer viewable or assignable)

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.

cmd=listWikis - List all wikis

cmd=listTemplates - List all wiki templates

cmd=listSnippets - List all snippets.

Arguments:

  • fGlobalOnly=0 - optional, default 0
    • Returns only global snippets. If this is left off or set to 0, both private and global snippets for the current user are returned.

Creating

cmd=newProject

Arguments:

  • sProject
    • The title of the new project
  • ixPersonPrimaryContact
  • fAllowPublicSubmit
  • fInbox - default 0

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 - required
  • sFullnamerequired
  • nTypedefault 0
    • Set to 0 for a normal user, 1 for an administrator, 2 for a community user, and 3 for a virtual user
  • fActivedefault 1
  • sPassworddefault = random
  • sLocaleoptional
  • sLanguage - optional
  • sTimeZoneKey - optional
  • sSnippetKey - optional
  • fNotify - optional
  • sPhone - optional
  • sHomepage - optional

Returns:

  • ixPerson of the new person

cmd=newFixFor - Creates a new milestone

Arguments:

  • ixProject – required
    • Set ixProject to -1 to create a global milestone
  • sFixFor – required
    • The title of the new milestone
  • dtRelease - optional
  • dtStart - optional
  • sStartNote - optional
  • fAssignable - optional

Returns:

  • ixFixFor of the new milestone

Editing

cmd=editPerson

Same as cmd=newPerson, but the only required parameter is a new one: ixPerson

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 and 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 milestone

Arguments: ixFixFor OR (sFixFor and 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 OR (sStatus and ixCategory)

cmd=viewMailbox – display info about a particular mailbox

Arguments: ixMailbox

cmd=viewTemplate – display info about a particular wiki template

Arguments: ixTemplate

Milestone Dependencies

cmd=addFixForDependency - create a dependency of one milestone upon another.

Arguments: ixFixFor, ixFixForDependsOn

cmd=deleteFixForDependency - remove a dependency of one milestone upon another.

Arguments: ixFixFor, ixFixForDependsOn

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. If ixPerson is set to 1, list the site working schedule.Returns <workingschedule> (see sample XML below)

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

cmd=listProjectPercentTime - list Per-Project Percent Time

Arguments:

  • ixPerson – If ixPerson is omitted, list Per-Project Percent Times for the logged on user.

Returns per-project percent times and nPercentTimeAllOtherProjects

cmd=addProjectPercentTime - Protect a project

Arguments:

  • ixProject – The project to protect
  • nPercent – How much time will be spent on this project (between 0 and 100)

Returns the new per-project percent time information

cmd=editProjectPercentTime - edit Per-Project Percent Time

Arguments:

  • ixProjectPercentTime – The ProjectPercentTime to modify
  • nPercent – How much time will nowbe spent on the project (between 0 and 100)

Returns the modified per-project percent time information

cmd=deleteProjectPercentTime - Unprotect a project

Arguments:

  • ixProjectPercentTime – The ProjectPercentTime to delete

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 TimeIntervals for a user. Any of the optional arguments serve to filter the results.

Arguments

  • ixPerson - optional
    • Specifies which user’s intervals should be returned. If omitted, list intervals for the logged on user. If set to 1, list intervals for all users. Note that you must be an administrator to see time interval information for users other than the logged on user.
  • ixBug - optional
    • Specifies that only intervals associated with this bug should be returned.
  • dtStart, dtEnd - optional
    • If dtStart and/or dtEnd are supplied, listIntervals will return intervals whose start date falls between dtStart and dtEnd.

Source Control

NOTE: If you’re using Kiln for source control, see the Kiln API Developer’s Wiki.

cmd=newCheckin – associate a new checkin with a given FogBugz case

Arguments:

  • ixBug
    • The case with which to associate the checkin
  • sFile
    • The name of the file being checked in
  • sPrev
    • The pre-checkin revision number
  • sNew
    • The post-checkin revision number
  • ixRepository
    • The ID of the source control repository in which this file is located
  • sRepo - deprecated
    • In versions of FogBugz before 7.0, this field indicated the file’s repository. Included for backwards-compatibility. Do not use with new repositories.

cmd=listCheckins – list all of the checkins that have been associated with the specified case. (If using Kiln, please see Working with Bugs in the Kiln API.)

Arguments:

  • ixBug

Tags

cmd=listTags – list all of the tags attached to cases or wikis that are visible for the current user (available with FogBugz 8.2+)

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

Milestones

cmd=editFixFor

Edits an existing milestone (available with FogBugz 8.2+). Any optional arguments that are not included will clear the corresponding data from the milestone. This command will also remove any associations between a milestone and projects.

Arguments:

  • ixFixFor - required
  • sFixFor - required
  • dtRelease
  • dtStart
  • sStartNote
  • fAssignable

Returns:

  • ixFixFor of the milestone

Wikis

cmd=newWiki

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

cmd=editWiki

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

cmd=deleteWiki

Arguments: ixWiki

cmd=undeleteWiki

Arguments: ixWiki

cmd=newArticle

Arguments: ixWiki, sHeadline, sBody, cols, dt, ixPersonEditedBy, sTags

cmd=editArticle

Arguments: ixWikiPage, sHeadline, sBody, sComment, dt, ixPersonEditedBy, sTags

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, fDefault

cmd=editTemplate

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

cmd=wikiFileUpload

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

Discussion Groups

cmd=listDiscussGroups - list all readable discussion groups

cmd=listDiscussion

Arguments:

  • ixDiscussGroup
  • fFull - t
  • o list every post use fFull=1, for just main topics use fFull=2
  • m - m
  • onth, omit for current month
  • y - y
  • ear, omit for current year

Example:

?cmd=listDiscussion&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.

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 with cmd=edit.

Subscriptions

cmd=subscribe

Arguments: ixBug or ixWikiPage, ixPerson (Only Admins may use this parameter)

cmd=unsubscribe

Arguments: ixBug or ixWikiPage, ixPerson (Only Admins may use this parameter)

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

Email Correspondents

Manage the list of email addresses which FogBugz auto-completes when you enter a correspondent in a case.

cmd=addEmailAddress

Arguments: sFullEmail

cmd=deleteEmailAddress

Arguments: sEmail

cmd=findEmailAddress

Arguments: sEmail – To list all email addresses, use sEmail=@

Mark as viewed

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

cmd=view

Arguments:

  • ixBug - required
  • 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. To mark a case as unread, use ixBugEvent=1

Star/unstar (available with 8.2+)

cmd=star or cmd=unstar

Arguments:

  • sType
    • One of the following strings: Bug, WikiPage, or DiscussTopic
  • ixItem
    • Value of the ixBug, ixWikiPage, or ixDiscussTopic. Must correspond with the value of sType.
  • ixPerson
    • Optional (Only admins may use this parameter). When absent, will star for current user.

Settings

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

Site Settings

cmd=viewSiteSettings – get back info about this installation’s site-wide settings such as the FogBugz version, customized names of extra fields, etc.

Evidence-Based Scheduling

cmd=viewUserTimelineReport

View the complete set of EBS milestone work simulations for all users required to complete this milestone and all of its dependencies. This is the same data that is displayed in the Per-User Timeline Report.

Arguments: ixFixFor, ixPriority

cmd=viewUserShipDateReport

Like viewUserTimelineReport, but only including the simulation of the final milestone to be completed by each user. This is the same data that is show in the Per-User Ship Date report.

Arguments: ixFixFor, ixPriority

cmd=viewShipDateReport

View the distribution of overall completion dates for this milestone at this Priority. This is the same data that is shown in the Ship Date report.

Arguments: ixFixFor, ixPriority

cmd=viewHoursRemainingReport

View the distribution of projected overall hours remaining to complete this milesone at this Priority. This is the data that is aggregated over time in the Burn Down Chart. Including fThisFixForOnly=1 gives the data that is aggregated in the Burn Down Chart (this milestone only).

Arguments: required: ixFixFor, ixPriority optional: fThisFixForOnly (defaults to false)

cmd=listShipDate

List the historical nightly ship date calculations for this milestone at this Priority from the time when the milestone was created until now.

Arguments: ixFixFor, ixPriority

cmd=viewEstimator

View the distributions of actual/estimated ratios in this person’s estimate history.

Arguments: ixPerson

Increasing the next case number via the API

cmd=adminSetCaseNumber

This sets the next newly created case to start with this case number. For example, if the current highest case number is 35, and you want the next case number to start at 5000, then you can run this command with the value of 5000. Note that you can only use this command to raise the next value, not lower it. Please note that this cannot be undone.

Arguments: ixBug

Sample XML Payloads

Cases:

<cases count="1"> -- count is included in the cases attribute
  <case ixBug="123" operations="edit,assign,resolve,reactivate,close,reopen,reply,forward,email,move,spam,remind">
    -- note: currently move, spam, and remind are not supported actions. Older version of the API which call the deprecated cmd=list (instead of cmd=search&q=) will not see reply, forward, or email operations in the case listing
  <ixBug>123</ixBug> -- case number
    <ixBugParent>234</ixBugParent> -- parent case number
    <ixBugChildren>456,876</ixBugChildren> -- subcase numbers
    <tags> -- tags
      <tag><![CDATA[first]]></tag>
      <tag><![CDATA[second]]></tag>
      <tag><![CDATA[third]]></tag>
    </tags>
    <fOpen>true</fOpen> -- true if open, false if closed
    <sTitle>Duck, Duck... but No Goose!</sTitle> -- title
    <sOriginalTitle>Problem finding the goose...</sTitle> -- original title for a case opened by an incoming email or a public case submission
    <sLatestTextSummary>I searched the docs, but no goose!</sLatestTextSummary> -- short string with case's latest comment
    <ixBugEventLatestText>1151</ixBugEventLatestText> -- ixBugEvent for latest event with actual text comment
    <ixProject>22</ixProject> -- project id
    <sProject>The Farm</sProject> -- project name
    <ixArea>35</ixArea> -- area id
    <sArea>Pond</sArea> -- area name
    <ixGroup>6</ixGroup> -- group id (deprecated as of FogBugz 8--will always return 0)
    <ixPersonAssignedTo>1</ixPersonAssignedTo> -- person case is assigned to (id)
    <sPersonAssignedTo>Old MacDonald</sPersonAssignedTo> -- person case is assigned to (name)
    <sEmailAssignedTo>grandpa@oldmacdonald.com</sEmailAssignedTo> -- email of person case is assigned to
    <ixPersonOpenedBy>2</ixPersonOpenedBy> -- person case was opened by (id)
    <ixPersonResolvedBy>2</ixPersonResolvedBy> -- person case was resolved by (id)
    <ixPersonClosedBy></ixPersonClosedBy> -- person case was closed by (id)
    <ixPersonLastEditedBy>0</ixPersonLastEditedBy> -- person case was last edited by (id)
    <ixStatus>2</ixStatus> -- status (id)
    <ixBugDuplicates>321</ixBugDuplicates> -- cases that are closed as duplicates of this one (id)
    <ixBugOriginal>654</ixBugOriginal> -- the case which this one was a duplicate of (id)
    <sStatus>Geschlossen (Fixed)</sStatus> -- status (name)
    <ixPriority>3</ixPriority> -- priority (id)
    <sPriority>Must Fix</sPriority> -- priority (name)
    <ixFixFor>3</ixFixFor> -- fixfor (id)
    <sFixFor>Test</sFixFor> -- fixfor (name)
    <dtFixFor>2007-05-06T22:47:59Z</dtFixFor> -- date of fixfor (date)
    <sVersion></sVersion> -- version field (custom field #1)
    <sComputer></sComputer> -- computer field (custom field #2)
    <hrsOrigEst>0</hrsOrigEst> -- hours of original estimate (0 if no estimate)
    <hrsCurrEst>0</hrsCurrEst> -- hours of current estimate
    <hrsElapsed>0</hrsElapsed> -- total elapsed hours -- includes all time from time intervals PLUS hrsElapsedExtra time
    <c>0</c> -- number of occurrences (minus 1) of this bug (increased via bugzscout)
      -- to display the actual number of occurrences, add 1 to this number  
    <sCustomerEmail></sCustomerEmail> -- if there is a customer contact for this case, this is their email
    <ixMailbox>0</ixMailbox> -- if this case came in via dispatcho, the mailbox it came in on
    <ixCategory>1</ixCategory> -- category (id)
    <sCategory>Feature</sCategory> -- category (name)
    <dtOpened>2007-05-06T22:47:59Z</dtOpened> -- date case was opened
    <dtResolved>2007-05-06T22:47:59Z</dtResolved> -- date case was resolved
    <dtClosed>2007-05-06T22:47:59Z</dtClosed> -- date case was closed
    <ixBugEventLatest>1151</ixBugEventLatest> -- latest bugevent
    <dtLastUpdated>2007-05-06T22:47:59Z</dtLastUpdated> -- the date when this case was last updated
    <fReplied>false</fReplied> -- has this case been replied to?
    <fForwarded>false</fForwarded> -- has this case been forwarded?
    <sTicket></sTicket> -- id for customer to view bug (bug number + 8 letters e.g. 4003_XFLFFFCS)
    <ixDiscussTopic>0</ixDiscussTopic> -- id of discussion topic if case is related
    <dtDue></dtDue> -- date this case is due (empty if no due date)
    <sReleaseNotes></sReleaseNotes> -- release notes
    <ixBugEventLastView>1151</ixBugEventLastView> -- the ixBugEventLatest when you last viewed this case
    <dtLastView>2007-05-06T22:47:59Z</dtLastView> -- the date when you last viewed this case
    <ixRelatedBugs>345,267,2920</ixRelatedBugs> -- comma separated list of other related case numbers
    <sScoutDescription>Main.cpp:165</sScoutDescription> -- if this case is a Scout case, this ID is the unique identifier
    <sScoutMessage>Please contact us or visit our knowledge base to resolve.</sScoutMessage> -- this is the message
      -- displayed to users when they submit a case that matches this sScoutDescription  
    <fScoutStopReporting>false</fScoutStopReporting> -- whether we are still recording occurrences of this crash or not
    <dtLastOccurrence>2007-05-06T22:47:59Z</dtLastOccurrence> -- most recent occurrence of this crash, if this is a BugzScout case
    <fSubscribed>true</fSubscribed> -- true if you are subscribed to this case, otherwise false
  </case>
</cases> 

BugEvents:

<events>
  <event ixBugEvent="174" ixBug="13">
  <ixBugEvent>174</ixBugEvent> -- Identity field in the database for this event
    <evt>4</evt> -- Number for type of event, see event codes
    <sVerb>Assigned to Captain Caveman</sVerb> -- Description of event in English always
    <ixPerson>3</ixPerson> -- Identity field of the person who made this event happen
    <sPerson>Mikey</sPerson> -- Person's full name
    <ixPersonAssignedTo>4</ixPersonAssignedTo> -- Identity field of the person this case is assigned to
    <dt>2007-05-06T22:47:59Z</dt> -- Date event happened (in RFC822 UTC format)
    <s>Up up and away!</s> -- The text of the event (if this is an email or was created in HTML mode via Rich Case Events, this is a plain-text version of the event)
    <sHTML><![CDATA[<strong>Up up and away!</strong>]]></sHTML> -- If this is an event created in HTML mode via Rich Case Events, this contains the raw HTML version of the event
    <fEmail>false</fEmail> -- True if it is an email event
    <bEmail>false</bEmail> -- Deprecated: use fEmail
    <fExternal>false</fExternal> -- True if this case was created via an incoming email, discussion topic, or BugzScout
    <bExternal>false</bExternal> -- Deprecated: use fExternal
    <fHTML>true</fHTML> -- True if the event is an email and the html version has been cached. You should not need to look at this field. Instead use fEmail to determine if the event is an email and sFormat to determine if an edit is html-formatted
    <sFormat>html</sFormat> -- 'html' if the event was created in HTML mode via Rich Case Events
    <sChanges>Project changed from 'Inbox' to 'Cave'.</sChanges> -- Description of changes to the case during this event
    <evtDescription>Captain Caveman von Mikey zugewiesen</evtDescription> -- Description of event in YOUR language (in this case German)
    <rgAttachments><attachment><sFileName>Test Word.doc</sFileName> -- name of the attached file
    <sURL>default.asp?pg=pgDownload&amp;pgType=pgAttachment&amp;ixBugEvent=756&amp;sPart=2&amp;sTicket=&amp;sFileName=Test%20Word.doc</sURL> -- url to hit to get the contents of the attached file (add on token=<yourtoken>)
    </attachment></rgAttachments>-- if the event is an email (fEmail == true) then there are additional fields --
    <sFrom>"JJ Walker" <jj@dynomite.org></sFrom> -- the from header from the message
    <sTo>good@times.org</sTo> -- the to header from the message
    <sCC></sCC> -- the cc header from the message
    <sBCC></sBCC> -- the bcc header from the message (if readable)
    <sReplyTo></sReplyTo> -- the replyto header from the message
    <sSubject></sSubject> -- the subject header from the message
    <sDate>5 Jun 07 21:07:54 GMT</sDate> -- the date header from the message (exactly as it appears usually rfc822 date)
    <sBodyText></sBodyText> -- the body plaintext from the message
    <sBodyHTML></sBodyHTML> -- the message formatted in html
  </event>
</events>

Or, minievents for less information:

<minievents>
  <event ixBugEvent="174" ixBug="13">
  <ixBugEvent>174</ixBugEvent> -- Identity field in the database for this event
    <evt>4</evt> -- Number for type of event, see event codes
    <sVerb>Assigned to Captain Caveman</sVerb> -- Description of event in English always
    <ixPerson>3</ixPerson> -- Identity field of the person who made this event happen
    <sPerson>Mikey</sPerson> -- Person's full name
    <ixPersonAssignedTo>4</ixPersonAssignedTo> -- Identity field of the person this case is assigned to
    <dt>2007-05-06T22:47:59Z</dt> -- Date event happened (in RFC822 UTC format)
    <fEmail>false</fEmail> -- True if it is an email event
    <fHTML>false</fHTML> -- True if the event is an email and the html version has been cached. You should not need to look at this field. Instead use fEmail to determine if the event is an email and sFormat to determine if an edit is html-formatted
    <sFormat></sFormat> -- 'html' if the event was created in HTML mode via Rich Case Events
    <fExternal>false</fExternal> -- True if this case was created via an incoming email, discussion topic, or BugzScout
    <sChanges>Project changed from 'Inbox' to 'Cave'.</sChanges> -- Description of changes to the case during this event
    <evtDescription>Captain Caveman von Mikey zugewiesen</evtDescription> -- Description of event in YOUR language (in this case German)
      -- if the event is an email (fEmail == true) then there are additional fields --
    <sFrom>"JJ Walker" <jj@dynomite.org></sFrom> -- the from header from the message
    <sTo>good@times.org</sTo> -- the to header from the message
    <sCC></sCC> -- the cc header from the message
    <sBCC></sBCC> -- the bcc header from the message (if readable)
    <sReplyTo></sReplyTo> -- the replyto header from the message
    <sSubject></sSubject> -- the subject header from the message
    <sDate>5 Jun 07 21:07:54 GMT</sDate> -- the date header from the message (exactly as it appears usually rfc822 date)
  </event>
</minievents>

BugzScout Case:

cmd=listScoutCase


<case ixBug="5184" operations="edit,assign,resolve,email,remind">
  <ixBug>5184</ixBug>
  <sScoutMessage/>
  <fScoutStopReporting>
    <![CDATA[ False ]]>
  </fScoutStopReporting>
  <sScoutDescription>
    <![CDATA[ crash in CMyClass.GetData() at line 125 - version 2.5.44 ]]>
  </sScoutDescription>
  <dtLastOccurrence>2013-01-08T19:54:58Z</dtLastOccurrence>
</case>

Projects:

<projects>
  <project>
    <ixProject>68</ixProject> -- project id
    <sProject>The Farm</sProject> -- project name
    <ixPersonOwner>6</ixPersonOwner> -- person who is the default owner for this project (id)
    <sPersonOwner>Old MacDonald</sPersonOwner> -- name of owner
    <sEmail>grandpa@oldmacdonald.com</sEmail> -- email of owner
    <sPhone>555-294-4778</sPhone> -- phone of owner
    <fInbox>false</fInbox> -- true if this is the Inbox project
    <iType>1</iType> -- type of group this project is part of (1 = client / 2 = dept)
    <ixGroup>1</ixGroup> -- group (id) this project is part of (deprecated as of FogBugz 8 -- will always return 0)
    <sGroup>Internal</sGroup> -- name of group this project is part of
  </project>
</projects>

Project:

<project>
  <ixProject>3</ixProject>
  <sProject>
    <![CDATA[ Inbox ]]>
  </sProject>
  <ixPersonOwner>2</ixPersonOwner>
  <fInbox>true</fInbox>
  <fDeleted>false</fDeleted>
  <sPublicSubmitEmail/>
</project>

Areas:

<areas>
  <area>
    <ixArea>53</ixArea> -- area id
    <sArea>Bug</sArea> -- area name
    <ixProject>23</ixProject> -- project (id) this area belongs to
    <sProject>Antioch, CA</sProject> -- project (name) this area belongs to
    <ixPersonOwner></ixPersonOwner> -- default owner of this area. if empty then use project owner
    <sPersonOwner></sPersonOwner> -- name of owner of this area. if empty then use project owner
    <nType>0</nType> -- type of area: 0=normal, 1=Not Spam, 2=Undecided, 3=Spam (Inbox areas only)
    <cDoc>0</cDoc> -- number of documents trained into area (autosorted areas only)
  </area>
</areas>

Area:

<area>
  <ixArea>12</ixArea>
  <sArea>
    <![CDATA[ Widget Support ]]>
  </sArea>
  <ixProject>3</ixProject>
  <ixPersonOwner>5</ixPersonOwner>
  <nType>0</nType> -- type of area: 0 = normal, 1 = Not Spam, 2 = Undecided, 3 = Spam (Inbox areas only)
  <cDoc>0</cDoc> -- number of documents trained into area (autosorted areas only)
  <fDeleted>false</fDeleted>
</area>

FixFors (Milestones):

<fixfors>
  <fixfor>
    <ixFixFor>1</ixFixFor>
    <sFixFor>Undecided</sFixFor>
    <fDeleted>0</fDeleted>
    <dt/>
    <dtStart/>
    <sStartNote/>
    <setixFixForDependency/>
    <ixProject/>
    <sProject/>
  </fixfor>
  <fixfor>
    <ixFixFor>2</ixFixFor>
    <sFixFor>2005.1</sFixFor>
    <fDeleted>0</fDeleted>
    <dt>2005-12-05T00:00:00Z</dt>
    <dtStart>2005-10-01T00:00:00Z</dtStart>
    <sStartNote>Can't start work until the hardware arrives.</sStartNote>
    <setixFixForDependency><ixFixFor>3</ixFixFor></setixFixForDependency>
    <ixProject>5</ixProject>
    <sProject>New York City</sProject>
  </fixfor></fixfors>

FixFor (Milestone):

<fixfor>
  <ixFixFor>1</ixFixFor>
  <sFixFor>
    <![CDATA[ Undecided ]]>
  </sFixFor>
  <fInactive>false</fInactive>
  <dt/>
  <ixProject>-1</ixProject>
  <dtStart/>
  <sStartNote/>
  <setixFixForDependency/>
</fixfor>

Priorities:

<priorities>
  <priority>
    <ixPriority>1</ixPriority> -- priority id
    <sPriority>Very Urgent</sPriority> -- priority name
  </priority>
</priorities>

Priority:

<priority>
  <ixPriority>7</ixPriority>
  <sPriority>
    <![CDATA[ Don't Fix ]]>
  </sPriority>
</priority>

Categories:

<categories>
  <category>
    <ixCategory>1</ixCategory> -- category id
    <sCategory>Bug</sCategory> -- category name
    <sPlural>Bugs</sPlural> -- category plural name
    <ixStatusDefault>2</ixStatusDefault> -- when a case of this category type is resolved, the status id of the default (selected) status
    <fIsScheduleItem>false</fIsScheduleItem> -- true if this is a schedule item category
  </category>
  <category>
    <ixCategory>2</ixCategory>
    <sCategory>Feature</sCategory>
    <sPlural>Features</sPlural>
    <ixStatusDefault>8</ixStatusDefault>
    <fIsScheduleItem>false</fIsScheduleItem>
  </category>
</categories>

Category:

<category>
  <ixCategory>5</ixCategory>
  <sCategory>
    <![CDATA[ Critical Bug ]]>
  </sCategory>
  <sPlural>
    <![CDATA[ Critical Bugs ]]>
  </sPlural>
  <ixStatusDefault>27</ixStatusDefault> -- when a case of this category type is resolved, the status id of the default (selected) status
  <fIsScheduleItem>false</fIsScheduleItem>
  <fDeleted>false</fDeleted>
  <iOrder>4</iOrder> -- display order as configured in Admin -> Workflow -> Categories
  <nIconType>5</nIconType> -- the built-in icon this category uses
  <ixAttachmentIcon>0</ixAttachmentIcon> -- the custom icon this category uses
  <ixStatusDefaultActive>26</ixStatusDefaultActive> -- default active status for a newly opened case with this category type
</category>

Statuses:

<statuses>
  <status>
    <ixStatus>1</ixStatus>
    <sStatus>
      <![CDATA[ Active ]]>
    </sStatus>
    <ixCategory>1</ixCategory>
    <fWorkDone>false</fWorkDone>
    <fResolved>false</fResolved>
    <fDuplicate>false</fDuplicate>
    <fDeleted>false</fDeleted>
    <iOrder>0</iOrder>
  </status>
  <status>
    <ixStatus>2</ixStatus>
    <sStatus>
      <![CDATA[ Resolved (Fixed) ]]>
    </sStatus>
    <ixCategory>1</ixCategory>
    <fWorkDone>true</fWorkDone>
    <fResolved>true</fResolved>
    <fDuplicate>false</fDuplicate>
    <fDeleted>false</fDeleted>
    <iOrder>0</iOrder>
  </status>
</statuses>

Status:

<status>
  <ixStatus>29</ixStatus>
  <sStatus>
    <![CDATA[ In Triage ]]>
  </sStatus>
  <ixCategory>5</ixCategory>
  <fWorkDone>false</fWorkDone>
  <fResolved>false</fResolved>
  <fDuplicate>false</fDuplicate>
  <fDeleted>false</fDeleted>
  <iOrder>1</iOrder>
</status>

Tags:

<tags>
  <tag>
    <ixTag>4</ixTag>
    <sTag>
    <![CDATA[ docs ]]>
    </sTag>
    <cTagUses>1</cTagUses>
  </tag>
  <tag>
    <ixTag>5</ixTag>
    <sTag>
    <![CDATA[ beta ]]>
    </sTag>
    <cTagUses>1</cTagUses>
  </tag>
</tags>

Wikis:

<wikis>
  <wiki>
    <ixWiki>1</ixWiki>
    <sWiki>
      <![CDATA[ Widget Documentation ]]>
    </sWiki>
    <sTagLineHTML/>
      <![CDATA[ <b>Full documentation for CompanyCorp Widgets</b> ]]>
    </sTagLineHTML>
    <ixWikiPageRoot>1</ixWikiPageRoot>
    <ixTemplate>2</ixTemplate>
    <fDeleted>false</fDeleted>
  </wiki>
</wikis>

Templates:

<templates>
  <template>
    <ixTemplate>1</ixTemplate> -- template id
    <sTemplate>My Template</sTemplate> -- template name
  </template>
</templates>

Template:

<template>
  <sTemplate>My Template</sTemplate> -- template name
  <sBodyHTML>...</sBodyHTML> -- template HTML
  <sBodyCSS>...</sBodyCSS> -- template CSS
  <nRevision>2</nRevision> -- current revision of the template
  <fReadOnly>false</fReadOnly> -- whether or not the template can be modified/deleted
  <fDefault>false</fDefault> -- whether or not this template is the default template for new wikis
</template>

Template Revisions:

<revisions>
  <revision>
    <nRevision>1</nRevision>
    <ixPerson>2</ixPerson>
    <sRemoteIP>
      <![CDATA[ 0.0.0.0 ]]>
    </sRemoteIP>
    <sTitle>
      <![CDATA[ Widget Documentation ]]>
    </sTitle>
    <sComment>
      <![CDATA[ template for docs: initial version ]]>
    </sComment>
    <fDiff>false</fDiff>
    <dt>2013-01-02T17:14:07Z</dt>
  </revision>
  <revision>
    <nRevision>2</nRevision>
    <ixPerson>2</ixPerson>
    <sRemoteIP>
      <![CDATA[ 0.0.0.0 ]]>
    </sRemoteIP>
    <sTitle>
      <![CDATA[ Widget Documentation ]]>
    </sTitle>
    <sComment/>
    <fDiff>false</fDiff>
    <dt>2013-01-02T17:14:26Z</dt>
  </revision>
</revisions>

Wiki Articles:

<articles>
  <article>
    <ixWikiPage>1</ixWikiPage>
    <sHeadline>
      <![CDATA[ Root Article ]]>
    </sHeadline>
  </article>
  <article>
    <ixWikiPage>3</ixWikiPage>
    <sHeadline>
      <![CDATA[ Widget Help ]]>
    </sHeadline>
  </article>
</articles>

Wiki Article:

<wikipage>
  <sHeadline>
    <![CDATA[ Root Article ]]>
  </sHeadline>
  <sBody>
    <![CDATA[ <p>This is a test article</p>
<p>
  <a class="wikiNew" fc_linktext="Widget Help" href="default.asp?W3">Widget Help</a>
</p> ]]>
  </sBody>
  <nRevision>5</nRevision>
  <tags>
    <tag>
      <![CDATA[ docs ]]>
    </tag>
  </tags>
</wikipage>

Wiki Article Revisions:

<revisions>
  <revision>
    <nRevision>1</nRevision>
    <ixPerson>2</ixPerson>
    <sRemoteIP/>
    <sTitle>
      <![CDATA[ Root Article ]]>
    </sTitle>
    <sComment>
      <![CDATA[ Created root page ]]>
    </sComment>
    <fDiff>false</fDiff>
    <dt>2012-12-20T16:24:43Z</dt>
  </revision>
  <revision>
    <nRevision>2</nRevision>
    <ixPerson>2</ixPerson>
    <sRemoteIP/>
    <sTitle>
      <![CDATA[ Root Article ]]>
    </sTitle>
    <sComment/>
    <fDiff>false</fDiff>
    <dt>2013-01-02T17:14:41Z</dt>
  </revision>
</revisions>

Filters:

<filters>
  <filter type="builtin" sFilter="ez349">My Cases</filter> -- built-in "My Cases" filter
  <filter type="saved" sFilter="304">Cases I should have closed months ago</filter> -- an example saved filter for the current user
  <filter type="shared" sFilter="98" status="current">Customer Service Top 10</filter> -- an example shared filter
</filters>

Working Schedule:

<workingSchedule>
  <ixPerson>2</ixPerson> -- person owner (id) of this schedule
  <nHoursPerDay>8</nHoursPerDay> -- hrs of day that are actually devoted to work 
  <nWorkdayStarts>9</nWorkdayStarts> -- military hour that workday starts 9am = 9 / 5pm = 17
  <nWorkdayEnds>17</nWorkdayEnds> -- military hour that workday ends 9am = 9 / 5pm = 17
  <fHasLunch>true</fHasLunch> -- whether there is time off for lunch
  <nLunchStarts>12</nLunchStarts> -- military hour that lunch starts
  <hrsLunchLength>0.5</hrsLunchLength> -- hours long that lunch lasts
  <dtLastUpdated>2007-05-06T22:39:31Z</dtLastUpdated> -- the date these values were last changed
  <rgWorkDays> -- if value is true, then it is considered a workday
    <sunday>false</sunday>
    <monday>true</monday>
    <tuesday>true</tuesday>
    <wednesday>true</wednesday>
    <thursday>true</thursday>
    <friday>true</friday>
    <saturday>false</saturday>
  </rgWorkDays>
</workingSchedule>

Project Percent Times:


<projectpercenttimes>
  <projectpercenttime>
    <m_nPercentLast>0</m_nPercentLast>
    <ixProjectPercentTime>1</ixProjectPercentTime>
    <ixPerson>2</ixPerson>
    <ixProject>2</ixProject>
    <nPercent>20</nPercent>
  </projectpercenttime>
  <projectpercenttime>
    <m_nPercentLast>0</m_nPercentLast>
    <ixProjectPercentTime>2</ixProjectPercentTime>
    <ixPerson>2</ixPerson>
    <ixProject>3</ixProject>
    <nPercent>20</nPercent>
    </projectpercenttime>
  <nPercentTimeAllOtherProjects>60</nPercentTimeAllOtherProjects>
</projectpercenttimes>

Intervals:

<intervals>  <interval>    <ixBug>2</ixBug> -- case id for this interval
    <ixInterval>8</ixInterval> -- interval (id) 
    <dtStart>9</dtStart> -- start time of interval
    <dtEnd>17</dtEnd> -- end time of interval
    <sTitle>1</sTitle> -- title of case
    <ixPerson>12</ixPerson> -- person this interval applies to
  </interval>
</intervals>

People:

<people>
  <person>
    <ixPerson>11</ixPerson> -- person (id)
    <sFullName>Old MacDonald</sFullName> -- person name
    <sEmail>grandpa@oldmacdonald.com</sEmail> -- person email
    <sPhone></sPhone> -- person phone
    <fAdministrator>false</fAdministrator> -- true if user is a site admin
    <fCommunity>false</fCommunity> -- true if user is a community user
    <fVirtual>false</fVirtual> -- true if user is a virtual user
    <fDeleted>false</fDeleted> -- true if account is inactive
    <fNotify>true</fNotify> -- true if user receives email notifications
    <sHomepage></sHomepage> -- homepage url
    <sLocale>en-us</sLocale> -- The locale code for the date/number language (i.e., "en-us") ( "*" means use browser format )
    <sLanguage>en-us</sLanguage> -- The locale code for the UI language (i.e., "en-us") ( "*" means use browser format )
    <sTimeZoneKey>Eastern Standard Time</sTimeZoneKey> -- A key that defines the time zone setting for this person's account (i.e., "Eastern Standard Time"). The values for this setting are operating system dependent. ( "*" means use fogbugz default )
    <fExpert>false</fExpert> -- No longer used
  </person>
</people>

Person:

<person>
  <ixPerson>2</ixPerson>
  <sFullName>
    <![CDATA[ Administrator ]]>
  </sFullName>
  <sEmail>
    <![CDATA[ it@example.com ]]>
  </sEmail>
  <sPhone/>
  <fAdministrator>true</fAdministrator>
  <fCommunity>false</fCommunity>
  <fVirtual>false</fVirtual>
  <fDeleted>false</fDeleted>
  <fNotify>true</fNotify>
  <sHomepage/>
  <sLocale>
    <![CDATA[ * ]]>
  </sLocale>
  <sLanguage>
    <![CDATA[ * ]]>
  </sLanguage>
  <sTimeZoneKey>
    <![CDATA[ * ]]>
  </sTimeZoneKey>
  <sSnippetKey>
    <![CDATA[ ` ]]>
  </sSnippetKey>
  <ixBugWorkingOn>0</ixBugWorkingOn>
  <nType>1</nType>
</person>

Discussion Groups (without topics):

cmd=listDiscussGroups

<discussions>
  <discussion>
    <sFullName>test</sFullName>
    <sURL>http://localhost/fb/?test</sURL>
    <sTagLineHTML>test</sTagLineHTML>
    <ixDiscussGroup>1</ixDiscussGroup>
  </discussion>
</discussions>

Discussion Group (includes topics):

cmd=listDiscussion

<discussion>
  <sFullName>test</sFullName>
  <sURL>http://localhost/fb/?test</sURL>
  <sTagLineHTML>test</sTagLineHTML>
  <topic>
    <post>
      <ixDiscussTopic>4</ixDiscussTopic>
      <ixDiscussTopicParent>0</ixDiscussTopicParent>
      <sHeadline>a second topic</sHeadline>
      <sFullName>fogtest</sFullName>
      <sURL/>
      <dt>2007-06-25T20:39:47Z</dt>
      <sPost>new topic message</sPost>
      <fModerator>true</fModerator>
      <fAuthorized>true</fAuthorized>
    </post>
  </topic>
  <topic>
    <post>
     ...    
    </post>
  </topic>
</discussion>

Discussion Topic (includes posts for topic):

cmd=listDiscussTopic

<topic>
  <post>
    <ixDiscussTopic>2</ixDiscussTopic>
    <ixDiscussTopicParent>0</ixDiscussTopicParent>
    <sHeadline>test headline</sHeadline>
    <sFullName>fogtest</sFullName>
    <sURL/>
    <dt>2007-06-25T20:24:50Z</dt>
    <sPost>message</sPost>
    <fModerator>true</fModerator>
    <fAuthorized>true</fAuthorized>
  </post>
  <post>
    <ixDiscussTopic>3</ixDiscussTopic>
    <ixDiscussTopicParent>2</ixDiscussTopicParent>
    <sHeadline>test headline</sHeadline>
    <sFullName>fogtest</sFullName>
    <sURL/>
    <dt>2007-06-25T20:39:30Z</dt>
    <sPost>another message</sPost>
    <fModerator>true</fModerator>
    <fAuthorized>true</fAuthorized>
  </post>
</topic>

Checkins:

<checkins>
  <checkin>
    <ixCVS>28444</ixCVS>
    <ixBug>403416</ixBug>
    <sFile>trunk/fogcreek/FogBugz/Website/snippet.js</sFile>
    <sPrev>0</sPrev>
    <sNew>22878</sNew>
    <sRepo></sRepo>
    <ixRepository>2</ixRepository>
  </checkin>
</checkins>

Mailboxes:

cmd=listMailboxes

<mailboxes>
  <mailbox>
    <ixMailbox>1</ixMailbox>
    <sEmail> -- the email address from mailbox settings
      <![CDATA[ "customer support" <customer@company.com> ]]>
    </sEmail>
    <sEmailUser> -- the "personal" email address with your name
      <![CDATA[ "Jonas Jalopy" <customer@company.com> ]]>
    </sEmailUser>
    <sTemplate> -- the automatic message reply text or "signature"
      <![CDATA[ -- Sincerely, Customer Service ]]>
    </sTemplate>
  </mailbox>
</mailboxes>

cmd=viewMailbox

<mailbox>
  <ixMailbox>1</ixMailbox>
  <sEmail> -- the email address from mailbox settings
    <![CDATA[ "customer support" <customer@company.com> ]]>
  </sEmail>
  <sEmailUser> -- the "personal" email address with your name
    <![CDATA[ "Jonas Jalopy" <customer@company.com> ]]>
  </sEmailUser>
  <sTemplate> -- the automatic message reply text or "signature"
    <![CDATA[ -- Sincerely, Customer Service ]]>
  </sTemplate>
</mailbox>

Settings (user):

<settings>
  <sTimeZoneKey>Eastern Standard Time</sTimeZoneKey> -- this user's time zone
  <nTimeZoneOffset>-14400</nTimeZoneOffset> -- offset in seconds from UTC for this user
  <sServerTime>2007-10-05T11:34:14Z</sServerTime> -- current time on the FogBugz server
  <cols>sCategory,ixBug,sLatestTextSummary,sStatus,ixPersonOpenedBy,sPriority</cols> -- an approximation of the columns in the user's current filter
</settings>

Site Settings (available with FogBugz 8.2+):

<sitesettings>
  <sVersion>8.2.0</sVersion> -- version of FogBugz installation
  <sCustom1>Client Phone Number</sCustom1> -- name of the first built-in Extra Case Field (not associated with the Custom Fields plugin)
  <sCustom2>Computer</sCustom2> -- name of the second built-in Extra Case Field (not associated with the Custom Fields plugin)
</sitesettings>

Evidence-Based Scheduling:

Ship Date:

<shipDate>
  <ixShipDate>704843</ixShipDate>
  <ixFixFor>281</ixFixFor>
  <ixPriority>7</ixPriority>
  <dtCalc>2008-12-06T06:01:58Z</dtCalc> -- The date and time when this calculation was performed.
  -- The 5, 50, and 95% confidence completion dates calculated --
  <dtLow>2009-01-26T22:26:46Z</dtLow>
  <dtMid>2009-02-18T19:23:12Z</dtMid>
  <dtHigh>2009-03-10T20:52:10Z</dtHigh>
  -- The 5, 50, and 95% confidence sums of projected hours remaining to complete in this FixFor and all preceding FixFors in its project. --
  <hrsLow>0</hrsLow>
  <hrsMid>0</hrsMid>
  <hrsHigh>0</hrsHigh>
  -- The 5, 50, and 95% confidence sums of projected hours remaining to complete in ths FixFor only. --
  <hrsLowThis>0</hrsLowThis>
  <hrsMidThis>0</hrsMidThis>
  <hrsHighThis>0</hrsHighThis>
  <dtOfficial>2009-02-27T05:00:00Z</dtOfficial>-- The user-supplied official ship date fo this FixFor at the time of calculation.
  <fCompleted>false</fCompleted>
</shipDate>

Estimator:

cmd=viewEstimator

<estimator>
  <ixPerson>29</ixPerson>
  <rgdblRatioSmall>
    <array>
      <item>0</item>
      <item>0.0599074074074074</item>
      <item>0.0616666666666667</item>
      <item>0.08</item>
      <item>0.108333333333333</item>
      <item>0.122222222222222</item>
      ...
    </array>
  </rgdblRatioSmall>
  <rgdblRatioBig>
    <array>
      <item>0</item>
      <item>0</item>
      <item>0.256732026143791</item>
      <item>0.333586805555556</item>
      <item>0.434944444444444</item>
      <item>0.466884531590414</item>
      ...
    </array>
  </rgdblRatioBig>
</estimator>

Snippets:

<snippets>
  <snippet>
    <ix>1</ix>
    <fGlobal>true</fGlobal> -- True if the snippet is available to all users
    <name><![CDATA[1]]></name> -- Snippet
    <text><![CDATA[Hi [[name]],

Thanks for writing to us!
]]></text> -- Replacement text
    <comment><![CDATA[Insert at the beginning of most email]]></comment> -- Notes
  </snippet>
</snippets>

Correspondent Emails:

cmd=findEmailAddress

<emails>
  <email>"Albert Einstein" <aeinstein@example.com></email>
  <email>"Bob Smith" <bob@example.com></email>
  <email>"Grace Hopper" <grace.hopper@example.com></email>
</emails>

Error Codes

  • 0 – FogBugz not initialized. Database may be down or needs to be upgraded.
  • 1 – Log On problem – Incorrect Username or Password
  • 2 – Log On problem – multiple matches for username
  • 3 – You are not logged on.
  • 4 – Argument is missing from query
  • 5 – Edit problem – the case you are trying to edit could not be found
  • 6 – Edit problem – the action you are trying to perform on this case is not permitted
  • 7 – Time tracking problem – you can’t add a time interval to this case because the case can’t be found, is closed, has no estimate, or you don’t have permission
  • 8 – New case problem – you can’t write to any project
  • 9 – Case has changed since last view
  • 10 – Search problem – an error occurred in search.
  • 12 – Wiki creation problem
  • 13 – Wiki permission problem
  • 14 – Wiki load error
  • 15 – Wiki template error
  • 16 – Wiki commit error
  • 17 – No such project
  • 18 – No such user
  • 19 – Area creation problem
  • 20 – FixFor creation problem
  • 21 – Project creation problem
  • 22 – User creation problem
  • 23 – Project percent time problem
  • 24 – No such fixfor
  • 25 – Violates fixfor execution order
  • 27 – No such API command

Event Codes

  • evtOpened = 1
  • evtEdited = 2
  • evtAssigned = 3
  • evtReactivated= 4
  • evtReopened = 5
  • evtClosed = 6
  • evtMoved = 7 ‘ 2.0 or earlier. From 3.0 on this was recorded as an Edit
  • evtUnknown = 8 ‘ Not quite sure what happened; display sVerb in the UI
  • evtReplied = 9
  • evtForwarded = 10
  • evtReceived = 11
  • evtSorted = 12
  • evtNotSorted = 13
  • evtResolved = 14
  • evtEmailed = 15
  • evtReleaseNoted = 16
  • evtDeletedAttachment = 17

Miscellaneous Notes

  • All parameters starting with the letters “dt” only accept times expressed in UTC (Coordinated Universal Time). Similarly, all return values starting with those letters will be expressed in UTC.