Bugzilla:BzAPI:Objects

This page lists the objects used on the Bugzilla:REST_API, and the fields of each, along with their types, descriptions, and any names those fields may have in other contexts.

Notes

• A general API principle is that if you don't submit a field or object to a change function, it's unchanged. This means you can send simple changes without having to send the entire bug. However, due to limitations of Bugzilla, this does not work with attachments - you need to send the whole object.
• Fields marked Read Only are set automatically by Bugzilla, based on other information or fields. They may be returned by GET calls, but will be ignored in POST or PUT. (So you don't have to remove them before sending an object back.)
• Fields marked No Mod can be set when the object is created, but are Read Only thereafter.
• For the objects other than Bug, some fields are marked Optional to show that they are not always present. For a Bug, all fields should be considered Optional apart from "id" and "ref".
• For fields of type Boolean, on submit, please use "1" and "0" for true and false. This may get relaxed later.
• Fields of type Timestamp should be sent and received in the UTC timezone in ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ (T and Z being a literal "T" and "Z").

Bug

Bold means the field is in the default set returned on the search interface.

Name	Type	Description	Other Names
actual_time	Decimal, Read Only	Time it has taken to fix the bug so far
alias	String	Bug's alias (text alternative to ID)
assigned_to	User	User responsible for the bug
attachments	Array of Attachment	Related files stored by Bugzilla	attachment
blocks	Array of Integer	IDs of bugs which can only be fixed after this one	blocked
cc	Array of User	Users signed up to be notified of changes
classification	String	Name of classification (categorization above product)
comments	Array of Comment	Things people have said about the bug	long_desc
component	String	Bug's component (sub-product)
creation_time	Timestamp String, Read Only	When bug was filed	creation_ts, opendate
creator	User, Read Only	User who submitted the bug	reporter
deadline	Datestamp String	Date by which bug must be fixed
depends_on	Array of Integer	Bugs that must be fixed first	dependson
dupe_of	Integer	Bug number of which this bug is a duplicate (only present if bug is RESOLVED DUPLICATE)
estimated_time	Decimal	Current estimated time for fix, in hours
flags	Array of Flag	Flags set on this bug
groups	Array of Group	Groups to which this bug belongs
history	Array of ChangeSet, Read Only	Changes made to bug fields in the past (requires 3.4)
id	Integer, Read Only	Unique numeric identifier for bug	bug_id
is_cc_accessible	Boolean	Whether CC list can see bug, regardless of groups	cclist_accessible
is_confirmed	Boolean, Read Only	Whether bug has ever passed from UNCONFIRMED to CONFIRMED status	everconfirmed, is_everconfirmed
is_creator_accessible	Boolean	Whether creator (reporter) can see bug, regardless of groups	reporter_accessible, is_reporter_accessible
keywords	Array of String	Tags (from a limited set) describing the bug
last_change_time	Timestamp String, Read Only	Last change	delta_ts, changeddate
op_sys	String	Operating system bug was seen on, e.g. Windows Vista, Linux
platform	String	Computing platform bug was seen on, e.g. PC, Mac	rep_platform
priority	String	How important the bug is, e.g. P1, P5
product	String	Name of product
qa_contact	User	User responsible for checking bug is fixed
ref	String, Read Only	URL of bug in API
remaining_time	Decimal, Read Only	Hours left before fix will be done
resolution	String	The resolution, if the bug is in a closed state, e.g. FIXED, DUPLICATE
see_also	Array of String	URLs of related bugs
severity	String	How severe the bug is, e.g. enhancement, critical	bug_severity
status	String	Current status, e.g. NEW, RESOLVED	bug_status
summary	String	Short sentence describing the bug	short_desc
target_milestone	String	When the bug is going to be fixed
update_token	String	Token you'll need to submit to change the bug; supplied only when logged in	token
url	String	URL relating to the bug (in search defaults only on 4.0 and above)	bug_file_loc
version	String	Version of software in which bug is seen
whiteboard	String	Notes on current status	status_whiteboard
work_time	Decimal (Submit Only)	Hours to be added to actual_time

• Field values are configurable, so examples may not apply to your Bugzilla.

Comment

Name	Type	Description	Other Names
attachment_id	Integer, Read Only	ID of attachment added at the same time as this comment, if any; 3.6 or above and /comment call only
attachment_ref	String, Read Only	Ref of attachment added at the same time as this comment, if any; 3.6 or above and /comment call only
creator	User, Read Only	User who wrote the comment
creation_time	Timestamp String, Read Only	Time comment was added
id	Integer, Read Only	Unique numeric identifier for comment; 3.4 or above (set by Bugzilla; must not be set when adding comments)
is_private	Boolean	Whether comment is private
text	String, No Mod	Text of comment (plain text)

Group

Name	Type	Description	Other Names
id	Integer	Unique numeric identifier for group (required on submit for 3.6 and below)
name	String	Unique string identifier for group (required on submit for 4.0 and above)

Between 3.6 and 4.0, Bugzilla changed which of these two fields was considered "primary". Note that you should never have Bugzilla version problems if you always supply both fields on submit, and the two fields refer to the same group (i.e. no mismatches).

Flag

Name	Type	Description	Other Names
id	Integer	Unique numeric identifier for this particular flag (set by Bugzilla; do not set when creating flags)
name	String, Read Only	Descriptive non-unique name for flag type, e.g. 'review'
requestee	String, Optional	User action is requested from, if flag is requestable; can only be set if setting status to '?'
setter	User, Read Only	User who set the flag
status	String	Flag value - '?', '+', '-' or 'X'
type_id	Integer	Unique numeric identifier for flag type

• To remove a flag, pass it to an update function with a status of "X".

ChangeSet

Name	Type	Description	Other Names
changer	User	Who made the changes
changes	Array of Change	The changes made in one change submission
change_time	Timestamp String	When the changes were made

Change

Name	Type	Description	Other Names
added	String	Values added, if any (comma-separated if multiple)
field_name	String	Name of field changed
removed	String	Values removed, if any (comma-separated if multiple)

• The values of "added" and "removed" are flat strings, never objects. If multiple values are added or removed from a multi-valued field, the values are comma-separated. Users are represented by their login names.

Attachment

Name	Type	Description	Other Names
attacher	User, Read Only	User who created attachment
bug_id	Integer, Read Only	ID if bug to which this is an attachment
bug_ref	String, Read Only	URL of associated bug in API
comments	Array of Comment, Optional, Submit Only	Bug comment associated with creation or change (only first element in array is looked at)
creation_time	Timestamp String, Read Only	When attachment was submitted
data	String, Optional, No Mod	Attachment data encoded using encoding 'encoding'; provided only when attachmentdata requested
description	String	Text describing the attachment
encoding	String, Optional, No Mod	Encoding of 'content'; 'base64' is the only supported value; provided only when attachmentdata requested
file_name	String	Path-less filename of attachment
flags	Array of Flag	Flags set on this attachment
id	Integer, Read Only	Unique numeric identifier for attachment	attach_id
is_obsolete	Boolean	Whether attachment is marked obsolete	isobsolete
is_patch	Boolean	Whether attachment is a patch	ispatch
is_private	Boolean	Whether attachment is private	isprivate
ref	String, Read Only	URL of attachment in API
size	Integer	Size of attachment, in bytes
update_token	String, Optional	Token to submit to change attachment metadata; supplied only when logged in	token
content_type	String	MIME type of attachment

• Due to limitations in Bugzilla, when updating attachments (including their flags), you must post back the entire object, otherwise Bugzilla will complain about missing fields. This limitation may be removed in future.

User

Name	Type	Description	Other Names
email	String	Email address of user (if you are logged in)
id	Integer, Optional (for the moment)	Unique numeric identifier for user (currently only supplied on /user API)
name	String	Email address of user (if you are logged in) or first part otherwise (which is therefore non-unique)	assignee, reporter, qa_contact (as flat fields)
real_name	String, Read Only, Optional	User's real name	name, assignee_realname etc.
ref	String, Read Only	URL of user in API

Error

Name	Type	Description	Other Names
code	Integer, Read Only	Unambiguous definition of error (XXXunimplemented)
error	Boolean (True), Read Only	Indicates the object is an error object
html_page	String, Read Only, Optional	If underlying implementation is screen-scraping and if error is not recognised; only present so you can read it manually!
http_code	Integer, Read Only, Optional	If Bugzilla returned a useful HTTP code
message	String, Read Only	Short English string describing error
xmlrpc_code	Integer, Read Only, Optional	If underlying implementation is XML-RPC

• Error objects are distinguished from other objects because they have an "error" member set to a true value. You should test every API return to see if it is an Error.