Bug 1038275: Comprehensible documentation for the REST API

r=gerv,a=glob

14 files changed, 4097 insertions, 0 deletions

diff --git a/docs/en/rst/api/core/v1/attachment.rst b/docs/en/rst/api/core/v1/attachment.rst
new file mode 100644
index 000000000..f89b6c23e
--- /dev/null
+++ b/docs/en/rst/api/core/v1/attachment.rst
@@ -0,0 +1,351 @@
+Attachments
+===========
+
+The Bugzilla API for creating, changing, and getting the details of attachments.
+
+.. _rest_attachments:
+
+Get Attachment
+--------------
+
+This allows you to get data about attachments, given a list of bugs and/or
+attachment IDs. Private attachments will only be returned if you are in the
+appropriate group or if you are the submitter of the attachment.
+
+**Request**
+
+To get all current attachments for a bug:
+
+.. code-block:: text
+
+   GET /rest/bug/(bug_id)/attachment
+
+To get a specific attachment based on attachment ID:
+
+.. code-block:: text
+
+   GET /rest/bug/attachment/(attachment_id)
+
+One of the below must be specified.
+
+=================  ====  ======================================================
+name               type  description
+=================  ====  ======================================================
+**bug_id**         int   Integer bug ID.
+**attachment_id**  int   Integer attachment ID.
+=================  ====  ======================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+      "bugs" : {
+         "1345" : [
+            { (attachment) },
+            { (attachment) }
+         ],
+         "9874" : [
+            { (attachment) },
+            { (attachment) }
+         ],
+      },
+      "attachments" : {
+         "234" : { (attachment) },
+         "123" : { (attachment) },
+      }
+   }
+
+An object containing two elements: ``bugs`` and ``attachments``.
+
+The attachments for the bug that you specified in the ``bug_id`` argument in
+input are returned in ``bugs`` on output. ``bugs`` is a object that has integer
+bug IDs for keys and the values are arrays of objects as attachments.
+(Fields for attachments are described below.)
+
+For the attachment that you specified directly in ``attachment_id``, they
+are returned in ``attachments`` on output. This is a object where the attachment
+ids point directly to objects describing the individual attachment.
+
+The fields for each attachment (where it says ``(attachment)`` in the
+sample response above) are:
+
+================  ========  =====================================================
+name              type      description
+================  ========  =====================================================
+data              base64    The raw data of the attachment, encoded as Base64.
+size              int       The length (in bytes) of the attachment.
+creation_time     datetime  The time the attachment was created.
+last_change_time  datetime  The last time the attachment was modified.
+id                int       The numeric ID of the attachment.
+bug_id            int       The numeric ID of the bug that the attachment is
+                            attached to.
+file_name         string    The file name of the attachment.
+summary           string    A short string describing the attachment.
+content_type      string    The MIME type of the attachment.
+is_private        boolean   ``true`` if the attachment is private (only visible
+                            to a certain group called the "insidergroup",
+                            ``false`` otherwise.
+is_obsolete       boolean   ``true`` if the attachment is obsolete, ``false``
+                            otherwise.
+is_patch          boolean   ``true`` if the attachment is a patch, ``false``
+                            otherwise.
+creator           string    The login name of the user that created the
+                            attachment.
+flags             array     Array of objects, each containing the information
+                            about the flag currently set for each attachment.
+                            Each flag object contains items descibed in the
+                            Flag object below.
+================  ========  =====================================================
+
+Flag object:
+
+=================  ========  ====================================================
+name               type      description
+=================  ========  ====================================================
+id                 int       The ID of the flag.
+name               string    The name of the flag.
+type_id            int       The type ID of the flag.
+creation_date      datetime  The timestamp when this flag was originally created.
+modification_date  datetime  The timestamp when the flag was last modified.
+status             string    The current status of the flag such as ?, +, or -.
+setter             string    The login name of the user who created or last
+                             modified the flag.
+requestee          string    The login name of the user this flag has been
+                             requested to be granted or denied. Note, this field
+                             is only returned if a requestee is set.
+=================  ========  ====================================================
+
+.. _rest_add_attachment:
+
+Create Attachment
+-----------------
+
+This allows you to add an attachment to a bug in Bugzilla.
+
+**Request**
+
+To create attachment on a current bug:
+
+.. code-block:: text
+
+   POST /rest/bug/(bug_id)/attachment
+
+.. code-block:: js
+
+   {
+     "ids" : [ 35 ],
+     "is_patch" : true,
+     "comment" : "This is a new attachment comment",
+     "summary" : "Test Attachment",
+     "content_type" : "text/plain",
+     "data" : "(Some patch content)",
+     "file_name" : "test_attachment.patch",
+     "obsoletes" : [],
+     "is_private" : false,
+     "flags" : [
+       {
+         "name" : "review",
+         "status" : "?",
+         "requestee" : "user@bugzilla.org",
+         "new" : true
+       }
+     ]
+   }
+
+
+The params to include in the POST body, as well as the returned
+data format, are the same as below. The ``bug_id`` param will be
+overridden as it it pulled from the URL path.
+
+================  =======  ======================================================
+name              type     description
+================  =======  ======================================================
+**ids**           array    The IDs or aliases of bugs that you want to add this
+                           attachment to. The same attachment and comment will be
+                           added to all these bugs.
+**data**          string   The content of the attachment. If the content of the
+                           attachment is not ASCII text such as
+                           ``application/octet-stream`` you must encode it in
+                           base64 using an appropriate client library such as
+                           ``MIME::Base64`` for Perl.
+**file_name**     string   The "file name" that will be displayed in the UI for
+                           this attachment and also downloaded copies will be
+                           given.
+**summary**       string   A short string describing the attachment.
+**content_type**  string   The MIME type of the attachment, like ``text/plain``
+                           or ``image/png``.
+comment           string   A comment to add along with this attachment.
+is_patch          boolean  ``true`` if Bugzilla should treat this attachment as a
+                           patch. If you specify this, you do not need to specify
+                           a ``content_type``. The ``content_type`` of the
+                           attachment will be forced to ``text/plain``. Defaults
+                           to ``false`` if not specified.
+is_private        boolean  ``true`` if the attachment should be private
+                           (restricted to the "insidergroup"), ``false`` if the
+                           attachment should be public. Defaults to ``false`` if
+                           not specified.
+flags             array    Flags objects to add to the attachment. The object
+                           format is described in the Flag object below.
+================  =======  ======================================================
+
+Flag object:
+
+To create a flag, at least the ``status`` and the ``type_id`` or ``name`` must
+be provided. An optional requestee can be passed if the flag type is requestable
+to a specific user.
+
+=========  ======  ==============================================================
+name       type    description
+=========  ======  ==============================================================
+name       string  The name of the flag type.
+type_id    int     The internal flag type ID.
+status     string  The flags new status (i.e. "?", "+", "-" or "X" to clear a
+                   flag).
+requestee  string  The login of the requestee if the flag type is requestable to
+                   a specific user.
+=========  ======  ==============================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "ids" : [
+       "2797"
+     ]
+   }
+
+====  =====  =========================
+name  type   description
+====  =====  =========================
+ids   array  Attachment IDs created.
+====  =====  =========================
+
+.. _rest_update_attachment:
+
+Update Attachment
+-----------------
+
+This allows you to update attachment metadata in Bugzilla.
+
+**Request**
+
+To update attachment metadata on a current attachment:
+
+.. code-block:: text
+
+   PUT /rest/bug/attachment/(attachment_id)
+
+.. code-block:: js
+
+   {
+     "ids" : [ 2796 ],
+     "summary" : "Test XML file",
+     "comment" : "Changed this from a patch to a XML file",
+     "content_type" : "text/xml",
+     "is_patch" : 0
+   }
+
+=================  =====  =======================================================
+name               type   description
+=================  =====  =======================================================
+**attachment_id**  int    Integer attachment ID.
+**ids**            array  The IDs of the attachments you want to update.
+=================  =====  =======================================================
+
+============  =======  ==========================================================
+name          type     description
+============  =======  ==========================================================
+file_name     string   The "file name" that will be displayed in the UI for this
+                       attachment.
+summary       string   A short string describing the attachment.
+comment       string   An optional comment to add to the attachment's bug.
+content_type  string   The MIME type of the attachment, like ``text/plain``
+                       or ``image/png``.
+is_patch      boolean  ``true`` if Bugzilla should treat this attachment as a
+                       patch. If you specify this, you do not need to specify a
+                       ``content_type``. The ``content_type`` of the attachment
+                       will be forced to ``text/plain``.
+is_private    boolean  ``true`` if the attachment should be private (restricted
+                       to the "insidergroup"), ``false`` if the attachment
+                       should be public.
+is_obsolete   boolean  ``true`` if the attachment is obsolete, ``false``
+                       otherwise.
+flags         array    An array of Flag objects with changes to the flags. The
+                       object format is described in the Flag object below.
+============  =======  ==========================================================
+
+Flag object:
+
+The following values can be specified. At least the ``status`` and one of
+``type_id``, ``id``, or ``name`` must be specified. If a type_id or name matches
+a single currently set flag, the flag will be updated unless ``new`` is specified.
+
+=========  =======  =============================================================
+name       type     description
+=========  =======  =============================================================
+name       string   The name of the flag that will be created or updated.
+type_id    int      The internal flag type ID that will be created or updated.
+                    You will need to specify the ``type_id`` if more than one
+                    flag type of the same name exists.
+status     string   The flags new status (i.e. "?", "+", "-" or "X" to clear a
+                    flag).
+requestee  string   The login of the requestee if the flag type is requestable
+                    to a specific user.
+id         int      Use ID to specify the flag to be updated. You will need to
+                    specify the ``id`` if more than one flag is set of the same
+                    name.
+new        boolean  Set to true if you specifically want a new flag to be
+                    created.
+=========  =======  =============================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "attachments" : [
+       {
+         "changes" : {
+           "content_type" : {
+             "added" : "text/xml",
+             "removed" : "text/plain"
+           },
+           "is_patch" : {
+             "added" : "0",
+             "removed" : "1"
+           },
+           "summary" : {
+             "added" : "Test XML file",
+             "removed" : "test patch"
+           }
+         },
+         "id" : 2796,
+         "last_change_time" : "2014-09-29T14:41:53Z"
+       }
+     ]
+   }
+
+``attachments`` (array) Change objects with the following items:
+
+================  ========  =====================================================
+name              type      description
+================  ========  =====================================================
+id                int       The ID of the attachment that was updated.
+last_change_time  datetime  The exact time that this update was done at, for this
+                            attachment. If no update was done (that is, no fields
+                            had their values changed and no comment was added)
+                            then this will instead be the last time the
+                            attachment was updated.
+changes           object    The changes that were actually done on this
+                            attachment. The keys are the names of the fields that
+                            were changed, and the values are an object with two
+                            items:
+
+                            * added: (string) The values that were added to this
+                              field. Possibly a comma-and-space-separated list
+                              if multiple values were added.
+                            * removed: (string) The values that were removed from
+                              this field.
+================  ========  =====================================================
diff --git a/docs/en/rst/api/core/v1/bug-user-last-visit.rst b/docs/en/rst/api/core/v1/bug-user-last-visit.rst
new file mode 100644
index 000000000..919744968
--- /dev/null
+++ b/docs/en/rst/api/core/v1/bug-user-last-visit.rst
@@ -0,0 +1,111 @@
+Bug User Last Visited
+=====================
+
+.. _rest-bug-user-last-visit-update:
+
+Update Last Visited
+-------------------
+
+Update the last-visited time for the specified bug and current user.
+
+**Request**
+
+To update the time for a single bug id:
+
+.. code-block:: text
+
+   POST /rest/bug_user_last_visit/(id)
+
+To update one or more bug ids at once:
+
+.. code-block:: text
+
+   POST /rest/bug_user_last_visit
+
+.. code-block:: js
+
+   {
+     "ids" : [35,36,37]
+   }
+
+=======  =====  ==============================
+name     type   description
+=======  =====  ==============================
+**id**   int    An integer bug id.
+**ids**  array  One or more bug ids to update.
+=======  =====  ==============================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     {
+       "id" : 100,
+       "last_visit_ts" : "2014-10-16T17:38:24Z"
+     }
+   ]
+
+An array of objects containing the items:
+
+=============  ========  ============================================
+name           type      description
+=============  ========  ============================================
+id             int       The bug id.
+last_visit_ts  datetime  The timestamp the user last visited the bug.
+=============  ========  ============================================
+
+.. _rest-bug-user-last-visit-get:
+
+Get Last Visited
+----------------
+
+**Request**
+
+Get the last-visited timestamp for one or more specified bug ids or get a
+list of the last 20 visited bugs and their timestamps.
+
+To return the last-visited timestamp for a single bug id:
+
+.. code-block:: text
+
+   GET /rest/bug_user_last_visit/(id)
+
+To return more than one specific bug timestamps:
+
+.. code-block:: text
+
+   GET /rest/bug_user_last_visit/123?ids=234&ids=456
+
+To return just the most recent 20 timestamps:
+
+.. code-block:: text
+
+   GET /rest/bug_user_last_visit
+
+=======  =====  ============================================
+name     type   description
+=======  =====  ============================================
+**id**   int    An integer bug id.
+**ids**  array  One or more optional bug ids to get.
+=======  =====  ============================================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     {
+       "id" : 100,
+       "last_visit_ts" : "2014-10-16T17:38:24Z"
+     }
+   ]
+
+An array of objects containing the following items:
+
+=============  ========  ============================================
+name           type      description
+=============  ========  ============================================
+id             int       The bug id.
+last_visit_ts  datetime  The timestamp the user last visited the bug.
+=============  ========  ============================================
diff --git a/docs/en/rst/api/core/v1/bug.rst b/docs/en/rst/api/core/v1/bug.rst
new file mode 100644
index 000000000..1bf2a2006
--- /dev/null
+++ b/docs/en/rst/api/core/v1/bug.rst
@@ -0,0 +1,986 @@
+Bugs
+====
+
+The REST API for creating, changing, and getting the details of bugs.
+
+This part of the Bugzilla REST API allows you to file new bugs in Bugzilla and
+to get information about existing bugs.
+
+.. _rest_single_bug:
+
+Get Bug
+-------
+
+Gets information about particular bugs in the database.
+
+**Request**
+
+To get information about a particular bug using its ID or alias:
+
+.. code-block::  text
+
+   GET /rest/bug/(id_or_alias)
+
+You can also use :ref:`rest_search_bugs` to return more than one bug at a time
+by specifying bug IDs as the search terms.
+
+.. code-block:: text
+
+   GET /rest/bug?id=12434,43421
+
+================  =====  ======================================================
+name              type   description
+================  =====  ======================================================
+**id_or_alias**   mixed  An integer bug ID or a bug alias string.
+================  =====  ======================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "faults": [],
+     "bugs": [
+       {
+         "assigned_to_detail": {
+           "id": 2,
+           "real_name": "Test User",
+           "name": "user@bugzilla.org",
+           "email": "user@bugzilla.org"
+         },
+         "flags": [
+           {
+             "type_id": 11,
+             "modification_date": "2014-09-28T21:03:47Z",
+             "name": "blocker",
+             "status": "?",
+             "id": 2906,
+             "setter": "user@bugzilla.org",
+             "creation_date": "2014-09-28T21:03:47Z"
+           }
+         ],
+         "resolution": "INVALID",
+         "id": 35,
+         "qa_contact": "",
+         "version": "1.0",
+         "status": "RESOLVED",
+         "creator": "user@bugzilla.org",
+         "cf_drop_down": "---",
+         "summary": "test bug",
+         "last_change_time": "2014-09-23T19:12:17Z",
+         "platform": "All",
+         "url": "",
+         "classification": "Unclassified",
+         "cc_detail": [
+           {
+             "id": 786,
+             "real_name": "Foo Bar",
+             "name": "foo@bar.com",
+             "email": "foo@bar.com"
+           },
+         ],
+         "priority": "P1",
+         "is_confirmed": true,
+         "creation_time": "2000-07-25T13:50:04Z",
+         "assigned_to": "user@bugzilla.org",
+         "flags": [],
+         "alias": [],
+         "cf_large_text": "",
+         "groups": [],
+         "op_sys": "All",
+         "cf_bug_id": null,
+         "depends_on": [],
+         "is_cc_accessible": true,
+         "is_open": false,
+         "cf_qa_list_4": "---",
+         "keywords": [],
+         "cc": [
+           "foo@bar.com",
+         ],
+         "see_also": [],
+         "deadline": null,
+         "is_creator_accessible": true,
+         "whiteboard": "",
+         "dupe_of": null,
+         "target_milestone": "---",
+         "cf_mulitple_select": [],
+         "component": "SaltSprinkler",
+         "severity": "critical",
+         "cf_date": null,
+         "product": "FoodReplicator",
+         "creator_detail": {
+           "id": 28,
+           "real_name": "hello",
+           "name": "user@bugzilla.org",
+           "email": "namachi@netscape.com"
+         },
+         "cf_free_text": "",
+         "blocks": []
+       }
+     ]
+   }
+
+``bugs`` (array) Each bug object contains information about the bugs with valid
+ids containing the following items:
+
+These fields are returned by default or by specifying ``_default`` in
+``include_fields``.
+
+=====================  ========  ================================================
+name                   type      description
+=====================  ========  ================================================
+actual_time            double    The total number of hours that this bug has
+                                 taken so far. If you are not in the time-tracking
+                                 group, this field will not be included in the
+                                 return value.
+alias                  array     The unique aliases of this bug. An empty array
+                                 will be returned if this bug has no aliases.
+assigned_to            string    The login name of the user to whom the bug is
+                                 assigned.
+assigned_to_detail     object    An object containing detailed user information
+                                 for the assigned_to. To see the keys included
+                                 in the user detail object, see below.
+blocks                 array     The IDs of bugs that are "blocked" by this bug.
+cc                     array     The login names of users on the CC list of this
+                                 bug.
+cc_detail              array     Array of objects containing detailed user
+                                 information for each of the cc list members.
+                                 To see the keys included in the user detail
+                                 object, see below.
+classification         string    The name of the current classification the bug
+                                 is in.
+component              string    The name of the current component of this bug.
+creation_time          datetime  When the bug was created.
+creator                string    The login name of the person who filed this bug
+                                 (the reporter).
+creator_detail         object    An object containing detailed user information
+                                 for the creator. To see the keys included in the
+                                 user detail object, see below.
+deadline               string    The day that this bug is due to be completed, in
+                                 the format ``YYYY-MM-DD``.
+depends_on             array     The IDs of bugs that this bug "depends on".
+dupe_of                int       The bug ID of the bug that this bug is a
+                                 duplicate of. If this bug isn't a duplicate of
+                                 any bug, this will be null.
+estimated_time         double    The number of hours that it was estimated that
+                                 this bug would take. If you are not in the
+                                 time-tracking group, this field will not be
+                                 included in the return value.
+flags                  array     An array of objects containing the information
+                                 about flags currently set for the bug. Each flag
+                                 objects contains the following items
+groups                 array     The names of all the groups that this bug is in.
+id                     int       The unique numeric ID of this bug.
+is_cc_accessible       boolean   If true, this bug can be accessed by members of
+                                 the CC list, even if they are not in the groups
+                                 the bug is restricted to.
+is_confirmed           boolean   ``true`` if the bug has been confirmed. Usually
+                                 this means that the bug has at some point been
+                                 moved out of the ``UNCONFIRMED`` status and into
+                                 another open status.
+is_open                boolean   ``true`` if this bug is open, ``false`` if it
+                                 is closed.
+is_creator_accessible  boolean   If ``true``, this bug can be accessed by the
+                                 creator of the bug, even if they are not a
+                                 member of the groups the bug is restricted to.
+keywords               array     Each keyword that is on this bug.
+last_change_time       datetime  When the bug was last changed.
+op_sys                 string    The name of the operating system that the bug
+                                 was filed against.
+platform               string    The name of the platform (hardware) that the bug
+                                 was filed against.
+priority               string    The priority of the bug.
+product                string    The name of the product this bug is in.
+qa_contact             string    The login name of the current QA Contact on the
+                                 bug.
+qa_contact_detail      object    An object containing detailed user information
+                                 for the qa_contact. To see the keys included in
+                                 the user detail object, see below.
+remaining_time         double    The number of hours of work remaining until work
+                                 on this bug is complete. If you are not in the
+                                 time-tracking group, this field will not be
+                                 included in the return value.
+resolution             string    The current resolution of the bug, or an empty
+                                 string if the bug is open.
+see_also               array     The URLs in the See Also field on the bug.
+severity               string    The current severity of the bug.
+status                 string    The current status of the bug.
+summary                string    The summary of this bug.
+target_milestone       string    The milestone that this bug is supposed to be
+                                 fixed by, or for closed bugs, the milestone that
+                                 it was fixed for.
+update_token           string    The token that you would have to pass to the
+                                 ``process_bug.cgi`` page in order to update this
+                                 bug. This changes every time the bug is updated.
+                                 This field is not returned to logged-out users.
+url                    string    A URL that demonstrates the problem described in
+                                 the bug, or is somehow related to the bug report.
+version                string    The version the bug was reported against.
+whiteboard             string    The value of the "status whiteboard" field on
+                                 the bug.
+=====================  ========  ================================================
+
+Custom fields:
+
+Every custom field in this installation will also be included in the
+return value. Most fields are returned as strings. However, some field types have
+different return values.
+
+Normally custom fields are returned by default similar to normal bug fields or
+you can specify only custom fields by using ``_custom`` in ``include_fields``.
+
+Extra fields:
+
+These fields are returned only by specifying ``_extra`` or the field name in
+``include_fields``.
+
+====  =====  ====================================================================
+name  type   description
+====  =====  ====================================================================
+tags  array  Each array item is a tag name. Note that tags are
+             personal to the currently logged in user and are not the same as
+             comment tags.
+====  =====  ====================================================================
+
+User object:
+
+=========  ======  ==============================================================
+name       type    description
+=========  ======  ==============================================================
+id         int     The user ID for this user.
+real_name  string  The 'real' name for this user, if any.
+name       string  The user's Bugzilla login.
+email      string  The user's email address. Currently this is the same value as
+                   the name.
+=========  ======  ==============================================================
+
+Flag object:
+
+=================  ========  ====================================================
+name               type      description
+=================  ========  ====================================================
+id                 int       The ID of the flag.
+name               string    The name of the flag.
+type_id            int       The type ID of the flag.
+creation_date      datetime  The timestamp when this flag was originally created.
+modification_date  datetime  The timestamp when the flag was last modified.
+status             string    The current status of the flag.
+setter             string    The login name of the user who created or last
+                             modified the flag.
+requestee          string    The login name of the user this flag has been
+                             requested to be granted or denied. Note, this field
+                             is only returned if a requestee is set.
+=================  ========  ====================================================
+
+Custom field object:
+
+You can specify to only return custom fields by specifying ``_custom`` or the
+field name in ``include_fields``.
+
+* Bug ID Fields: (int)
+* Multiple-Selection Fields: (array of strings)
+* Date/Time Fields: (datetime)
+
+.. _rest_history:
+
+Bug History
+-----------
+
+Gets the history of changes for particular bugs in the database.
+
+**Request**
+
+To get the history for a specific bug ID:
+
+.. code-block:: text
+
+   GET /rest/bug/(id)/history
+
+To get the history for a bug since a specific date:
+
+.. code-block:: text
+
+   GET /rest/bug/(id)/history?new_since=YYYY-MM-DD
+
+=========  ========  ============================================================
+name       type      description
+=========  ========  ============================================================
+**id**     mixed     An integer bug ID or alias.
+new_since  datetime  A datetime timestamp to only show history since.
+=========  ========  ============================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "bugs": [
+       {
+         "alias": [],
+         "history": [
+           {
+             "when": "2014-09-23T19:12:17Z",
+             "who": "user@bugzilla.org",
+             "changes": [
+               {
+                 "added": "P1",
+                 "field_name": "priority",
+                 "removed": "P2"
+               },
+               {
+                 "removed": "blocker",
+                 "field_name": "severity",
+                 "added": "critical"
+               }
+             ]
+           },
+           {
+             "when": "2014-09-28T21:03:47Z",
+             "who": "user@bugzilla.org",
+             "changes": [
+               {
+                 "added": "blocker?",
+                 "removed": "",
+                 "field_name": "flagtypes.name"
+               }
+             ]
+           }
+         ],
+         "id": 35
+       }
+     ]
+   }
+
+``bugs`` (array) Bug objects each containing the following items:
+
+=======  =====  =================================================================
+name     type   description
+=======  =====  =================================================================
+id       int    The numeric ID of the bug.
+alias    array  The unique aliases of this bug. An empty array will be returned
+                if this bug has no aliases.
+history  array  An array of History objects.
+=======  =====  =================================================================
+
+History object:
+
+=======  ========  ==============================================================
+name     type      description
+=======  ========  ==============================================================
+when     datetime  The date the bug activity/change happened.
+who      string    The login name of the user who performed the bug change.
+changes  array     An array of Change objects which contain all the changes that
+                   happened to the bug at this time (as specified by ``when``).
+=======  ========  ==============================================================
+
+Change object:
+
+=============  ======  ==========================================================
+name           type    description
+=============  ======  ==========================================================
+field_name     string  The name of the bug field that has changed.
+removed        string  The previous value of the bug field which has been
+                       deleted by the change.
+added          string  The new value of the bug field which has been added
+                       by the change.
+attachment_id  int     The ID of the attachment that was changed.
+                       This only appears if the change was to an attachment,
+                       otherwise ``attachment_id`` will not be present in this
+                       object.
+=============  ======  ==========================================================
+
+.. _rest_search_bugs:
+
+Search Bugs
+-----------
+
+Allows you to search for bugs based on particular criteria.
+
+**Request**
+
+To search for bugs:
+
+.. code-block:: text
+
+   GET /rest/bug
+
+Unless otherwise specified in the description of a parameter, bugs are
+returned if they match *exactly* the criteria you specify in these
+parameters. That is, we don't match against substrings--if a bug is in
+the "Widgets" product and you ask for bugs in the "Widg" product, you
+won't get anything.
+
+Criteria are joined in a logical AND. That is, you will be returned
+bugs that match *all* of the criteria, not bugs that match *any* of
+the criteria.
+
+Each parameter can be either the type it says, or a list of the types
+it says. If you pass an array, it means "Give me bugs with *any* of
+these values." For example, if you wanted bugs that were in either
+the "Foo" or "Bar" products, you'd pass:
+
+.. code-block:: text
+
+   GET /rest/bug?product=Foo&product=Bar
+
+Some Bugzillas may treat your arguments case-sensitively, depending
+on what database system they are using. Most commonly, though, Bugzilla is
+not case-sensitive with the arguments passed (because MySQL is the
+most-common database to use with Bugzilla, and MySQL is not case sensitive).
+
+In addition to the fields listed below, you may also use criteria that
+is similar to what is used in the Advanced Search screen of the Bugzilla
+UI. This includes fields specified by ``Search by Change History`` and
+``Custom Search``. The easiest way to determine what the field names are and what
+format Bugzilla expects is to first construct your query using the
+Advanced Search UI, execute it and use the query parameters in they URL
+as your query for the REST call.
+
+================  ========  =====================================================
+name              type      description
+================  ========  =====================================================
+alias             array     The unique aliases of this bug. An empty array will
+                            be returned if this bug has no aliases.
+assigned_to       string    The login name of a user that a bug is assigned to.
+component         string    The name of the Component that the bug is in. Note
+                            that if there are multiple Components with the same
+                            name, and you search for that name, bugs in *all*
+                            those Components will be returned. If you don't want
+                            this, be sure to also specify the ``product`` argument.
+creation_time     datetime  Searches for bugs that were created at this time or
+                            later. May not be an array.
+creator           string    The login name of the user who created the bug. You
+                            can also pass this argument with the name
+                            ``reporter``, for backwards compatibility with
+                            older Bugzillas.
+id                int       The numeric ID of the bug.
+last_change_time  datetime  Searches for bugs that were modified at this time
+                            or later. May not be an array.
+limit             int       Limit the number of results returned. If the limit
+                            is more than zero and higher than the maximum limit
+                            set by the administrator, then the maximum limit will
+                            be used instead. If you set the limit equal to zero,
+                            then all matching results will be returned instead.
+offset            int       Used in conjunction with the ``limit`` argument,
+                            ``offset`` defines the starting position for the
+                            search. For example, given a search that would
+                            return 100 bugs, setting ``limit`` to 10 and
+                            ``offset`` to 10 would return bugs 11 through 20
+                            from the set of 100.
+op_sys            string    The "Operating System" field of a bug.
+platform          string    The Platform (sometimes called "Hardware") field of
+                            a bug.
+priority          string    The Priority field on a bug.
+product           string    The name of the Product that the bug is in.
+resolution        string    The current resolution--only set if a bug is closed.
+                            You can find open bugs by searching for bugs with an
+                            empty resolution.
+severity          string    The Severity field on a bug.
+status            string    The current status of a bug (not including its
+                            resolution, if it has one, which is a separate field
+                            above).
+summary           string    Searches for substrings in the single-line Summary
+                            field on bugs. If you specify an array, then bugs
+                            whose summaries match *any* of the passed substrings
+                            will be returned. Note that unlike searching in the
+                            Bugzilla UI, substrings are not split on spaces. So
+                            searching for ``foo bar`` will match "This is a foo
+                            bar" but not "This foo is a bar". ``['foo', 'bar']``,
+                            would, however, match the second item.
+tags              string    Searches for a bug with the specified tag. If you
+                            specify an array, then any bugs that match *any* of
+                            the tags will be returned. Note that tags are
+                            personal to the currently logged in user.
+target_milestone  string    The Target Milestone field of a bug. Note that even
+                            if this Bugzilla does not have the Target Milestone
+                            field enabled, you can still search for bugs by
+                            Target Milestone. However, it is likely that in that
+                            case, most bugs will not have a Target Milestone set
+                            (it defaults to "---" when the field isn't enabled).
+qa_contact        string    The login name of the bug's QA Contact. Note that
+                            even if this Bugzilla does not have the QA Contact
+                            field enabled, you can still search for bugs by QA
+                            Contact (though it is likely that no bug will have a
+                            QA Contact set, if the field is disabled).
+url               string    The "URL" field of a bug.
+version           string    The Version field of a bug.
+whiteboard        string    Search the "Status Whiteboard" field on bugs for a
+                            substring. Works the same as the ``summary`` field
+                            described above, but searches the Status Whiteboard
+                            field.
+quicksearch       string    Search for bugs using quicksearch syntax.
+================  ========  =====================================================
+
+**Response**
+
+The same as :ref:`rest_single_bug`.
+
+.. _rest_create_bug:
+
+Create Bug
+----------
+
+This allows you to create a new bug in Bugzilla. If you specify any
+invalid fields, an error will be thrown stating which field is invalid.
+If you specify any fields you are not allowed to set, they will just be
+set to their defaults or ignored.
+
+You cannot currently set all the items here that you can set on enter_bug.cgi.
+
+The WebService interface may allow you to set things other than those listed
+here, but realize that anything undocumented here may likely change in the
+future.
+
+**Request**
+
+To create a new bug in Bugzilla.
+
+.. code-block:: text
+
+   POST /rest/bug
+
+.. code-block:: js
+
+   {
+     "product" : "TestProduct",
+     "component" : "TestComponent",
+     "version" : "unspecified",
+     "summary" : "'This is a test bug - please disregard",
+     "alias" : "SomeAlias",
+     "op_sys" : "All",
+     "priority" : "P1",
+     "rep_platform" : "All"
+   }
+
+Some params must be set, or an error will be thrown. These params are
+marked in **bold**.
+
+Some parameters can have defaults set in Bugzilla, by the administrator.
+If these parameters have defaults set, you can omit them. These parameters
+are marked (defaulted).
+
+Clients that want to be able to interact uniformly with multiple
+Bugzillas should always set both the params marked required and those
+marked (defaulted), because some Bugzillas may not have defaults set
+for (defaulted) parameters, and then this method will throw an error
+if you don't specify them.
+
+==================  =======  ====================================================
+name                type     description
+==================  =======  ====================================================
+**product**         string   The name of the product the bug is being filed
+                             against.
+**component**       string   The name of a component in the product above.
+**summary**         string   A brief description of the bug being filed.
+**version**         string   A version of the product above; the version the
+                             bug was found in.
+description         string   (defaulted) The initial description for this bug.
+                             Some Bugzilla installations require this to not be
+                             blank.
+op_sys              string   (defaulted) The operating system the bug was
+                             discovered on.
+platform            string   (defaulted) What type of hardware the bug was
+                             experienced on.
+priority            string   (defaulted) What order the bug will be fixed in by
+                             the developer, compared to the developer's other
+                             bugs.
+severity            string   (defaulted) How severe the bug is.
+alias               array    One or more brief aliases for the bug that can be
+                             used instead of a bug number when accessing this bug.
+                             Must be unique in all of this Bugzilla.
+assigned_to         string   A user to assign this bug to, if you don't want it
+                             to be assigned to the component owner.
+cc                  array    An array of usernames to CC on this bug.
+comment_is_private  boolean  If set to true, the description is private,
+                             otherwise it is assumed to be public.
+groups              array    An array of group names to put this bug into. You
+                             can see valid group names on the Permissions tab of
+                             the Preferences screen, or, if you are an
+                             administrator, in the Groups control panel. If you
+                             don't specify this argument, then the bug will be
+                             added into all the groups that are set as being
+                             "Default" for this product. (If you want to avoid
+                             that, you should specify ``groups`` as an empty
+                             array.)
+qa_contact          string   If this installation has QA Contacts enabled, you
+                             can set the QA Contact here if you don't want to
+                             use the component's default QA Contact.
+status              string   The status that this bug should start out as. Note
+                             that only certain statuses can be set on bug
+                             creation.
+resolution          string   If you are filing a closed bug, then you will have
+                             to specify a resolution. You cannot currently
+                             specify a resolution of ``DUPLICATE``   for new
+                             bugs, though. That must be done with
+                             :ref:`rest_update_bug`.
+target_milestone    string   A valid target milestone for this product.
+flags               array    Flags objects to add to the bug. The object format
+                             is described in the Flag object below.
+==================  =======  ====================================================
+
+Flag object:
+
+To create a flag, at least the ``status`` and the ``type_id`` or ``name`` must
+be provided. An optional requestee can be passed if the flag type is requestable
+to a specific user.
+
+=========  ======  ==============================================================
+name       type    description
+=========  ======  ==============================================================
+name       string  The name of the flag type.
+type_id    int     The internal flag type ID.
+status     string  The flags new status (i.e. "?", "+", "-" or "X" to clear flag).
+requestee  string  The login of the requestee if the flag type is requestable
+                   to a specific user.
+=========  ======  ==============================================================
+
+In addition to the above parameters, if your installation has any custom
+fields, you can set them just by passing in the name of the field and
+its value as a string.
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id" : 12345
+   }
+
+====  ====  ======================================
+name  type  description
+====  ====  ======================================
+id    int   This is the ID of the newly-filed bug.
+====  ====  ======================================
+
+.. _rest_update_bug:
+
+Update Bug
+----------
+
+Allows you to update the fields of a bug. Automatically sends emails
+out about the changes.
+
+**Request**
+
+To update the fields of a current bug.
+
+.. code-block:: text
+
+   PUT /rest/bug/(id_or_alias)
+
+.. code-block:: js
+
+   {
+     "ids" : [35],
+     "status" : "IN_PROGRESS",
+     "keywords" : {
+       "add" : ["funny", "stupid"]
+     }
+   }
+
+The params to include in the PUT body as well as the returned data format,
+are the same as below. You can specify the ID or alias of the bug to update
+either in the URL path and/or in the ``ids`` param. You can use both and they
+will be combined so you can edit more than one bug at a time.
+
+===============  =====  =========================================================
+name             type   description
+===============  =====  =========================================================
+**id_or_alias**  mixed  An integer bug ID or alias.
+**ids**          array  The IDs or aliases of the bugs that you want to modify.
+===============  =====  =========================================================
+
+All following fields specify the values you want to set on the bugs you are
+updating.
+
+=====================  =======  =================================================
+name                   type     description
+=====================  =======  =================================================
+alias                  object   These specify the aliases of a bug that can be
+                                used instead of a bug number when acessing this
+                                bug. To set these, you should pass a hash as the
+                                value. The object may contain the following
+                                items:
+
+                                * ``add`` (array) Aliases to add to this field.
+                                * ``remove`` (array) Aliases to remove from this
+                                  field. If the aliases are not already in the
+                                  field, they will be ignored.
+                                * ``set`` (array) An exact set of aliases to set
+                                  this field to, overriding the current value.
+                                  If you specify ``set``, then ``add`` and
+                                  ``remove`` will be ignored.
+
+                                You can only set this if you are modifying a
+                                single bug. If there is more than one bug
+                                specified in ``ids``, passing in a value for
+                                ``alias`` will cause an error to be thrown.
+
+                                For backwards compatibility, you can also
+                                specify a single string. This will be treated as
+                                if you specified the set key above.
+assigned_to            string   The full login name of the user this bug is
+                                assigned to.
+blocks                 object   (Same as ``depends_on`` below)
+depends_on             object   These specify the bugs that this bug blocks or
+                                depends on, respectively. To set these, you
+                                should pass an object as the value. The object
+                                may contain the following items:
+
+                                * ``add`` (array) Bug IDs to add to this field.
+                                * ``remove`` (array) Bug IDs to remove from this
+                                  field. If the bug IDs are not already in the
+                                  field, they will be ignored.
+                                * ``set`` (array of) An exact set of bug IDs to
+                                  set this field to, overriding the current
+                                  value. If you specify ``set``, then ``add``
+                                  and ``remove`` will be ignored.
+cc                     object   The users on the cc list. To modify this field,
+                                pass an object, which may have the following
+                                items:
+
+                                * ``add`` (array) User names to add to the CC
+                                  list. They must be full user names, and an
+                                  error will be thrown if you pass in an invalid
+                                  user name.
+                                * ``remove`` (array) User names to remove from
+                                  the CC list. They must be full user names, and
+                                  an error will be thrown if you pass in an
+                                  invalid user name.
+is_cc_accessible       boolean  Whether or not users in the CC list are allowed
+                                to access the bug, even if they aren't in a group
+                                that can normally access the bug.
+comment                object   A comment on the change. The object may contain
+                                the following items:
+
+                                * ``body`` (string) The actual text of the
+                                  comment. For compatibility with the parameters
+                                  to :ref:`rest_add_comment`, you can also call
+                                  this field ``comment``, if you want.
+                                * ``is_private`` (boolean) Whether the comment is
+                                  private or not. If you try to make a comment
+                                  private and you don't have the permission to,
+                                  an error will be thrown.
+comment_is_private     object   This is how you update the privacy of comments
+                                that are already on a bug. This is a object,
+                                where the keys are the ``int`` ID of comments
+                                (not their count on a bug, like #1, #2, #3, but
+                                their globally-unique ID, as returned by
+                                :ref:`rest_comments` and the value is a
+                                ``boolean`` which specifies whether that comment
+                                should become private (``true``) or public
+                                (``false``).
+
+                                The comment IDs must be valid for the bug being
+                                updated. Thus, it is not practical to use this
+                                while updating multiple bugs at once, as a single
+                                comment ID will never be valid on multiple bugs.
+component              string   The Component the bug is in.
+deadline               date     The Deadline field is a date specifying when the
+                                bug must be completed by, in the format
+                                ``YYYY-MM-DD``.
+dupe_of                int      The bug that this bug is a duplicate of. If you
+                                want to mark a bug as a duplicate, the safest
+                                thing to do is to set this value and *not* set
+                                the ``status`` or ``resolutio`` fields. They will
+                                automatically be set by Bugzilla to the
+                                appropriate values for duplicate bugs.
+estimated_time         double   The total estimate of time required to fix the
+                                bug, in hours. This is the *total* estimate, not
+                                the amount of time remaining to fix it.
+flags                  array    An array of Flag change objects. The items needed
+                                are described below.
+groups                 object   The groups a bug is in. To modify this field,
+                                pass an object, which may have the following
+                                items:
+
+                                * ``add`` (array) The names of groups to add.
+                                  Passing in an invalid group name or a group
+                                  that you cannot add to this bug will cause an
+                                  error to be thrown.
+                                * ``remove`` (array) The names of groups to
+                                  remove. Passing in an invalid group name or a
+                                  group that you cannot remove from this bug
+                                  will cause an error to be thrown.
+keywords               object   Keywords on the bug. To modify this field, pass
+                                an object, which may have the following items:
+
+                                * ``add`` (array) The names of keywords to add
+                                  to the field on the bug. Passing something that
+                                  isn't a valid keyword name will cause an error
+                                  to be thrown.
+                                * ``remove`` (array) The names of keywords to
+                                  remove from the field on the bug. Passing
+                                  something that isn't a valid keyword name will
+                                  cause an error to be thrown.
+                                * ``set`` (array) An exact set of keywords to set
+                                  the field to, on the bug. Passing something
+                                  that isn't a valid keyword name will cause an
+                                  error to be thrown. Specifying ``set``
+                                  overrides ``add`` and ``remove``.
+op_sys                 string   The Operating System ("OS") field on the bug.
+platform               string   The Platform or "Hardware" field on the bug.
+priority               string   The Priority field on the bug.
+product                string   The name of the product that the bug is in. If
+                                you change this, you will probably also want to
+                                change ``target_milestone``, ``version``, and
+                                ``component``, since those have different legal
+                                values in every product.
+
+                                If you cannot change the ``target_milestone``
+                                field, it will be reset to the default for the
+                                product, when you move a bug to a new product.
+
+                                You may also wish to add or remove groups, as
+                                which groups are
+                                valid on a bug depends on the product. Groups
+                                that are not valid in the new product will be
+                                automatically removed, and groups which are
+                                mandatory in the new product will be automaticaly
+                                added, but no other automatic group changes will
+                                be done.
+
+                                .. note::
+                                   Users can only move a bug into a product if
+                                   they would normally have permission to file
+                                   new bugs in that product.
+qa_contact             string   The full login name of the bug's QA Contact.
+is_creator_accessible  boolean  Whether or not the bug's reporter is allowed
+                                to access the bug, even if they aren't in a group
+                                that can normally access the bug.
+remaining_time         double   How much work time is remaining to fix the bug,
+                                in hours. If you set ``work_time`` but don't
+                                explicitly set ``remaining_time``, then the
+                                ``work_time`` will be deducted from the bug's
+                                ``remaining_time``.
+reset_assigned_to      boolean  If true, the ``assigned_to`` field will be
+                                reset to the default for the component that the
+                                bug is in. (If you have set the component at the
+                                same time as using this, then the component used
+                                will be the new component, not the old one.)
+reset_qa_contact       boolean  If true, the ``qa_contact`` field will be reset
+                                to the default for the component that the bug is
+                                in. (If you have set the component at the same
+                                time as using this, then the component used will
+                                be the new component, not the old one.)
+resolution             string   The current resolution. May only be set if you
+                                are closing a bug or if you are modifying an
+                                already-closed bug. Attempting to set the
+                                resolution to *any* value (even an empty or null
+                                string) on an open bug will cause an error to be
+                                thrown.
+
+                                .. note::
+                                   If you change the ``status`` field to an open
+                                   status, the resolution field will automatically
+                                   be cleared, so you don't have to clear it
+                                   manually.
+see_also               object   The See Also field on a bug, specifying URLs to
+                                bugs in other bug trackers. To modify this field,
+                                pass an object, which may have the following
+                                items:
+
+                                * ``add`` (array) URLs to add to the field. Each
+                                  URL must be a valid URL to a bug-tracker, or
+                                  an error will be thrown.
+                                * ``remove`` (array) URLs to remove from the
+                                  field. Invalid URLs will be ignored.
+severity               string   The Severity field of a bug.
+status                 string   The status you want to change the bug to. Note
+                                that if a bug is changing from open to closed,
+                                you should also specify a ``resolution``.
+summary                string   The Summary field of the bug.
+target_milestone       string   The bug's Target Milestone.
+url                    string   The "URL" field of a bug.
+version                string   The bug's Version field.
+whiteboard             string   The Status Whiteboard field of a bug.
+work_time              double   The number of hours worked on this bug as part
+                                of this change.
+                                If you set ``work_time`` but don't explicitly
+                                set ``remaining_time``, then the ``work_time``
+                                will be deducted from the bug's ``remaining_time``.
+=====================  =======  =================================================
+
+You can also set the value of any custom field by passing its name as
+a parameter, and the value to set the field to. For multiple-selection
+fields, the value should be an array of strings.
+
+Flag change object:
+
+The following values can be specified. At least the ``status`` and one of
+``type_id``, ``id``, or ``name`` must be specified. If a ``type_id`` or
+``name`` matches a single currently set flag, the flag will be updated unless
+``new`` is specified.
+
+==========  =======  ============================================================
+name        type     description
+==========  =======  ============================================================
+name        string   The name of the flag that will be created or updated.
+type_id     int      The internal flag type ID that will be created or updated.
+                     You will need to specify the ``type_id`` if more than one
+                     flag type of the same name exists.
+**status**  string   The flags new status (i.e. "?", "+", "-" or "X" to clear a
+                     flag).
+requestee   string   The login of the requestee if the flag type is requestable
+                     to a specific user.
+id          int      Use ID to specify the flag to be updated. You will need to
+                     specify the ``id`` if more than one flag is set of the same
+                     name.
+new         boolean  Set to true if you specifically want a new flag to be
+                     created.
+==========  =======  ============================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "bugs" : [
+       {
+         "alias" : [],
+         "changes" : {
+           "keywords" : {
+             "added" : "funny, stupid",
+             "removed" : ""
+           },
+             "status" : {
+               "added" : "IN_PROGRESS",
+               "removed" : "CONFIRMED"
+           }
+         },
+         "id" : 35,
+         "last_change_time" : "2014-09-29T14:25:35Z"
+       }
+     ]
+   }
+
+``bugs`` (array) This points to an array of objects with the following items:
+
+================  ========  =====================================================
+name              type      description
+================  ========  =====================================================
+id                int       The ID of the bug that was updated.
+alias             array     The aliases of the bug that was updated, if this bug
+                            has any alias.
+last_change_time  datetime  The exact time that this update was done at, for
+                            this bug. If no update was done (that is, no fields
+                            had their values changed and no comment was added)
+                            then this will instead be the last time the bug was
+                            updated.
+changes           object    The changes that were actually done on this bug. The
+                            keys are the names of the fields that were changed,
+                            and the values are an object with two keys:
+
+                            * ``added`` (string) The values that were added to
+                              this field, possibly a comma-and-space-separated
+                              list if multiple values were added.
+                            * ``removed`` (string) The values that were removed
+                              from this field, possibly a
+                              comma-and-space-separated list if multiple values
+                              were removed.
+================  ========  =====================================================
+
+Currently, some fields are not tracked in changes: ``comment``,
+``comment_is_private``, and ``work_time``. This means that they will not
+show up in the return value even if they were successfully updated.
+This may change in a future version of Bugzilla.
diff --git a/docs/en/rst/api/core/v1/bugzilla.rst b/docs/en/rst/api/core/v1/bugzilla.rst
new file mode 100644
index 000000000..2dd40e0cb
--- /dev/null
+++ b/docs/en/rst/api/core/v1/bugzilla.rst
@@ -0,0 +1,302 @@
+Bugzilla Information
+====================
+
+These methods are used to get general configuration information about this
+Bugzilla instance.
+
+Version
+-------
+
+Returns the current version of Bugzilla. Normally in the format of ``X.X`` or
+``X.X.X``. For example, ``4.4`` for the initial release of a new branch. Or
+``4.4.6`` for a minor release on the same branch.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/version
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "version": "4.5.5+"
+   }
+
+=======  ======  =========================================
+name     type    description
+=======  ======  =========================================
+version  string  The current version of this Bugzilla
+=======  ======  =========================================
+
+Extensions
+----------
+
+Gets information about the extensions that are currently installed and enabled
+in this Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/extensions
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "extensions": {
+       "Voting": {
+         "version": "4.5.5+"
+       },
+       "BmpConvert": {
+         "version": "1.0"
+       }
+     }
+   }
+
+==========  ======  ====================================================
+name        type    description
+==========  ======  ====================================================
+extensions  object  An object containing the extensions enabled as keys.
+                    Each extension object contains the following keys:
+
+                    * ``version`` (string) The version of the extension.
+==========  ======  ====================================================
+
+Timezone
+--------
+
+Returns the timezone in which Bugzilla expects to receive dates and times on the API.
+Currently hard-coded to UTC ("+0000"). This is unlikely to change.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/timezone
+
+.. code-block:: js
+
+   {
+     "timezone": "+0000"
+   }
+
+**Response**
+
+========  ======  ===============================================================
+name      type    description
+========  ======  ===============================================================
+timezone  string  The timezone offset as a string in (+/-)XXXX (RFC 2822) format.
+========  ======  ===============================================================
+
+Time
+----
+
+Gets information about what time the Bugzilla server thinks it is, and
+what timezone it's running in.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/time
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "web_time_utc": "2014-09-26T18:01:30Z",
+     "db_time": "2014-09-26T18:01:30Z",
+     "web_time": "2014-09-26T18:01:30Z",
+     "tz_offset": "+0000",
+     "tz_short_name": "UTC",
+     "tz_name": "UTC"
+   }
+
+=============  ======  ==========================================================
+name           type    description
+=============  ======  ==========================================================
+db_time        string  The current time in UTC, according to the Bugzilla
+                       database server.
+
+                       Note that Bugzilla assumes that the database and the
+                       webserver are running in the same time zone. However,
+                       if the web server and the database server aren't
+                       synchronized or some reason, *this* is the time that
+                       you should rely on or doing searches and other input
+                       to the WebService.
+web_time       string  This is the current time in UTC, according to
+                       Bugzilla's web server.
+
+                       This might be different by a second from ``db_time``
+                       since this comes from a different source. If it's any
+                       more different than a second, then there is likely
+                       some problem with this Bugzilla instance. In this
+                       case you should rely  on the ``db_time``, not the
+                       ``web_time``.
+web_time_utc   string  Identical to ``web_time``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+tz_name        string  The literal string ``UTC``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+tz_short_name  string  The literal string ``UTC``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+tz_offset      string  The literal string ``+0000``. (Exists only for
+                       backwards-compatibility with versions of Bugzilla
+                       before 3.6.)
+=============  ======  ==========================================================
+
+Parameters
+----------
+
+Returns parameter values currently used in this Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/parameters
+
+**Response**
+
+Example response for anonymous user:
+
+.. code-block:: js
+
+   {
+      "parameters" : {
+         "maintainer" : "admin@example.com",
+         "requirelogin" : "0"
+      }
+   }
+
+Example response for authenticated user:
+
+.. code-block:: js
+
+   {
+      "parameters" : {
+          "allowemailchange" : "1",
+          "attachment_base" : "http://bugzilla.example.com/",
+          "commentonchange_resolution" : "0",
+          "commentonduplicate" : "0",
+          "cookiepath" : "/",
+          "createemailregexp" : ".*",
+          "defaultopsys" : "",
+          "defaultplatform" : "",
+          "defaultpriority" : "--",
+          "defaultseverity" : "normal",
+          "duplicate_or_move_bug_status" : "RESOLVED",
+          "emailregexp" : "^[\\w\\.\\+\\-=']+@[\\w\\.\\-]+\\.[\\w\\-]+$",
+          "emailsuffix" : "",
+          "letsubmitterchoosemilestone" : "1",
+          "letsubmitterchoosepriority" : "1",
+          "mailfrom" : "bugzilla-daemon@example.com",
+          "maintainer" : "admin@example.com",
+          "maxattachmentsize" : "1000",
+          "maxlocalattachment" : "0",
+          "musthavemilestoneonaccept" : "0",
+          "noresolveonopenblockers" : "0",
+          "password_complexity" : "no_constraints",
+          "rememberlogin" : "on",
+          "requirelogin" : "0",
+          "urlbase" : "http://bugzilla.example.com/",
+          "use_see_also" : "1",
+          "useclassification" : "1",
+          "usemenuforusers" : "0",
+          "useqacontact" : "1",
+          "usestatuswhiteboard" : "1",
+          "usetargetmilestone" : "1",
+      }
+   }
+
+A logged-out user can only access the ``maintainer`` and ``requirelogin``
+parameters.
+
+A logged-in user can access the following parameters (listed alphabetically):
+
+* allowemailchange
+* attachment_base
+* commentonchange_resolution
+* commentonduplicate
+* cookiepath
+* defaultopsys
+* defaultplatform
+* defaultpriority
+* defaultseverity
+* duplicate_or_move_bug_status
+* emailregexpdesc
+* emailsuffix
+* letsubmitterchoosemilestone
+* letsubmitterchoosepriority
+* mailfrom
+* maintainer
+* maxattachmentsize
+* maxlocalattachment
+* musthavemilestoneonaccept
+* noresolveonopenblockers
+* password_complexity
+* rememberlogin
+* requirelogin
+* search_allow_no_criteria
+* urlbase
+* use_see_also
+* useclassification
+* usemenuforusers
+* useqacontact
+* usestatuswhiteboard
+* usetargetmilestone
+
+A user in the tweakparams group can access all existing parameters.
+New parameters can appear or obsolete parameters can disappear depending
+on the version of Bugzilla and on extensions being installed.
+The list of parameters returned by this method is not stable and will
+never be stable.
+
+Last Audit Time
+---------------
+
+Gets the most recent timestamp among all of the events recorded in the audit_log
+table.
+
+**Request**
+
+To get most recent audit timestamp for all classes:
+
+.. code-block:: text
+
+   GET /rest/last_audit_time
+
+To get the the most recent audit timestamp for the ``Bugzilla::Product`` class:
+
+.. code-block:: text
+
+   GET /rest/last_audit_time?class=Bugzilla::Product
+
+=====  =====  ===================================================================
+name   type   description
+=====  =====  ===================================================================
+class  array  The class names are defined as ``Bugzilla::<class_name>"`` such as
+              Bugzilla:Product`` for products.
+=====  =====  ===================================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "last_audit_time": "2014-09-23T18:03:38Z"
+   }
+
+===============  ======  ====================================================
+name             type    description
+===============  ======  ====================================================
+last_audit_time  string  The maximum of the at_time from the audit_log.
+===============  ======  ====================================================
diff --git a/docs/en/rst/api/core/v1/classification.rst b/docs/en/rst/api/core/v1/classification.rst
new file mode 100644
index 000000000..8b5003d39
--- /dev/null
+++ b/docs/en/rst/api/core/v1/classification.rst
@@ -0,0 +1,80 @@
+Classifications
+===============
+
+This part of the Bugzilla API allows you to deal with the available
+classifications. You will be able to get information about them as well as
+manipulate them.
+
+.. _rest_get_classification:
+
+Get Classification
+------------------
+
+Returns an object containing information about a set of classifications.
+
+**Request**
+
+To return information on a single classification using the ID or name:
+
+.. code-block:: text
+
+   GET /rest/classification/(id_or_name)
+
+==============  =====  =====================================
+name            type   description
+==============  =====  =====================================
+**id_or_name**  mixed  An Integer classification ID or name.
+==============  =====  =====================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "classifications": [
+       {
+         "sort_key": 0,
+         "description": "Unassigned to any classifications",
+         "products": [
+           {
+             "id": 2,
+             "name": "FoodReplicator",
+             "description": "Software that controls a piece of hardware that will create any food item through a voice interface."
+           },
+           {
+             "description": "Spider secretions",
+             "name": "Ѕpїdєr Séçretíøns",
+             "id": 4
+           }
+         ],
+         "id": 1,
+         "name": "Unclassified"
+       }
+     ]
+   }
+
+``classifications`` (array) Each object is a classification that the user is
+authorized to see and has the following items:
+
+===========  ======  ============================================================
+name         type    description
+===========  ======  ============================================================
+id           int     The ID of the classification.
+name         string  The name of the classification.
+description  string  The description of the classificaion.
+sort_key     int     The value which determines the order the classification is
+                     sorted.
+products     array   Products the user is authorized to
+                     access within the classification. Each hash has the
+                     following keys:
+===========  ======  ============================================================
+
+Product object:
+
+===========  ======  ================================
+name         type    description
+===========  ======  ================================
+name         string  The name of the product.
+id           int     The ID of the product.
+description  string  The description of the product.
+===========  ======  ================================
diff --git a/docs/en/rst/api/core/v1/comment.rst b/docs/en/rst/api/core/v1/comment.rst
new file mode 100644
index 000000000..60fabb93b
--- /dev/null
+++ b/docs/en/rst/api/core/v1/comment.rst
@@ -0,0 +1,242 @@
+Comments
+========
+
+.. _rest_comments:
+
+Get Comments
+------------
+
+This allows you to get data about comments, given a bug ID or comment ID.
+
+**Request**
+
+To get all comments for a particular bug using the bug ID or alias:
+
+.. code-block:: text
+
+   GET /rest/bug/(id_or_alias)/comment
+
+To get a specific comment based on the comment ID:
+
+.. code-block:: text
+
+   GET /rest/bug/comment/(comment_id)
+
+===============  ========  ======================================================
+name             type      description
+===============  ========  ======================================================
+**id_or_alias**  mixed     A single integer bug ID or alias.
+**comment_id**   int       A single integer comment ID.
+new_since        datetime  If specified, the method will only return comments
+                           *newer* than this time. This only affects comments
+                           returned from the ``ids`` argument. You will always be
+                           returned all comments you request in the
+                           ``comment_ids`` argument, even if they are older than
+                           this date.
+===============  ========  ======================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "bugs": {
+       "35": {
+         "comments": [
+           {
+             "time": "2000-07-25T13:50:04Z",
+             "text": "test bug to fix problem in removing from cc list.",
+             "bug_id": 35,
+             "count": 0,
+             "attachment_id": null,
+             "is_private": false,
+             "tags": [],
+             "creator": "user@bugzilla.org",
+             "creation_time": "2000-07-25T13:50:04Z",
+             "id": 75
+           }
+         ]
+       }
+     },
+     "comments": {}
+   }
+
+Two items are returned:
+
+``bugs`` This is used for bugs specified in ``ids``. This is an object,
+where the keys are the numeric IDs of the bugs, and the value is
+a object with a single key, ``comments``, which is an array of comments.
+(The format of comments is described below.)
+
+Any individual bug will only be returned once, so if you specify an ID
+multiple times in ``ids``, it will still only be returned once.
+
+``comments`` Each individual comment requested in ``comment_ids`` is
+returned here, in a object where the numeric comment ID is the key,
+and the value is the comment. (The format of comments is described below.)
+
+A "comment" as described above is a object that contains the following items:
+
+=============  ========  ========================================================
+name           type      description
+=============  ========  ========================================================
+id             int       The globally unique ID for the comment.
+bug_id         int       The ID of the bug that this comment is on.
+attachment_id  int       If the comment was made on an attachment, this will be
+                         the ID of that attachment. Otherwise it will be null.
+count          int       The number of the comment local to the bug. The
+                         Description is 0, comments start with 1.
+text           string    The actual text of the comment.
+creator        string    The login name of the comment's author.
+time           datetime  The time (in Bugzilla's timezone) that the comment was
+                         added.
+creation_time  datetime  This is exactly same as the ``time`` key. Use this
+                         field instead of ``time`` for consistency with other
+                         methods including :ref:`rest_single_bug` and
+                         :ref:`rest_attachments`.
+
+                         For compatibility, ``time`` is still usable. However,
+                         please note that ``time`` may be deprecated and removed
+                         in a future release.
+
+is_private     boolean   ``true`` if this comment is private (only visible to a
+                         certain group called the "insidergroup"), ``false``
+                         otherwise.
+=============  ========  ========================================================
+
+.. _rest_add_comment:
+
+Create Comments
+---------------
+
+This allows you to add a comment to a bug in Bugzilla.
+
+**Request**
+
+To create a comment on a current bug.
+
+.. code-block:: text
+
+   POST /rest/bug/(id)/comment
+
+.. code-block:: js
+
+   {
+     "ids" : [123,..],
+     "comment" : "This is an additional comment",
+     "is_private" : false
+   }
+
+``ids`` is optional in the data example above and can be used to specify adding
+a comment to more than one bug at the same time.
+
+===========  =======  ===========================================================
+name         type     description
+===========  =======  ===========================================================
+**id**       int      The ID or alias of the bug to append a comment to.
+ids          array    List of integer bug IDs to add the comment to.
+**comment**  string   The comment to append to the bug. If this is empty
+                      or all whitespace, an error will be thrown saying that you
+                      did not set the ``comment`` parameter.
+is_private   boolean  If set to true, the comment is private, otherwise it is
+                      assumed to be public.
+work_time    double   Adds this many hours to the "Hours Worked" on the bug.
+                      If you are not in the time tracking group, this value will
+                      be ignored.
+===========  =======  ===========================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id" : 789
+   }
+
+====  ====  =================================
+name  type  description
+====  ====  =================================
+id    int   ID of the newly-created comment.
+====  ====  =================================
+
+.. _rest_search_comment_tags:
+
+Search Comment Tags
+-------------------
+
+Searches for tags which contain the provided substring.
+
+**Request**
+
+To search for comment tags:
+
+.. code-block:: text
+
+   GET /rest/bug/comment/tags/(query)
+
+Example:
+
+.. code-block:: text
+
+   GET /rest/bug/comment/tags/spa
+
+=========  ======  ====================================================
+name       type    description
+=========  ======  ====================================================
+**query**  string  Only tags containg this substring will be returned.
+limit      int     If provided will return no more than ``limit`` tags.
+                   Defaults to ``10``.
+=========  ======  ====================================================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     "spam"
+   ]
+
+An array of matching tags.
+
+.. _rest_update_comment_tags:
+
+Update Comment Tags
+-------------------
+
+Adds or removes tags from a comment.
+
+**Request**
+
+To update the tags comments attached to a comment:
+
+.. code-block:: text
+
+   PUT /rest/bug/comment/(comment_id)/tags
+
+Example:
+
+.. code-block:: js
+
+   {
+     "comment_id" : 75,
+     "add" : ["spam", "bad"]
+   }
+
+==============  =====  ====================================
+name            type   description
+==============  =====  ====================================
+**comment_id**  int    The ID of the comment to update.
+add             array  The tags to attach to the comment.
+remove          array  The tags to detach from the comment.
+==============  =====  ====================================
+
+**Response**
+
+.. code-block:: js
+
+   [
+     "bad",
+     "spam"
+   ]
+
+An array of strings containing the comment's updated tags.
diff --git a/docs/en/rst/api/core/v1/component.rst b/docs/en/rst/api/core/v1/component.rst
new file mode 100644
index 000000000..aceada1a7
--- /dev/null
+++ b/docs/en/rst/api/core/v1/component.rst
@@ -0,0 +1,65 @@
+Components
+==========
+
+This part of the Bugzilla API allows you to deal with the available product
+components. You will be able to get information about them as well as manipulate
+them.
+
+Create Component
+----------------
+
+This allows you to create a new component in Bugzilla. You must be authenticated
+and be in the *editcomponents* group to perform this action.
+
+**Request**
+
+To create a new component:
+
+.. code-block:: text
+
+   POST /rest/component
+
+.. code-block:: js
+
+   {
+     "product" : "TestProduct",
+     "name" : "New Component",
+     "description" : "This is a new component",
+     "default_assignee" : "dkl@mozilla.com"
+   }
+
+Some params must be set, or an error will be thrown. These params are
+shown in **bold**.
+
+====================  =======  ==================================================
+name                  type     description
+====================  =======  ==================================================
+**name**              string   The name of the new component.
+**product**           string   The name of the product that the component must
+                               be added to. This product must already exist, and
+                               the user have the necessary permissions to edit
+                               components for it.
+**description**       string   The description of the new component.
+**default_assignee**  string   The login name of the default assignee of the
+                               component.
+default_cc            array    Each string representing one login name of the
+                               default CC list.
+default_qa_contact    string   The login name of the default QA contact for the
+                               component.
+is_open               boolean  1 if you want to enable the component for bug
+                               creations. 0 otherwise. Default is 1.
+====================  =======  ==================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id": 27
+   }
+
+====  ====  ========================================
+name  type  description
+====  ====  ========================================
+id    int   The ID of the newly-added component.
+====  ====  ========================================
diff --git a/docs/en/rst/api/core/v1/field.rst b/docs/en/rst/api/core/v1/field.rst
new file mode 100644
index 000000000..d97aa3050
--- /dev/null
+++ b/docs/en/rst/api/core/v1/field.rst
@@ -0,0 +1,240 @@
+Bug Fields
+==========
+
+The Bugzilla API for getting details about bug fields.
+
+.. _rest_fields:
+
+Fields
+------
+
+Get information about valid bug fields, including the lists of legal values
+for each field.
+
+**Request**
+
+To get information about all fields:
+
+.. code-block:: text
+
+   GET /rest/field/bug
+
+To get information related to a single field:
+
+.. code-block:: text
+
+   GET /rest/field/bug/(id_or_name)
+
+==========  =====  ==========================================================
+name        type   description
+==========  =====  ==========================================================
+id_or_name  mixed  An integer field ID or string representing the field name.
+==========  =====  ==========================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "fields": [
+       {
+         "display_name": "Priority",
+         "name": "priority",
+         "type": 2,
+         "is_mandatory": false,
+         "value_field": null,
+         "values": [
+           {
+             "sortkey": 100,
+             "sort_key": 100,
+             "visibility_values": [],
+             "name": "P1"
+           },
+           {
+             "sort_key": 200,
+             "name": "P2",
+             "visibility_values": [],
+             "sortkey": 200
+           },
+           {
+             "sort_key": 300,
+             "visibility_values": [],
+             "name": "P3",
+             "sortkey": 300
+           },
+           {
+             "sort_key": 400,
+             "name": "P4",
+             "visibility_values": [],
+             "sortkey": 400
+           },
+           {
+             "name": "P5",
+             "visibility_values": [],
+             "sort_key": 500,
+             "sortkey": 500
+           }
+         ],
+         "visibility_values": [],
+         "visibility_field": null,
+         "is_on_bug_entry": false,
+         "is_custom": false,
+         "id": 13
+       }
+     ]
+   }
+
+``field`` (array) Field objects each containing the following items:
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+id                 int      An integer ID uniquely identifying this field in this
+                            installation only.
+type               int      The number of the fieldtype. The following values are
+                            defined:
+
+                            * ``0`` Field type unknown
+                            * ``1`` Single-line string field
+                            * ``2`` Single value field
+                            * ``3`` Multiple value field
+                            * ``4`` Multi-line text value
+                            * ``5`` Date field with time
+                            * ``6`` Bug ID field
+                            * ``7`` See Also field
+                            * ``8`` Keywords field
+                            * ``9`` Date field
+                            * ``10`` Integer field
+
+is_custom          boolean  ``true`` when this is a custom field, ``false``
+                            otherwise.
+name               string   The internal name of this field. This is a unique
+                            identifier for this field. If this is not a custom
+                            field, then this name will be the same across all
+                            Bugzilla installations.
+display_name       string   The name of the field, as it is shown in the user
+                            interface.
+is_mandatory       boolean  ``true`` if the field must have a value when filing
+                            new bugs. Also, mandatory fields cannot have their
+                            value cleared when updating bugs.
+is_on_bug_entry    boolean  For custom fields, this is ``true`` if the field is
+                            shown when you enter a new bug. For standard fields,
+                            this is currently always ``false``, even if the field
+                            shows up when entering a bug. (To know whether or not
+                            a standard field is valid on bug entry, see
+                            :ref:`rest_create_bug`.
+visibility_field   string   The name of a field that controls the visibility of
+                            this field in the user interface. This field only
+                            appears in the user interface when the named field is
+                            equal to one of the values is ``visibility_values``.
+                            Can be null.
+visibility_values  array    This field is only shown when ``visibility_field``
+                            matches one of these string values. When
+                            ``visibility_field`` is null, then this is an empty
+                            array.
+value_field        string   The name of the field that controls whether or not
+                            particular values of the field are shown in the user
+                            interface. Can be null.
+values             array    Objects representing the legal values for
+                            select-type (drop-down and multiple-selection)
+                            fields. This is  also populated for the
+                            ``component``, ``version``, ``target_milestone``,
+                            and ``keywords`` fields, but not for the ``product``
+                            field (you must use ``get_accessible_products`` for
+                            that). For fields that aren't select-type fields,
+                            this will simply be an empty array. Each object
+                            contains the items described in the Value object
+                            below.
+=================  =======  =====================================================
+
+Value object:
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+name               string   The actual value--this is what you would specify for
+                            this field in ``create``, etc.
+sort_key           int      Values, when displayed in a list, are sorted first by
+                            this integer and then secondly by their name.
+visibility_values  array    If ``value_field`` is defined for this field, then
+                            this value is only shown if the ``value_field`` is
+                            set to one of the values listed in this array. Note
+                            that for per-product fields, ``value_field`` is set
+                            to ``product`` and ``visibility_values`` will reflect
+                            which product(s) this value appears in.
+is_active          boolean  This value is defined only for certain
+                            product-specific fields such as version,
+                            target_milestone or component. When true, the value
+                            is active; otherwise the value is not active.
+description        string   The description of the value. This item is only
+                            included for the ``keywords`` field.
+is_open            boolean  For ``bug_status`` values, determines whether this
+                            status specifies that the bug is "open" (``true``)
+                            or "closed" (``false``). This item is only included
+                            for the ``bug_status`` field.
+can_change_to      array    For ``bug_status`` values, this is an array of
+                            objects that determine which statuses you can
+                            transition to from this status. (This item is only
+                            included for the ``bug_status`` field.)
+
+                            Each object contains the following items:
+
+                            * name: (string) The name of the new status
+                            * comment_required: (boolean) ``true`` if a comment
+                              is required when you change a bug into this status
+                              using this transition.
+=================  =======  =====================================================
+
+.. _rest_legal_values:
+
+Legal Values
+------------
+
+**DEPRECATED** Use ''Fields'' instead.
+
+Tells you what values are allowed for a particular field.
+
+**Request**
+
+To get information on the values for a field based on field name:
+
+.. code-block:: text
+
+   GET /rest/field/bug/(field)/values
+
+To get information based on field name and a specific product:
+
+.. code-block:: text
+
+   GET /rest/field/bug/(field)/(product_id)/values
+
+==========  ======  =============================================================
+name        type    description
+==========  ======  =============================================================
+field       string  The name of the field you want information about.
+                    This should be the same as the name you would use in
+                    :ref:`rest_create_bug`, below.
+product_id  int     If you're picking a product-specific field, you have to
+                    specify the ID of the product you want the values for.
+==========  ======  =============================================================
+
+**Resppnse**
+
+.. code-block:: js
+
+   {
+     "values": [
+       "P1",
+       "P2",
+       "P3",
+       "P4",
+       "P5"
+     ]
+   }
+
+==========  ======  =============================================================
+name        type    description
+==========  ======  =============================================================
+values      array   The legal values for this field. The values will be sorted
+                    as they normally would be in Bugzilla.
+==========  ======  =============================================================
diff --git a/docs/en/rst/api/core/v1/flagtype.rst b/docs/en/rst/api/core/v1/flagtype.rst
new file mode 100644
index 000000000..994ac27c8
--- /dev/null
+++ b/docs/en/rst/api/core/v1/flagtype.rst
@@ -0,0 +1,373 @@
+Flag Types
+==========
+
+This part of the Bugzilla API allows you to get and create bug and attachment
+flags.
+
+.. _rest_flagtype_get:
+
+Get Flag Type
+-------------
+
+Get information about valid flag types that can be set for bugs and attachments.
+
+**Request**
+
+To get information about all flag types for a product:
+
+.. code-block:: text
+
+   GET /rest/flag_type/(product)
+
+To get information about flag_types for a product and component:
+
+.. code-block:: text
+
+   GET /rest/flag_type/(product)/(component)
+
+.. code-block:: js
+
+   {
+     "bug": [
+       {
+         "is_multiplicable": false,
+         "is_requesteeble": false,
+         "values": [
+           "X",
+           "?",
+           "+",
+           "-"
+         ],
+         "id": 11,
+         "type": "bug",
+         "is_active": true,
+         "description": "Blocks the next release",
+         "name": "blocker"
+       },
+       {
+         "is_requesteeble": false,
+         "is_multiplicable": false,
+         "is_active": true,
+         "description": "Regression found?",
+         "name": "regression",
+         "id": 10,
+         "type": "bug",
+         "values": [
+           "X",
+           "?",
+           "+",
+           "-"
+         ]
+       },
+     ],
+     "attachment": [
+       {
+         "is_requesteeble": true,
+         "is_multiplicable": true,
+         "name": "review",
+         "is_active": true,
+         "description": "Review the patch for correctness and applicability to the problem.",
+         "type": "attachment",
+         "id": 1,
+         "values": [
+           "X",
+           "?",
+           "+",
+           "-"
+         ]
+       },
+       {
+         "name": "approval",
+         "description": "Approve the patch for check-in to the tree.",
+         "is_active": true,
+         "values": [
+           "X",
+           "?",
+           "+",
+           "-"
+         ],
+         "type": "attachment",
+         "id": 3,
+         "is_multiplicable": false,
+         "is_requesteeble": false
+       }
+     ]
+   }
+
+You must pass a product name and an optional component name. If the product or
+component names contains a ``/`` character, up will need to url encode it.
+
+===========  ======  ============================================================
+name         type    description
+===========  ======  ============================================================
+**product**  string  The name of a valid product.
+component    string  An optional valid component name associated with the
+                     product.
+===========  ======  ============================================================
+
+**Response**
+
+An object containing two items, ``bug`` and ``attachment``. Each value is an
+array of objects, containing the following items:
+
+================  =======  ======================================================
+name              type     description
+================  =======  ======================================================
+id                int      An integer ID uniquely identifying this flag type.
+name              string   The name for the flag type.
+type              string   The target of the flag type which is either ``bug``
+                           or ``attachment``.
+description       string   The description of the flag type.
+values            array    String values that the user can set on the flag type.
+is_requesteeble   boolean  Users can ask specific other users to set flags of
+                           this type.
+is_multiplicable  boolean  Multiple flags of this type can be set for the same
+                           bug or attachment.
+================  =======  ======================================================
+
+Create Flag Type
+----------------
+
+Create a new flag type. You must be authenticated and be in the *editcomponents*
+group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+   POST /rest/flag_type
+
+.. code-block:: js
+
+   {
+     "name" : "feedback",
+     "description" : "This attachment needs feedback",
+     "inclusions" : [ "WorldControl "],
+     "target_type" : "attachment"
+   }
+
+Some params must be set, or an error will be thrown. The required params are
+marked in **bold**.
+
+===========================  =======  ===========================================
+name                         type     description
+===========================  =======  ===========================================
+**name**                     string   The name of the new flag type.
+**description**              string   A description for the flag type.
+target_type                  string   The new flag is either for a ``bug`` or an
+                                      ``attachment``.
+inclusions                   array    An array of strings or an object containing
+                                      product names, and optionally component
+                                      names. If you provide a string, the flag
+                                      type will be shown on all bugs in that
+                                      product. If you provide an object, the key
+                                      represents the product name, and the value
+                                      is the components of the product to be
+                                      included.
+exclusions                   array    An array of strings or an object containing
+                                      product names. This uses the same format as
+                                      ``inclusions``. This will exclude the flag
+                                      from all products and components specified.
+sortkey                      int      A number between 1 and 32767 by which this
+                                      type will be sorted when displayed to users
+                                      in a list; ignore if you don't care what
+                                      order the types appear in or if you want
+                                      them to appear in alphabetical order.
+is_active                    boolean  Flag of this type appear in the UI and can
+                                      be set. Default is ``true``.
+is_requestable               boolean  Users can ask for flags of this type to be
+                                      set. Default is ``true``.
+cc_list                      array    If the flag type is requestable, who should
+                                      receive e-mail notification of requests.
+                                      This is an array of e-mail addresses which\
+                                      do not need to be Bugzilla logins.
+is_specifically_requestable  boolean  Users can ask specific other users to
+                                      set flags of this type as opposed to just
+                                      asking the wind. Default is ``true``.
+is_multiplicable             boolean  Multiple flags of this type can be set on
+                                      the same bug. Default is ``true``.
+grant_group                  string   The group allowed to grant/deny flags of
+                                      this type (to allow all users to grant/deny
+                                      these flags, select no group). Default is
+                                      no group.
+request_group                string   If flags of this type are requestable, the
+                                      group allowed to request them (to allow all
+                                      users to request these flags, select no
+                                      group). Note that the request group alone
+                                      has no effect if the grant group is not
+                                      defined! Default is no group.
+===========================  =======  ===========================================
+
+An example for ``inclusions`` and/or ``exclusions``:
+
+.. code-block:: js
+
+   [
+     "FooProduct"
+   ]
+
+   {
+     "BarProduct" : [ "C1", "C3" ],
+     "BazProduct" : [ "C7" ]
+   }
+
+This flag will be added to **all** components of ``FooProduct``, components C1
+and C3 of ``BarProduct``, and C7 of ``BazProduct``.
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id": 13
+   }
+
+=======  ====  ==============================================
+name     type  description
+=======  ====  ==============================================
+flag_id  int   ID of the new FlagType object is returned.
+=======  ====  ==============================================
+
+.. _rest_flagtype_update:
+
+Update Flag Type
+----------------
+
+This allows you to update a flag type in Bugzilla. You must be authenticated
+and be in the *editcomponents* group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+   PUT /rest/flag_type/(id_or_name)
+
+.. code-block:: js
+
+   {
+     "ids" : [13],
+     "name" : "feedback-new",
+     "is_requestable" : false
+   }
+
+You can edit a single flag type by passing the ID or name of the flag type
+in the URL. To edit more than one flag type, you can specify addition IDs or
+flag type names using the ``ids`` or ``names`` parameters respectively.
+
+One of the below must be specified.
+
+==============  =====  ==========================================================
+name            type   description
+==============  =====  ==========================================================
+**id_or_name**  mixed  Integer flag type ID or name.
+**ids**         array  Numeric IDs of the flag types that you wish to update.
+**names**       array  Names of the flag types that you wish to update. If many
+                       flag types have the same name, this will change **all**
+                       of them.
+==============  =====  ==========================================================
+
+The following parameters specify the new values you want to set for the flag
+types you are updating.
+
+===========================  =======  ===========================================
+name                         type     description
+===========================  =======  ===========================================
+name                         string   A short name identifying this type.
+description                  string   A comprehensive description of this type.
+inclusions                   array    An array of strings or an object containing
+                                      product names, and optionally component
+                                      names. If you provide a string, the flag
+                                      type will be shown on all bugs in that
+                                      product. If you provide an object, the key
+                                      represents the product name, and the value
+                                      is the components of the product to be
+                                      included.
+exclusions                   array    An array of strings or an object containing
+                                      product names. This uses the same format as
+                                      ``inclusions``. This will exclude the flag
+                                      from all products and components specified.
+sortkey                      int      A number between 1 and 32767 by which this
+                                      type will be sorted when displayed to users
+                                      in a list; ignore if you don't care what
+                                      order the types appear in or if you want
+                                      them to appear in alphabetical order.
+is_active                    boolean  Flag of this type appear in the UI and can
+                                      be set.
+is_requestable               boolean  Users can ask for flags of this type to be
+                                      set.
+cc_list                      array    If the flag type is requestable, who should
+                                      receive e-mail notification of requests.
+                                      This is an array of e-mail addresses
+                                      which do not need to be Bugzilla logins.
+is_specifically_requestable  boolean  Users can ask specific other users to set
+                                      flags of this type as opposed to just
+                                      asking the wind.
+is_multiplicable             boolean  Multiple flags of this type can be set on
+                                      the same bug.
+grant_group                  string   The group allowed to grant/deny flags of
+                                      this type (to allow all users to grant/deny
+                                      these flags, select no group).
+request_group                string   If flags of this type are requestable, the
+                                      group allowed to request them (to allow all
+                                      users to request these flags, select no
+                                      group). Note that the request group alone
+                                      has no effect if the grant group is not
+                                      defined!
+===========================  =======  ===========================================
+
+An example for ``inclusions`` and/or ``exclusions``:
+
+.. code-block:: js
+
+   [
+     "FooProduct",
+   ]
+
+   {
+     "BarProduct" : [ "C1", "C3" ],
+     "BazProduct" : [ "C7" ]
+   }
+
+This flag will be added to **all** components of ``FooProduct``,
+components C1 and C3 of ``BarProduct``, and C7 of ``BazProduct``.
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "flagtypes": [
+       {
+         "name": "feedback-new",
+         "changes": {
+           "is_requestable": {
+             "added": "0",
+             "removed": "1"
+           },
+           "name": {
+             "removed": "feedback",
+             "added": "feedback-new"
+           }
+         },
+         "id": 13
+       }
+     ]
+   }
+
+``flagtypes`` (array) Flag change objects containing the following items:
+
+=======  ======  ================================================================
+name     type    description
+=======  ======  ================================================================
+id       int     The ID of the flag type that was updated.
+name     string  The name of the flag type that was updated.
+changes  object  The changes that were actually done on this flag type.
+                 The keys are the names of the fields that were changed, and the
+                 values are an object with two items:
+
+                 * added: (string) The value that this field was changed to.
+                 * removed: (string) The value that was previously set in this
+                   field.
+=======  ======  ================================================================
+
+Booleans changes will be represented with the strings '1' and '0'.
diff --git a/docs/en/rst/api/core/v1/general.rst b/docs/en/rst/api/core/v1/general.rst
new file mode 100644
index 000000000..06ef5b2fb
--- /dev/null
+++ b/docs/en/rst/api/core/v1/general.rst
@@ -0,0 +1,255 @@
+General
+=======
+
+This is the standard REST API for external programs that want to interact
+with Bugzilla. It provides a REST interface to various Bugzilla functions.
+
+Basic Information
+-----------------
+
+**Browsing**
+
+If the ``Accept`` header of a request is set to ``text/html`` (as it is by an
+ordinary web browser) then the API will return the JSON data as a HTML
+page which the browser can display. In other words, you can play with the
+API using just your browser to see results in a human-readable form.
+This is a good way to try out the various GET calls, even if you can't use
+it for POST or PUT.
+
+**Data Format**
+
+The REST API only supports JSON input, and either JSON or JSONP output.
+So objects sent and received must be in JSON format.
+
+On every request, you must set both the ``Accept`` and ``Content-Type`` HTTP
+headers to the MIME type of the data format you are using to communicate with
+the API. ``Content-Type`` tells the API how to interpret your request, and
+``Accept`` tells it how you want your data back. ``Content-Type`` must be
+``application/json``. ``Accept`` can be either that, or
+``application/javascript`` for JSONP. In the latter`case, add a ``callback``
+parameter to name your callback.
+
+Parameters may also be passed in as part of the query string for non-GET
+requests and will override any matching parameters in the request body.
+
+Example request which returns the current version of Bugzilla:
+
+.. code-block:: http
+
+   GET /rest/version HTTP/1.1
+   Host: bugzilla.example.com
+   Accept: application/json
+
+Example response:
+
+.. code-block:: http
+
+   HTTP/1.1 200 OK
+   Vary: Accept
+   Content-Type: application/json
+
+   {
+     "version" : "4.2.9+"
+   }
+
+**Errors**
+
+When an error occurs over REST, an object is returned with the key ``error``
+set to ``true``.
+
+The error contents look similar to:
+
+.. code-block:: js
+
+   {
+     "error": true,
+     "message": "Some message here",
+     "code": 123
+   }
+
+Common Data Types
+-----------------
+
+The Bugzilla API uses the following various types of parameters:
+
+========  ======================================================================
+ type     description
+========  ======================================================================
+int       Integer.
+double    A floating-point number.
+string    A string.
+email     A string representing an email address. This value, when returned,
+          may be filtered based on if the user is logged in or not.
+date      A specific date. Example format: ``YYYY-MM-DD``.
+datetime  A date/time. Timezone should be in UTC unless otherwise noted.
+          Example format: ``YYYY-MM-DDTHH24:MI:SSZ``.
+boolean   ``true`` or ``false``.
+base64    A base64-encoded string. This is the only way to transfer
+          binary data via the API.
+array     An array. There may be mixed types in an array. ``[`` and ``]`` are
+          used to represent the beginning and end of arrays.
+object    A mapping of keys to values. Called a "hash", "dict", or "map" in
+          some other programming languages. The keys are strings, and the
+          values can be any type. ``{`` and ``}`` are used to represent the
+          beginning and end of objects.
+========  ======================================================================
+
+Parameters that are required will be displayed in **bold** in the parameters
+table for each API method.
+
+Authentication
+--------------
+
+Some methods do not require you to log in. An example of this is
+:ref:`rest_single_bug`. However, authenticating yourself allows you to see
+non-public information, for example, a bug that is not publicly visible.
+
+There are two ways to authenticate yourself:
+
+**API Keys**
+
+You can specify ``Bugzilla_api_key`` or simply ``api_key`` as an argument to
+any call, and you will be logged in as that user if the key is correct and has
+not been revoked. You can set up an API key by using the 'API Key' tab in the
+Preferences pages.
+
+**Login and Password**
+
+You can specify ``Bugzilla_login`` and ``Bugzilla_password`` or simply
+``login`` and ``password`` respectively, as arguments to any call, and you will
+be logged in as that user if your credentials are correct.
+
+======================  =======  ==============================================
+name                    type     description
+======================  =======  ==============================================
+**Bugzilla_login**      string   A user's login name.
+**Bugzilla_password**   string   That user's password.
+Bugzilla_restrictlogin  boolean  If true, then your login will only be
+                                 valid for your IP address.
+======================  =======  ==============================================
+
+The ``Bugzilla_restrictlogin`` option is only used when you have also
+specified ``Bugzilla_login`` and ``Bugzilla_password``.
+
+There is also a deprecated method of authentication described below that will be
+removed in the version after Bugzilla 5.0.
+
+**Bugzilla Tokens**
+
+You can use :ref:`rest_user_login` to log in as a Bugzilla user. This issues a
+token that you must then use in future calls. Just use the value for ``token``
+and pass as either ``Bugzilla_token`` or simply ``token`` as arguments to an
+API call.
+
+==================  ======  ===================================================
+name                type    description
+==================  ======  ===================================================
+**Bugzilla_token**  string  You can specify this as argument to any call,
+                            and you will be logged in as that user if the
+                            token is correct. This is the token returned
+                            when calling :ref:`rest_user_login` mentioned
+                            above.
+==================  ======  ===================================================
+
+An error is thrown if you pass an invalid token; you will need to log in again
+to get a new token.
+
+Also starting with Bugzilla 5.0, login cookies are no longer returned by
+:ref:`rest_user_login` due to security concerns.
+
+Useful Parameters
+-----------------
+
+Many calls take common arguments. These are documented below and linked from
+the individual calls where these parameters are used.
+
+**Including Fields**
+
+Many calls return an array of objects with various fields in the objects. (For
+example, :ref:`rest_single_bug` returns a list of ``bugs`` that have fields like
+``id``, ``summary``,  ``creation_time``, etc.)
+
+These parameters allow you to limit what fields are present in the objects, to
+improve performance or save some bandwidth.
+
+``include_fields``: The (case-sensitive) names of fields in the response data.
+Only the fields specified in the object will be returned, the rest will not be
+included. Fields should be comma delimited.
+
+Invalid field names are ignored.
+
+Example request to :ref:`rest_user_get`:
+
+.. code-block:: text
+
+   GET /rest/user/1?include_fields=id,name
+
+would return something like:
+
+.. code-block:: js
+
+   {
+     "users" : [
+       {
+         "id" : 1,
+         "name" : "user@domain.com"
+       }
+     ]
+   }
+
+**Excluding Fields**
+
+``exclude_fields``: The (case-sensitive) names of fields in the return value. The\
+fields specified will not be included in the returned hashes. Fields should
+be comma delimited.
+
+Invalid field names are ignored.
+
+Specifying fields here overrides ``include_fields``, so if you specify a
+field in both, it will be excluded, not included.
+
+Example request to :ref:`rest_user_get`:
+
+.. code-block:: js
+
+   GET /rest/user/1?exclude_fields=name
+
+would return something like:
+
+.. code-block:: js
+
+   {
+     "users" : [
+       {
+         "id" : 1,
+         "real_name" : "John Smith"
+       }
+     ]
+   }
+
+Some calls support specifying "subfields". If a call states that it supports
+"subfield" restrictions, you can restrict what information is returned within
+the first field. For example, if you call :ref:`rest_product_get` with an
+``include_fields`` of ``components.name``, then only the component name would be
+returned (and nothing else). You can include the main field, and exclude a
+subfield.
+
+There are several shortcut identifiers to ask for only certain groups of
+fields to be returned or excluded:
+
+=========  =====================================================================
+value      description
+=========  =====================================================================
+_all       All possible fields are returned if this is specified in
+           ``include_fields``.
+_default   Default fields are returned if ``include_fields`` is empty or
+           this is specified. This is useful if you want the default
+           fields in addition to a field that is not normally returned.
+_extra     Extra fields are not returned by default and need to be manually
+           specified in ``include_fields`` either by exact field name, or adding
+           ``_extra``.
+ _custom   Custom fields are normally returned by default unless this is added
+           to ``exclude_fields``. Also you can use it in ``include_fields`` if
+           for example you want specific field names plus all custom fields.
+           Custom fields are normally only relevant to bug objects.
+=========  =====================================================================
diff --git a/docs/en/rst/api/core/v1/group.rst b/docs/en/rst/api/core/v1/group.rst
new file mode 100644
index 000000000..e2c595240
--- /dev/null
+++ b/docs/en/rst/api/core/v1/group.rst
@@ -0,0 +1,278 @@
+Groups
+======
+
+The API for creating, changing, and getting information about groups.
+
+.. _rest_group_create:
+
+Create Group
+------------
+
+This allows you to create a new group in Bugzilla. You must be authenticated and
+be in the *creategroups* group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+   POST /rest/group
+
+.. code-block:: js
+
+   {
+     "name" : "secret-group",
+     "description" : "Too secret for you!",
+     "is_active" : true
+   }
+
+Some params must be set, or an error will be thrown. The required params are
+marked in **bold**.
+
+===============  =======  =======================================================
+name             type     description
+===============  =======  =======================================================
+**name**         string   A short name for this group. Must be unique. This
+                          is not usually displayed in the user interface, except
+                          in a few places.
+**description**  string   A human-readable name for this group. Should be
+                          relatively short. This is what will normally appear in
+                          the UI as the name of the group.
+user_regexp      string   A regular expression. Any user whose Bugzilla username
+                          matches this regular expression will automatically be
+                          granted membership in this group.
+is_active        boolean  ``true`` if new group can be used for bugs, ``false``
+                          if this is a group that will only contain users and no
+                          bugs will be restricted to it.
+icon_url         string   A URL pointing to a small icon used to identify the
+                          group. This icon will show up next to users' names in
+                          various parts of Bugzilla if they are in this group.
+===============  =======  =======================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id": 22
+   }
+
+====  ====  ==============================
+name  type  description
+====  ====  ==============================
+id    int   ID of the newly-created group.
+====  ====  ==============================
+
+.. _rest_group_update:
+
+Update Group
+------------
+
+This allows you to update a group in Bugzilla. You must be authenticated and be
+in the *creategroups* group to perform this action.
+
+**Request**
+
+To update a group using the group ID or name:
+
+.. code-block:: text
+
+   PUT /rest/group/(id_or_name)
+
+.. code-block:: js
+
+   {
+     "name" : "secret-group",
+     "description" : "Too secret for you! (updated description)",
+     "is_active" : false
+   }
+
+You can edit a single group by passing the ID or name of the group
+in the URL. To edit more than one group, you can specify addition IDs or
+group names using the ``ids`` or ``names`` parameters respectively.
+
+One of the below must be specified.
+
+==============  =====  ==========================================================
+name            type   description
+==============  =====  ==========================================================
+**id_or_name**  mixed  Integer group or name.
+**ids**         array  IDs of groups to update.
+**names**       array  Names of groups to update.
+==============  =====  ==========================================================
+
+The following parameters specify the new values you want to set for the group(s)
+you are updating.
+
+===========  =======  ===========================================================
+name         type     description
+===========  =======  ===========================================================
+name         string   A new name for the groups. If you try to set this while
+                      updating more than one group, an error will occur, as
+                      group names must be unique.
+description  string   A new description for the groups. This is what will appear
+                      in the UI as the name of the groups.
+user_regexp  string   A new regular expression for email. Will automatically
+                      grant membership to these groups to anyone with an email
+                      address that matches this perl regular expression.
+is_active    boolean  Set if groups are active and eligible to be used for bugs.
+                      ``true`` if bugs can be restricted to this group, ``false``
+                      otherwise.
+icon_url     string   A URL pointing to an icon that will appear next to the name
+                      of users who are in this group.
+===========  =======  ===========================================================
+
+**Response**
+
+.. code-block:: js
+
+  {
+    "groups": [
+      {
+        "changes": {
+          "description": {
+            "added": "Too secret for you! (updated description)",
+            "removed": "Too secret for you!"
+          },
+          "is_active": {
+            "removed": "1",
+            "added": "0"
+          }
+        },
+        "id": "22"
+      }
+    ]
+  }
+
+``groups`` (array) Group change objects, each containing the following items:
+
+=======  ======  ================================================================
+name     type    description
+=======  ======  ================================================================
+id       int     The ID of the group that was updated.
+changes  object  The changes that were actually done on this group. The
+                 keys are the names of the fields that were changed, and the
+                 values are an object with two items:
+
+                 * added: (string) The values that were added to this field,
+                   possibly a comma-and-space-separated list if multiple values
+                   were added.
+                 * removed: (string) The values that were removed from this
+                   field, possibly a comma-and-space-separated list if multiple
+                   values were removed.
+=======  ======  ================================================================
+
+.. _rest_group_get:
+
+Get Group
+---------
+
+Returns information about Bugzilla groups.
+
+**Request**
+
+To return information about a specific group ID or name:
+
+.. code-block:: text
+
+   GET /rest/group/(id_or_name)
+
+You can also return information about more than one specific group by using the
+following in your query string:
+
+.. code-block:: text
+
+   GET /rest/group?ids=1&ids=2&ids=3
+   GET /group?names=ProductOne&names=Product2
+
+If neither IDs nor names are passed, and you are in the creategroups or
+editusers group, then all groups will be retrieved. Otherwise, only groups
+that you have bless privileges for will be returned.
+
+==========  =======  ============================================================
+name        type     description
+==========  =======  ============================================================
+id_or_name  mixed    Integer group ID or name.
+ids         array    Integer IDs of groups.
+names       array    Names of groups.
+membership  boolean  Set to 1 then a list of members of the passed groups names
+                     and IDs will be returned.
+==========  =======  ============================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "groups": [
+       {
+         "membership": [
+           {
+             "real_name": "Bugzilla User",
+             "can_login": true,
+             "name": "user@bugzilla.org",
+             "login_denied_text": "",
+             "id": 85,
+             "email_enabled": false,
+             "email": "user@bugzilla.org"
+           },
+         ],
+         "is_active": true,
+         "description": "Test Group",
+         "user_regexp": "",
+         "is_bug_group": true,
+         "name": "TestGroup",
+         "id": 9
+       }
+     ]
+   }
+
+If the user is a member of the *creategroups* group they will receive
+information about all groups or groups matching the criteria that they passed.
+You have to be in the creategroups group unless you're requesting membership
+information.
+
+If the user is not a member of the *creategroups* group, but they are in the
+"editusers" group or have bless privileges to the groups they require
+membership information for, the is_active, is_bug_group and user_regexp values
+are not supplied.
+
+The return value will be an object containing group names as the keys; each
+value will be an object that describes the group and has the following items:
+
+============  ======  ===========================================================
+name          type    description
+============  ======  ===========================================================
+id            int     The unique integer ID that Bugzilla uses to identify this
+                      group. Even if the name of the group changes, this ID will
+                      stay the same.
+name          string  The name of the group.
+description   string  The description of the group.
+is_bug_group  int     Whether this group is to be used for bug reports or is
+                      only administrative specific.
+user_regexp   string  A regular expression that allows users to be added to
+                      this group if their login matches.
+is_active     int     Whether this group is currently active or not.
+users         array   User objects that are members of this group; only
+                      returned if the user sets the ``membership`` parameter to
+                      1. Each user object has the items describe in the User
+                      object below.
+============  ======  ===========================================================
+
+User object:
+
+=============  =======  =========================================================
+name           type     description
+=============  =======  =========================================================
+id             int      The ID of the user.
+real_name      string   The actual name of the user.
+email          string   The email address of the user.
+name           string   The login name of the user. Note that in some situations
+                        this is different than their email.
+can_login      boolean  A boolean value to indicate if the user can login into
+                        bugzilla.
+email_enabled  boolean  A boolean value to indicate if bug-related mail will
+                        be sent to the user or not.
+disabled_text  string   A text field that holds the reason for disabling a user
+                        from logging into Bugzilla. If empty, then the user
+                        account is enabled; otherwise it is disabled/closed.
+=============  =======  =========================================================
diff --git a/docs/en/rst/api/core/v1/index.rst b/docs/en/rst/api/core/v1/index.rst
new file mode 100644
index 000000000..933aeed96
--- /dev/null
+++ b/docs/en/rst/api/core/v1/index.rst
@@ -0,0 +1,18 @@
+Core API v1
+===========
+
+.. toctree::
+
+   general
+   attachment
+   bug
+   bug-user-last-visit
+   bugzilla
+   classification
+   comment
+   component
+   field
+   flagtype
+   group
+   product
+   user
diff --git a/docs/en/rst/api/core/v1/product.rst b/docs/en/rst/api/core/v1/product.rst
new file mode 100644
index 000000000..95726a3a8
--- /dev/null
+++ b/docs/en/rst/api/core/v1/product.rst
@@ -0,0 +1,416 @@
+Products
+========
+
+This part of the Bugzilla API allows you to list the available products and
+get information about them.
+
+.. _rest_product_list:
+
+List Products
+-------------
+
+Returns a list of the IDs of the products the user can search on.
+
+**Request**
+
+To get a list of product IDs a user can select such as for querying bugs:
+
+.. code-block:: text
+
+   GET /rest/product_selectable
+
+To get a list of product IDs a user can enter a bug against:
+
+.. code-block:: text
+
+   GET /rest/product_enterable
+
+To get a list of product IDs a user can search or enter bugs against.
+
+.. code-block:: text
+
+   GET /rest/product_accessible
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "ids": [
+       "2",
+       "3",
+       "19",
+       "1",
+       "4"
+     ]
+   }
+
+====  =====  ======================================
+name  type   description
+====  =====  ======================================
+ids   array  List of integer product IDs.
+====  =====  ======================================
+
+.. _rest_product_get:
+
+Get Product
+-----------
+
+Returns a list of information about the products passed to it.
+
+**Request**
+
+To return information about a specific type of products such as
+``accessible``, ``selectable``, or ``enterable``:
+
+.. code-block:: text
+
+   GET /rest/product?type=accessible
+
+To return information about a specific product by ``id`` or ``name``:
+
+.. code-block:: text
+
+   GET /rest/product/(id_or_name)
+
+You can also return information about more than one product by using the
+following parameters in your query string:
+
+.. code-block:: text
+
+   GET /rest/product?ids=1&ids=2&ids=3
+   GET /rest/product?names=ProductOne&names=Product2
+
+==========  ======  =============================================================
+name        type    description
+==========  ======  =============================================================
+id_or_name  mixed   Integer product ID or product name.
+ids         array   Product IDs
+names       array   Product names
+type        string  The group of products to return. Valid values are
+                    ``accessible`` (default), ``selectable``, and ``enterable``.
+                    ``type`` can be a single value or an array of values if more
+                    than one group is needed with duplicates removed.
+==========  ======  =============================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "products": [
+       {
+         "id": 1,
+         "default_milestone": "---",
+         "components": [
+           {
+             "is_active": true,
+             "default_assigned_to": "admin@bugzilla.org",
+             "id": 1,
+             "sort_key": 0,
+             "name": "TestComponent",
+             "flag_types": {
+               "bug": [
+                 {
+                   "is_active": true,
+                   "grant_group": null,
+                   "cc_list": "",
+                   "is_requestable": true,
+                   "id": 3,
+                   "is_multiplicable": true,
+                   "name": "needinfo",
+                   "request_group": null,
+                   "is_requesteeble": true,
+                   "sort_key": 0,
+                   "description": "needinfo"
+                 }
+               ],
+               "attachment": [
+                 {
+                   "description": "Review",
+                   "is_multiplicable": true,
+                   "name": "review",
+                   "is_requesteeble": true,
+                   "request_group": null,
+                   "sort_key": 0,
+                   "cc_list": "",
+                   "grant_group": null,
+                   "is_requestable": true,
+                   "id": 2,
+                   "is_active": true
+                 }
+               ]
+             },
+             "default_qa_contact": "",
+             "description": "This is a test component."
+           }
+         ],
+         "is_active": true,
+         "classification": "Unclassified",
+         "versions": [
+           {
+             "id": 1,
+             "name": "unspecified",
+             "is_active": true,
+             "sort_key": 0
+           }
+         ],
+         "description": "This is a test product.",
+         "has_unconfirmed": true,
+         "milestones": [
+           {
+             "name": "---",
+             "is_active": true,
+             "sort_key": 0,
+             "id": 1
+           }
+         ],
+         "name": "TestProduct"
+       }
+     ]
+   }
+
+``products`` (array) Each product object has the following items:
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+id                 int      An integer ID uniquely identifying the product in
+                            this installation only.
+name               string   The name of the product. This is a unique identifier
+                            for the product.
+description        string   A description of the product, which may contain HTML.
+is_active          boolean  A boolean indicating if the product is active.
+default_milestone  string   The name of the default milestone for the product.
+has_unconfirmed    boolean  Indicates whether the UNCONFIRMED bug status is
+                            available for this product.
+classification     string   The classification name for the product.
+components         array    Each component object has the items described in the
+                            Component object below.
+versions           array    Each object describes a version, and has the
+                            following items: ``name``, ``sort_key`` and
+                            ``is_active``.
+milestones         array    Each object describes a milestone, and has the
+                            following items: ``name``, ``sort_key`` and
+                            ``is_active``.
+=================  =======  =====================================================
+
+If the user tries to access a product that is not in the list of accessible
+products for the user, or a product that does not exist, that is silently
+ignored, and no information about that product is returned.
+
+Component object:
+
+===================  =======  ===================================================
+name                 type     description
+===================  =======  ===================================================
+id                   int      An integer ID uniquely identifying the component in
+                              this installation only.
+name                 string   The name of the component.  This is a unique
+                              identifier for this component.
+description          string   A description of the component, which may contain
+                              HTML.
+default_assigned_to  string   The login name of the user to whom new bugs
+                              will be assigned by default.
+default_qa_contact   string   The login name of the user who will be set as
+                              the QA Contact for new bugs by default. Empty
+                              string if the QA contact is not defined.
+sort_key             int      Components, when displayed in a list, are sorted
+                              first by this integer and then secondly by their
+                              name.
+is_active            boolean  A boolean indicating if the component is active.
+                              Inactive components are not enabled for new bugs.
+flag_types           object   An object containing two items ``bug`` and
+                              ``attachment`` that each contains an array of
+                              objects, where each describes a flagtype. The
+                              flagtype items are described in the Flagtype
+                              object below.
+===================  =======  ===================================================
+
+Flagtype object:
+
+================  =======  ======================================================
+name              type     description
+================  =======  ======================================================
+id                int      Returns the ID of the flagtype.
+name              string   Returns the name of the flagtype.
+description       string   Returns the description of the flagtype.
+cc_list           string   Returns the concatenated CC list for the flagtype, as
+                           a single string.
+sort_key          int      Returns the sortkey of the flagtype.
+is_active         boolean  Returns whether the flagtype is active or disabled.
+                           Flags being in a disabled flagtype are not deleted.
+                           It only prevents you from adding new flags to it.
+is_requestable    boolean  Returns whether you can request for the given
+                           flagtype (i.e. whether the '?' flag is available or
+                           not).
+is_requesteeble   boolean  Returns whether you can ask someone specifically
+                           or not.
+is_multiplicable  boolean  Returns whether you can have more than one
+                           flag for the given flagtype in a given bug/attachment.
+grant_group       int      the group ID that is allowed to grant/deny flags of
+                           this type. If the item is not included all users are
+                           allowed to grant/deny this flagtype.
+request_group     int      The group ID that is allowed to request the flag if
+                           the flag is of the type requestable. If the item is
+                           not included all users are allowed request this
+                           flagtype.
+================  =======  ======================================================
+
+.. _rest_product_create:
+
+Create Product
+--------------
+
+This allows you to create a new product in Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+   POST /rest/product
+
+.. code-block:: js
+
+   {
+     "name" : "AnotherProduct",
+     "description" : "Another Product",
+     "classification" : "Unclassified",
+     "is_open" : false,
+     "has_unconfirmed" : false,
+     "version" : "unspecified"
+   }
+
+Some params must be set, or an error will be thrown. The required params are
+marked in bold.
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+**name**           string   The name of this product. Must be globally unique
+                            within Bugzilla.
+**description**    string   A description for this product. Allows some simple
+                            HTML.
+**version**        string   The default version for this product.
+has_unconfirmed    boolean  Allow the UNCONFIRMED status to be set on bugs in
+                            this product. Default: true.
+classification     string   The name of the Classification which contains this
+                            product.
+default_milestone  string   The default milestone for this product. Default
+                            '---'.
+is_open            boolean  ``true`` if the product is currently allowing bugs
+                            to be entered into it. Default: ``true``.
+create_series      boolean  ``true`` if you want series for New Charts to be
+                            created for this new product. Default: ``true``.
+=================  =======  =====================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id": 20
+   }
+
+Returns an object with the following items:
+
+====  ====  =====================================
+name  type  description
+====  ====  =====================================
+id    int   ID of the newly-filed product.
+====  ====  =====================================
+
+.. _rest_product_update:
+
+Update Product
+--------------
+
+This allows you to update a product in Bugzilla.
+
+**Request**
+
+.. code-block:: text
+
+   PUT /rest/product/(id_or_name)
+
+You can edit a single product by passing the ID or name of the product
+in the URL. To edit more than one product, you can specify addition IDs or
+product names using the ``ids`` or ``names`` parameters respectively.
+
+.. code-block:: js
+
+   {
+     "ids" : [123],
+     "name" : "BarName",
+     "has_unconfirmed" : false
+   }
+
+One of the below must be specified.
+
+==============  =====  ==========================================================
+name            type   description
+==============  =====  ==========================================================
+**id_or_name**  mixed  Integer product ID or name.
+**ids**         array  Numeric IDs of the products that you wish to update.
+**names**       array  Names of the products that you wish to update.
+==============  =====  ==========================================================
+
+The following parameters specify the new values you want to set for the product(s)
+you are updating.
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+name               string   A new name for this product. If you try to set this
+                            while updating more than one product, an error will
+                            occur, as product names must be unique.
+default_milestone  string   When a new bug is filed, what milestone does it
+                            get by default if the user does not choose one? Must
+                            represent a milestone that is valid for this product.
+description        string   Update the long description for these products to
+                            this value.
+has_unconfirmed    boolean  Allow the UNCONFIRMED status to be set on bugs in
+                            products.
+is_open            boolean  ``true`` if the product is currently allowing bugs
+                            to be entered into it, ``false`` otherwise.
+=================  =======  =====================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+      "products" : [
+         {
+            "id" : 123,
+            "changes" : {
+               "name" : {
+                  "removed" : "FooName",
+                  "added" : "BarName"
+               },
+               "has_unconfirmed" : {
+                  "removed" : "1",
+                  "added" : "0"
+               }
+            }
+         }
+      ]
+   }
+
+``products`` (array) Product change objects containing the following items:
+
+=======  ======  ================================================================
+name     type    description
+=======  ======  ================================================================
+id       int     The ID of the product that was updated.
+changes  object  The changes that were actually done on this product. The
+                 keys are the names of the fields that were changed, and the
+                 values are an object with two items:
+
+                 * added: (string) The value that this field was changed to.
+                 * removed: (string) The value that was previously set in this
+                   field.
+=======  ======  ================================================================
+
+Booleans will be represented with the strings '1' and '0' for changed values
+as they are stored as strings in the database currently.
diff --git a/docs/en/rst/api/core/v1/user.rst b/docs/en/rst/api/core/v1/user.rst
new file mode 100644
index 000000000..e27211a7f
--- /dev/null
+++ b/docs/en/rst/api/core/v1/user.rst
@@ -0,0 +1,380 @@
+Users
+=====
+
+This part of the Bugzilla API allows you to create user accounts, get information
+about user accounts and to log in or out using an existing account.
+
+.. _rest_user_login:
+
+Login
+-----
+
+Logging in with a username and password is required for many Bugzilla
+installations, in order to search for private bugs, post new bugs, etc. This
+method allows you to retrieve a token that can be used as authentication for
+subsequent API calls. Otherwise yuou will need to pass your ``login`` and
+``password`` with each call.
+
+This method will be going away in the future in favor of using *API keys*.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/login?login=foo@example.com&password=toosecrettoshow
+
+==============  =======  ========================================================
+name            type     description
+==============  =======  ========================================================
+**login**       string   The user's login name.
+**password**    string   The user's password.
+restrict_login  boolean  If set to a true value, the token returned by this
+                         method will only be valid from the IP address which
+                         called this method.
+==============  =======  ========================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "token": "786-OLaWfBisMY",
+     "id": 786
+   }
+
+========  ======  ===============================================================
+name      type    description
+========  ======  ===============================================================
+id        int     Numeric ID of the user that was logged in.
+token     string  Token which can be passed in the parameters as
+                  authentication in other calls. The token can be sent along
+                  with any future requests to the webservice, for the duration
+                  of the session, i.e. til :ref:`rest_user_logout` is called.
+========  ======  ===============================================================
+
+.. _rest_user_logout:
+
+Logout
+------
+
+Log out the user. Basically it invalidates the token provided so it cannot be
+re-used. Does nothing if the token is not in use. Will also clear any existing
+authentication cookies the client may still have stored.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/logout?token=1234-VWvO51X69r
+
+=====  ======  ===================================================
+name   type    description
+=====  ======  ===================================================
+token  string   The user's token used for authentication.
+=====  ======  ===================================================
+
+.. _rest_user_valid_login:
+
+Valid Login
+-----------
+
+This method will verify whether a client's cookies or current login token is
+still valid or have expired. A valid username that matches must be provided as
+well.
+
+**Request**
+
+.. code-block:: text
+
+   GET /rest/valid_login?login=foo@example.com&token=1234-VWvO51X69r
+
+=========  =======  =============================================================
+name       type     description
+=========  =======  =============================================================
+**login**  string   The login name that matches the provided cookies or token.
+token      string   Persistent login token currently being used for
+                    authentication.
+=========  =======  =============================================================
+
+**Response**
+
+Returns true/false depending on if the current token is valid for the provided
+username.
+
+.. _rest_user_create:
+
+Create User
+-----------
+
+Creates a user account directly in Bugzilla, password and all. Instead of this,
+you should use **Offer Account by Email** when possible because that makes sure
+that the email address specified can actually receive an email. This function
+does not check that. You must be authenticated and be in the *editusers* group
+to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+   POST /rest/user
+
+.. code-block:: js
+
+   {
+     "email" : "user@bugzilla.org",
+     "full_name" : "Test User",
+     "password" : "K16ldRr922I1"
+   }
+
+==========  ======  =============================================================
+name        type    description
+==========  ======  =============================================================
+**email**   string  The email address for the new user.
+full_name   string  The user's full name. Will be set to empty if not specified.
+password    string  The password for the new user account, in plain text. It
+                    will be stripped of leading and trailing whitespace. If
+                    blank or not specified, the new created account will
+                    exist in Bugzilla but will not be allowed to log in
+                    using DB authentication until a password is set either
+                    by the user (through resetting their password) or by the
+                    administrator.
+==========  ======  =============================================================
+
+**Response**
+
+.. code-block:: js
+
+   {
+     "id": 58707
+   }
+
+====  ====  ============================================
+name  type  desciption
+====  ====  ============================================
+id    int   The numeric ID of the user that was created.
+====  ====  ============================================
+
+.. _rest_user_update:
+
+Update User
+-----------
+
+Updates an existing user account in Bugzilla. You must be authenticated and be
+in the *editusers* group to perform this action.
+
+**Request**
+
+.. code-block:: text
+
+   PUT /rest/user/(id_or_name)
+
+You can edit a single user by passing the ID or login name of the user
+in the URL. To edit more than one user, you can specify addition IDs or
+login names using the ``ids`` or ``names`` parameters respectively.
+
+=================  =======  =====================================================
+ name              type     description
+=================  =======  =====================================================
+**id_or_name**     mixed    Either the ID or the login name of the user to
+                            update.
+**ids**            array    Additional IDs of users to update.
+**names**          array    Additional login names of users to update.
+full_name          string   The new name of the user.
+email              string   The email of the user. Note that email used to
+                            login to bugzilla. Also note that you can only
+                            update one user at a time when changing the login
+                            name / email. (An error will be thrown if you try to
+                            update this field for multiple users at once.)
+password           string   The password of the user.
+email_enabled      boolean  A boolean value to enable/disable sending
+                            bug-related mail to the user.
+login_denied_text  string   A text field that holds the reason for disabling a
+                            user from logging into Bugzilla. If empty, then the
+                            user account is enabled; otherwise it is
+                            disabled/closed.
+groups             object   These specify the groups that this user is directly
+                            a member of. To set these, you should pass an object
+                            as the value. The object's items are described in
+                            the Groups update objects below.
+bless_groups       object   This is the same as groups but affects what groups
+                            a user has direct membership to bless that group.
+                            It takes the same inputs as groups.
+=================  =======  =====================================================
+
+Groups and bless groups update object:
+
+======  =====  ==================================================================
+name    type   description
+======  =====  ==================================================================
+add     array  The group IDs or group names that the user should be added to.
+remove  array  The group IDs or group names that the user should be removed from.
+set     array  Integers or strings which are an exact set of group IDs and group
+               names that the user should be a member of. This does not remove
+               groups from the user when the person making the change does not
+               have the bless privilege for the group.
+======  =====  ==================================================================
+
+If you specify ``set``, then ``add`` and ``remove`` will be ignored. A group in
+both the ``add`` and ``remove`` list will be added. Specifying a group that the
+user making the change does not have bless rights will generate an error.
+
+**Response**
+
+* users: (array) List of user change objects with the following items:
+
+=======  ======  ================================================================
+name     type    description
+=======  ======  ================================================================
+id       int     The ID of the user that was updated.
+changes  object  The changes that were actually done on this user. The keys
+                 are the names of the fields that were changed, and the values
+                 are an object with two items:
+
+                 * added: (string) The values that were added to this field,
+                   possibly a comma-and-space-separated list if multiple values
+                   were added.
+                 * removed: (string) The values that were removed from this
+                   field, possibly a comma-and-space-separated list if multiple
+                   values were removed.
+=======  ======  ================================================================
+
+.. _rest_user_get:
+
+Get User
+--------
+
+Gets information about user accounts in Bugzilla.
+
+**Request**
+
+To get information about a single user in Bugzilla:
+
+.. code-block:: text
+
+   GET /rest/user/(id_or_name)
+
+To get multiple users by name or ID:
+
+.. code-block:: text
+
+   GET /rest/user?names=foo@bar.com&name=test@bugzilla.org
+   GET /rest/user?ids=123&ids=321
+
+To get user matching a search string:
+
+.. code-block:: text
+
+   GET /rest/user?match=foo
+
+To get user by using an integer ID value or by using ``match``, you must be
+authenticated.
+
+================  =======  ======================================================
+name              type     description
+================  =======  ======================================================
+id_or_name        mixed    An integer user ID or login name of the user.
+ids               array    Integer user IDs. Logged=out users cannot pass
+                           this parameter to this function. If they try,
+                           they will get an error. Logged=in users will get
+                           an error if they specify the ID of a user they
+                           cannot see.
+names             array    Login names.
+match             array    This works just like "user matching" in Bugzilla
+                           itself. Users will be returned whose real name
+                           or login name contains any one of the specified
+                           strings. Users that you cannot see will not be
+                           included in the returned list.
+
+                           Most installations have a limit on how many
+                           matches are returned for each string; the default
+                           is 1000 but can be changed by the Bugzilla
+                           administrator.
+
+                           Logged-out users cannot use this argument, and
+                           an error will be thrown if they try. (This is to
+                           make it harder for spammers to harvest email
+                           addresses from Bugzilla, and also to enforce the
+                           user visibility restrictions that are
+                           implemented on some Bugzillas.)
+limit             int      Limit the number of users matched by the
+                           ``match`` parameter. If the value is greater than the
+                           system limit, the system limit will be used.
+                           This parameter is only valid when using the ``match``
+                           parameter.
+group_ids         array    Numeric IDs for groups that a user can be in.
+groups            array    Names of groups that a user can be in. If
+                           ``group_ids`` or ``groups`` are specified, they
+                           limit the return value to users who are in *any*
+                           of the groups specified.
+include_disabled  boolean  By default, when using the ``match`` parameter,
+                           disabled users are excluded from the returned
+                           results unless their full username is identical
+                           to the match string. Setting ``include_disabled`` to
+                           ``true`` will include disabled users in the returned
+                           results even if their username doesn't fully match
+                           the input string.
+================  =======  ======================================================
+
+**Response**
+
+* users: (array) Each object describes a user and has the following items:
+
+=================  =======  =====================================================
+name               type     description
+=================  =======  =====================================================
+id                 int      The unique integer ID that Bugzilla uses to represent
+                            this user. Even if the user's login name changes,
+                            this will not change.
+real_name          string   The actual name of the user. May be blank.
+email              string   The email address of the user.
+name               string   The login name of the user. Note that in some
+                            situations this is different than their email.
+can_login          boolean  A boolean value to indicate if the user can login
+                            into bugzilla.
+email_enabled      boolean  A boolean value to indicate if bug-related mail will
+                            be sent to the user or not.
+login_denied_text  string   A text field that holds the reason for disabling a
+                            user from logging into Bugzilla. If empty then the
+                            user account is enabled; otherwise it is
+                            disabled/closed.
+groups             array    Groups the user is a member of. If the currently
+                            logged in user is querying their own account or is a
+                            member of the 'editusers' group, the array will
+                            contain all the groups that the user is a member of.
+                            Otherwise, the array will only contain groups that
+                            the logged in user can bless. Each object describes
+                            the group and contains the items described in the
+                            Group object below.
+saved_searches     array    User's saved searches, each having the following
+                            Search object items described below.
+saved_reports      array    User's saved reports, each having the following
+                            Search object items described below.
+=================  =======  =====================================================
+
+Group object:
+
+===========  ======  ============================================================
+name         type    description
+===========  ======  ============================================================
+id           int     The group ID
+name         string  The name of the group
+description  string  The description for the group
+===========  ======  ============================================================
+
+Search object:
+
+=====  ======  ==================================================================
+name   type    description
+=====  ======  ==================================================================
+id     int     An integer ID uniquely identifying the saved report.
+name   string  The name of the saved report.
+query  string  The CGI parameters for the saved report.
+=====  ======  ==================================================================
+
+If you are not authenticated when you call this function, you will only be
+returned the ``id``, ``name``, and ``real_name`` items. If you are authenticated
+and not in 'editusers' group, you will only be returned the ``id``, ``name``,
+``real_name``, ``email``, ``can_login``, and ``groups`` items. The groups
+returned are filtered based on your permission to bless each group. The
+``saved_searches`` and ``saved_reports`` items are only returned if you are
+querying your own account, even if you are in the editusers group.