# 6. API Documentation

Contents

- JIRA
- Issue
- Priority
- Comment
- Worklog
- Watchers
- JIRAError

## 6.1. JIRA

class `jira.``JIRA`(server=None, options=None, basic_auth=None, oauth=None, jwt=None, kerberos=False, kerberos_options=None, validate=False, get_server_info=True, async_=False, async_workers=5, logging=True, max_retries=3, proxies=None, timeout=None, auth=None)

  Bases: `object`

  User interface to JIRA.

  Clients interact with JIRA by constructing an instance of this object and calling its methods. For addressable resources in JIRA – those with “self” links – an appropriate subclass of `Resource` will be returned with customized `update()` and `delete()` methods, along with attribute access to fields. This means that calls of the form `issue.fields.summary` will be resolved into the proper lookups to return the JSON value at that mapping. Methods that do not return resources will return a dict constructed from the JSON response or a scalar value; see each method’s documentation for details on what that method returns.

  Without any arguments, this client will connect anonymously to the JIRA instance started by the Atlassian Plugin SDK from one of the ‘atlas-run’, `atlas-debug`, or `atlas-run-standalone` commands. By default, this instance runs at `http://localhost:2990/jira`. The `options` argument can be used to set the JIRA instance to use.

  Authentication is handled with the `basic_auth` argument. If authentication is supplied (and is accepted by JIRA), the client will remember it for subsequent requests.

  For quick command line access to a server, see the `jirashell` script included with this distribution.

  The easiest way to instantiate is using `j = JIRA("https://jira.atlassian.com")`

  Parameters:

  - options –

    Specify the server and properties this client will use. Use a dict with any of the following properties:

    - server – the server address and context path to use. Defaults to `http://localhost:2990/jira`.
    - rest_path – the root REST path to use. Defaults to `api`, where the JIRA REST resources live.
    - rest_api_version – the version of the REST resources under rest_path to use. Defaults to `2`.
    - agile_rest_path - the REST path to use for JIRA Agile requests. Defaults to `greenhopper` (old, private
        API). Check GreenHopperResource for other supported values.
    - verify – Verify SSL certs. Defaults to `True`.
    - client_cert – a tuple of (cert,key) for the requests library for client side SSL
    - check_update – Check whether using the newest python-jira library version.
    - cookies – A dict of custom cookies that are sent in all requests to the server.
  - basic_auth – A tuple of username and password to use when establishing a session via HTTP BASIC authentication.
  - oauth –

    A dict of properties for OAuth authentication. The following properties are required:

    - access_token – OAuth access token for the user
    - access_token_secret – OAuth access token secret to sign with the key
    - consumer_key – key of the OAuth application link defined in JIRA
    - key_cert – private key file to sign requests with (should be the pair of the public key supplied to JIRA in the OAuth application link)
  - kerberos – If true it will enable Kerberos authentication.
  - kerberos_options –

    A dict of properties for Kerberos authentication. The following properties are possible:

    - mutual_authentication – string DISABLED or OPTIONAL.

    Example kerberos_options structure: `{'mutual_authentication': 'DISABLED'}`

  - jwt –

    A dict of properties for JWT authentication supported by Atlassian Connect. The following properties are required:

    - secret – shared secret as delivered during ‘installed’ lifecycle event (see https://developer.atlassian.com/static/connect/docs/latest/modules/lifecycle.html for details)
    - payload – dict of fields to be inserted in the JWT payload, e.g. ‘iss’

    Example jwt structure: `{'secret': SHARED_SECRET, 'payload': {'iss': PLUGIN_KEY}}`

  - validate – If true it will validate your credentials first. Remember that if you are accessing JIRA as anonymous it will fail to instantiate.
  - get_server_info – If true it will fetch server version info first to determine if some API calls are available.
  - async – To enable asynchronous requests for those actions where we implemented it, like issue update() or delete().
  - async_workers – Set the number of worker threads for async operations.
  - timeout – Set a read/connect timeout for the underlying calls to JIRA (default: None) Obviously this means that you cannot rely on the return code when this is enabled.

  `AGILE_BASE_URL` = '{server}/rest/{agile_rest_path}/{agile_rest_api_version}/{path}'
  `DEFAULT_OPTIONS` = {'agile_rest_api_version': '1.0', 'agile_rest_path': 'greenhopper', 'async': False, 'async_workers': 5, 'auth_url': '/rest/auth/1/session', 'check_update': False, 'client_cert': None, 'context_path': '/', 'headers': {'Cache-Control': 'no-cache', 'Content-Type': 'application/json', 'X-Atlassian-Token': 'no-check'}, 'resilient': True, 'rest_api_version': '2', 'rest_path': 'api', 'server': 'http://localhost:2990/jira', 'verify': True}
  `JIRA_BASE_URL` = '{server}/rest/{rest_path}/{rest_api_version}/{path}'
  `add_attachment`(issue, attachment, filename=None)

    Attach an attachment to an issue and returns a Resource for it.

    The client will not attempt to open or validate the attachment; it expects a file-like object to be ready for its use. The user is still responsible for tidying up (e.g., closing the file, killing the socket, etc.)

    Parameters:

    - issue – the issue to attach the attachment to
    - attachment – file-like object to attach to the issue, also works if it is a string with the filename.
    - filename – optional name for the attached file. If omitted, the file object’s `name` attribute is used. If you acquired the file-like object by any other method than `open()`, make sure that a name is specified in one way or the other.

    Return type: | an Attachment Resource

  `add_comment`(issue, body, visibility=None, is_internal=False)

    Add a comment from the current authenticated user on the specified issue and return a Resource for it.

    The issue identifier and comment body are required.

    Parameters:

    - issue – ID or key of the issue to add the comment to
    - body – Text of the comment to add
    - visibility – a dict containing two entries: “type” and “value”. “type” is ‘role’ (or ‘group’ if the JIRA server has configured comment visibility for groups) and ‘value’ is the name of the role (or group) to which viewing of this comment will be restricted.
    - is_internal – defines whether a comment has to be marked as ‘Internal’ in Jira Service Desk

  `add_group`(groupname)

    Create a new group in JIRA.

    Parameters: | groupname – The name of the group you wish to create.
    Returns: | Boolean - True if successful.

  `add_issues_to_epic`(epic_id, issue_keys, ignore_epics=True)

    Add the issues in `issue_keys` to the `epic_id`.

    Parameters:

    - epic_id – the epic to add issues to
    - issue_keys – the issues to add to the epic
    - ignore_epics – ignore any issues listed in `issue_keys` that are epics

  `add_issues_to_sprint`(sprint_id, issue_keys)

    Add the issues in `issue_keys` to the `sprint_id`.

    The sprint must be started but not completed.

    If a sprint was completed, then have to also edit the history of the issue so that it was added to the sprint before it was completed, preferably before it started. A completed sprint’s issues also all have a resolution set before the completion date.

    If a sprint was not started, then have to edit the marker and copy the rank of each issue too.

    Parameters:

    - sprint_id (int) – the sprint to add issues to
    - issue_keys (list of str) – the issues to add to the sprint

  `add_remote_link`(issue, destination, globalId=None, application=None, relationship=None)

    Add a remote link from an issue to an external application and returns a remote link Resource for it.

    `object` should be a dict containing at least `url` to the linked external URL and `title` to display for the link inside JIRA.

    For definitions of the allowable fields for `object` and the keyword arguments `globalId`, `application` and `relationship`, see https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+for+Remote+Issue+Links.

    Parameters:

    - issue – the issue to add the remote link to
    - destination – the link details to add (see the above link for details)
    - globalId – unique ID for the link (see the above link for details)
    - application – application information for the link (see the above link for details)
    - relationship – relationship description for the link (see the above link for details)

  `add_simple_link`(issue, object)

    Add a simple remote link from an issue to web resource.

    This avoids the admin access problems from add_remote_link by just
      using a simple object and presuming all fields are correct and not requiring more complex `application` data.
    `object` should be a dict containing at least `url` to the
      linked external URL and `title` to display for the link inside JIRA.

    For definitions of the allowable fields for `object` , see https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+for+Remote+Issue+Links.

    Parameters:

    - issue – the issue to add the remote link to
    - object – the dictionary used to create remotelink data

  `add_user`(username, email, directoryId=1, password=None, fullname=None, notify=False, active=True, ignore_existing=False, application_keys=None)

    Create a new JIRA user.

    Parameters:

    - username (`str`) – the username of the new user
    - email (`str`) – email address of the new user
    - directoryId (`int`) – the directory ID the new user should be a part of
    - password (`str`) – Optional, the password for the new user
    - fullname (`str`) – Optional, the full name of the new user
    - notify (`bool`) – Whether or not to send a notification to the new user
    - active (`bool`) – Whether or not to make the new user active upon creation
    - applicationKeys (`list`) – Keys of products user should have access to

  `add_user_to_group`(username, group)

    Add a user to an existing group.

    Parameters:

    - username – Username that will be added to specified group.
    - group – Group that the user will be added to.

    Returns: | json response from Jira server for success or a value that evaluates as False in case of failure.

  `add_vote`(issue)

    Register a vote for the current authenticated user on an issue.

    Parameters: | issue – ID or key of the issue to vote on

  `add_watcher`(issue, watcher)

    Add a user to an issue’s watchers list.

    Parameters:

    - issue – ID or key of the issue affected
    - watcher – username of the user to add to the watchers list

  `add_worklog`(issue, timeSpent=None, timeSpentSeconds=None, adjustEstimate=None, newEstimate=None, reduceBy=None, comment=None, started=None, user=None)

    Add a new worklog entry on an issue and return a Resource for it.

    Parameters:

    - issue – the issue to add the worklog to
    - timeSpent – a worklog entry with this amount of time spent, e.g. “2d”
    - adjustEstimate – (optional) allows the user to provide specific instructions to update the remaining time estimate of the issue. The value can either be `new`, `leave`, `manual` or `auto` (default).
    - newEstimate – the new value for the remaining estimate field. e.g. “2d”
    - reduceBy – the amount to reduce the remaining estimate by e.g. “2d”
    - started – Moment when the work is logged, if not specified will default to now
    - comment – optional worklog comment

  `application_properties`(key=None)

    Return the mutable server application properties.

    Parameters: | key – the single property to return a value for

  `applicationlinks`(cached=True)

    List of application links.

    Returns: | json

  `assign_issue`(issue, assignee)

    Assign an issue to a user. None will set it to unassigned. -1 will set it to Automatic.

    Parameters:

    - issue (int or str) – the issue ID or key to assign
    - assignee (str) – the user to assign the issue to

    Return type: | bool

  `async_do`(size=10)

    Execute all asynchronous jobs and wait for them to finish. By default it will run on 10 threads.

    Parameters: | size – number of threads to run on.

  `attachment`(id)

    Get an attachment Resource from the server for the specified ID.

  `attachment_meta`()

    Get the attachment metadata.

  `backup`(filename='backup.zip', attachments=False)

    Will call jira export to backup as zipped xml. Returning with success does not mean that the backup process finished.

  `backup_complete`()

    Return boolean based on ‘alternativePercentage’ and ‘size’ returned from backup_progress (cloud only).

  `backup_download`(filename=None)

    Download backup file from WebDAV (cloud only).

  `backup_progress`()

    Return status of cloud backup as a dict.

    Is there a way to get progress for Server version?

  `boards`(startAt=0, maxResults=50, type=None, name=None)

    Get a list of board resources.

    Parameters:

    - startAt – The starting index of the returned boards. Base index: 0.
    - maxResults – The maximum number of boards to return per page. Default: 50
    - type – Filters results to boards of the specified type. Valid values: scrum, kanban.
    - name – Filters results to boards that match or partially match the specified name.

    Return type: | ResultList[Board]

    When old GreenHopper private API is used, paging is not enabled and all parameters are ignored.

  `checked_version` = False
  `client_info`()

    Get the server this client is connected to.

  `close`()
  `comment`(issue, comment)

    Get a comment Resource from the server for the specified ID.

    Parameters:

    - issue – ID or key of the issue to get the comment from
    - comment – ID of the comment to get

  `comments`(issue)

    Get a list of comment Resources.

    Parameters: | issue – the issue to get comments from

  `component`(id)

    Get a component Resource from the server.

    Parameters: | id – ID of the component to get

  `component_count_related_issues`(id)

    Get the count of related issues for a component.

    Parameters: | id (integer) – ID of the component to use

  `confirm_project_avatar`(project, cropping_properties)

    Confirm the temporary avatar image previously uploaded with the specified cropping.

    After a successful registry with `create_temp_project_avatar()`, use this method to confirm the avatar for use. The final avatar can be a subarea of the uploaded image, which is customized with the `cropping_properties`: the return value of `create_temp_project_avatar()` should be used for this argument.

    Parameters:

    - project – ID or key of the project to confirm the avatar in
    - cropping_properties – a dict of cropping properties from `create_temp_project_avatar()`

  `confirm_user_avatar`(user, cropping_properties)

    Confirm the temporary avatar image previously uploaded with the specified cropping.

    After a successful registry with `create_temp_user_avatar()`, use this method to confirm the avatar for use. The final avatar can be a subarea of the uploaded image, which is customized with the `cropping_properties`: the return value of `create_temp_user_avatar()` should be used for this argument.

    Parameters:

    - user – the user to confirm the avatar for
    - cropping_properties – a dict of cropping properties from `create_temp_user_avatar()`

  `create_board`(name, project_ids, preset='scrum', location_type='user', location_id=None)

    Create a new board for the `project_ids`.

    Parameters:

    - name – name of the board
    - project_ids – the projects to create the board in
    - preset ('kanban', 'scrum', 'diy') – what preset to use for this board
    - location_type ('user', 'project') – the location type. Available in cloud.
    - location_id – the id of project that the board should be located under. Omit this for a ‘user’ location_type. Available in cloud.

  `create_component`(name, project, description=None, leadUserName=None, assigneeType=None, isAssigneeTypeValid=False)

    Create a component inside a project and return a Resource for it.

    Parameters:

    - name – name of the component
    - project – key of the project to create the component in
    - description – a description of the component
    - leadUserName – the username of the user responsible for this component
    - assigneeType – see the ComponentBean.AssigneeType class for valid values
    - isAssigneeTypeValid – boolean specifying whether the assignee type is acceptable

  `create_customer`(email, displayName)

    Create a new customer and return an issue Resource for it.

  `create_customer_request`(fields=None, prefetch=True, **fieldargs)

    Create a new customer request and return an issue Resource for it.

    Each keyword argument (other than the predefined ones) is treated as a field name and the argument’s value is treated as the intended value for that field – if the fields argument is used, all other keyword arguments will be ignored.

    By default, the client will immediately reload the issue Resource created by this method in order to return a complete Issue object to the caller; this behavior can be controlled through the ‘prefetch’ argument.

    JIRA projects may contain many different issue types. Some issue screens have different requirements for fields in a new issue. This information is available through the ‘createmeta’ method. Further examples are available here: https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Create+Issue

    Parameters:

    - fields – a dict containing field names and the values to use. If present, all other keyword arguments will be ignored
    - prefetch – whether to reload the created issue Resource so that all of its data is present in the value returned from this method

  `create_filter`(name=None, description=None, jql=None, favourite=None)

    Create a new filter and return a filter Resource for it.

    Parameters:

    - name – name of the new filter
    - description – useful human readable description of the new filter
    - jql – query string that defines the filter
    - favourite – whether to add this filter to the current user’s favorites

  `create_issue`(fields=None, prefetch=True, **fieldargs)

    Create a new issue and return an issue Resource for it.

    Each keyword argument (other than the predefined ones) is treated as a field name and the argument’s value is treated as the intended value for that field – if the fields argument is used, all other keyword arguments will be ignored.

    By default, the client will immediately reload the issue Resource created by this method in order to return a complete Issue object to the caller; this behavior can be controlled through the ‘prefetch’ argument.

    JIRA projects may contain many different issue types. Some issue screens have different requirements for fields in a new issue. This information is available through the ‘createmeta’ method. Further examples are available here: https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Create+Issue

    Parameters:

    - fields – a dict containing field names and the values to use. If present, all other keyword arguments will be ignored
    - prefetch – whether to reload the created issue Resource so that all of its data is present in the value returned from this method

  `create_issue_link`(type, inwardIssue, outwardIssue, comment=None)

    Create a link between two issues.

    Parameters:

    - type – the type of link to create
    - inwardIssue – the issue to link from
    - outwardIssue – the issue to link to
    - comment – a comment to add to the issues with the link. Should be a dict containing `body` and `visibility` fields: `body` being the text of the comment and `visibility` being a dict containing two entries: `type` and `value`. `type` is `role` (or `group` if the JIRA server has configured comment visibility for groups) and `value` is the name of the role (or group) to which viewing of this comment will be restricted.

  `create_issues`(field_list, prefetch=True)

    Bulk create new issues and return an issue Resource for each successfully created issue.

    See create_issue documentation for field information.

    Parameters:

    - field_list – a list of dicts each containing field names and the values to use. Each dict is an individual issue to create and is subject to its minimum requirements.
    - prefetch – whether to reload the created issue Resource for each created issue so that all of its data is present in the value returned from this method.

  `create_project`(key, name=None, assignee=None, type='Software', template_name=None)

    Key is mandatory and has to match JIRA project key requirements, usually only 2-10 uppercase characters.

    If name is not specified it will use the key value. If assignee is not specified it will use current user. Parameter template_name is used to create a project based on one of the existing project templates. If template_name is not specified, then it should use one of the default values. The returned value should evaluate to False if it fails otherwise it will be the new project id.

  `create_sprint`(name, board_id, startDate=None, endDate=None)

    Create a new sprint for the `board_id`.

    Parameters:

    - name – name of the sprint
    - board_id – the board to add the sprint to

  `create_temp_project_avatar`(project, filename, size, avatar_img, contentType=None, auto_confirm=False)

    Register an image file as a project avatar.

    The avatar created is temporary and must be confirmed before it can
      be used.
    Avatar images are specified by a filename, size, and file object. By default, the client will attempt to
      autodetect the picture’s content type: this mechanism relies on libmagic and will not work out of the box on Windows systems (see http://filemagic.readthedocs.org/en/latest/guide.html for details on how to install support). The `contentType` argument can be used to explicitly set the value (note that JIRA will reject any type other than the well-known ones for images, e.g. `image/jpg`, `image/png`, etc.)
    This method returns a dict of properties that can be used to crop a subarea of a larger image for use. This
      dict should be saved and passed to `confirm_project_avatar()` to finish the avatar creation process. If you want to cut out the middleman and confirm the avatar with JIRA’s default cropping, pass the ‘auto_confirm’ argument with a truthy value and `confirm_project_avatar()` will be called for you before this method returns.

    Parameters:

    - project – ID or key of the project to create the avatar in
    - filename – name of the avatar file
    - size – size of the avatar file
    - avatar_img – file-like object holding the avatar
    - contentType – explicit specification for the avatar image’s content-type
    - auto_confirm (boolean) – whether to automatically confirm the temporary avatar by calling `confirm_project_avatar()` with the return value of this method.

  `create_temp_user_avatar`(user, filename, size, avatar_img, contentType=None, auto_confirm=False)

    Register an image file as a user avatar.

    The avatar created is temporary and must be confirmed before it can be used.

    Avatar images are specified by a filename, size, and file object. By default, the client will attempt to autodetect the picture’s content type: this mechanism relies on `libmagic` and will not work out of the box on Windows systems (see http://filemagic.readthedocs.org/en/latest/guide.html for details on how to install support). The `contentType` argument can be used to explicitly set the value (note that JIRA will reject any type other than the well-known ones for images, e.g. `image/jpg`, `image/png`, etc.)

    This method returns a dict of properties that can be used to crop a subarea of a larger image for use. This dict should be saved and passed to `confirm_user_avatar()` to finish the avatar creation process. If you want to cut out the middleman and confirm the avatar with JIRA’s default cropping, pass the `auto_confirm` argument with a truthy value and `confirm_user_avatar()` will be called for you before this method returns.

    Parameters:

    - user – user to register the avatar for
    - filename – name of the avatar file
    - size – size of the avatar file
    - avatar_img – file-like object containing the avatar
    - contentType – explicit specification for the avatar image’s content-type
    - auto_confirm – whether to automatically confirm the temporary avatar by calling `confirm_user_avatar()` with the return value of this method.

  `create_version`(name, project, description=None, releaseDate=None, startDate=None, archived=False, released=False)

    Create a version in a project and return a Resource for it.

    Parameters:

    - name – name of the version to create
    - project – key of the project to create the version in
    - description – a description of the version
    - releaseDate – the release date assigned to the version
    - startDate – The start date for the version

  `createmeta`(projectKeys=None, projectIds=[], issuetypeIds=None, issuetypeNames=None, expand=None)

    Get the metadata required to create issues, optionally filtered by projects and issue types.

    Parameters:

    - projectKeys – keys of the projects to filter the results with. Can be a single value or a comma-delimited string. May be combined with projectIds.
    - projectIds – IDs of the projects to filter the results with. Can be a single value or a comma-delimited string. May be combined with projectKeys.
    - issuetypeIds – IDs of the issue types to filter the results with. Can be a single value or a comma-delimited string. May be combined with issuetypeNames.
    - issuetypeNames – Names of the issue types to filter the results with. Can be a single value or a comma-delimited string. May be combined with issuetypeIds.
    - expand – extra information to fetch inside each resource.

  `current_user`()
  `custom_field_option`(id)

    Get a custom field option Resource from the server.

    Parameters: | id – ID of the custom field to use

  `dashboard`(id)

    Get a dashboard Resource from the server.

    Parameters: | id – ID of the dashboard to get.

  `dashboards`(filter=None, startAt=0, maxResults=20)

    Return a ResultList of Dashboard resources and a `total` count.

    Parameters:

    - filter – either “favourite” or “my”, the type of dashboards to return
    - startAt – index of the first dashboard to return
    - maxResults – maximum number of dashboards to return. If maxResults evaluates as False, it will try to get all items in batches.

    Return type: | ResultList

  `deactivate_user`(username)

    Disable/deactivate the user.

  `delete_attachment`(id)

    Delete attachment by id.

    Parameters: | id – ID of the attachment to delete

  `delete_board`(id)

    Delete an agile board.

  `delete_component`(id)

    Delete component by id.

    Parameters: | id – ID of the component to use

  `delete_issue_link`(id)

    Delete a link between two issues.

    Parameters: | id – ID of the issue link to delete

  `delete_project`(pid)

    Delete project from Jira.

    Parameters: | pid (str) – JIRA projectID or Project or slug
    Returns bool: | True if project was deleted

    Raises:

    - JIRAError – If project not found or not enough permissions
    - ValueError – If pid parameter is not Project, slug or ProjectID

  `delete_project_avatar`(project, avatar)

    Delete a project’s avatar.

    Parameters:

    - project – ID or key of the project to delete the avatar from
    - avatar – ID of the avatar to delete

  `delete_user`(username)
  `delete_user_avatar`(username, avatar)

    Delete a user’s avatar.

    Parameters:

    - username – the user to delete the avatar from
    - avatar – ID of the avatar to remove

  `editmeta`(issue)

    Get the edit metadata for an issue.

    Parameters: | issue – the issue to get metadata for

  `favourite_filters`()

    Get a list of filter Resources which are the favourites of the currently authenticated user.

  `fields`()

    Return a list of all issue fields.

  `filter`(id)

    Get a filter Resource from the server.

    Parameters: | id – ID of the filter to get.

  `find`(resource_format, ids=None)

    Find Resource object for any addressable resource on the server.

    This method is a universal resource locator for any REST-ful resource in JIRA. The argument `resource_format` is a string of the form `resource`, `resource/{0}`, `resource/{0}/sub`, `resource/{0}/sub/{1}`, etc. The format placeholders will be populated from the `ids` argument if present. The existing authentication session will be used.

    The return value is an untyped Resource object, which will not support specialized `Resource.update()` or `Resource.delete()` behavior. Moreover, it will not know to return an issue Resource if the client uses the resource issue path. For this reason, it is intended to support resources that are not included in the standard Atlassian REST API.

    Parameters:

    - resource_format – the subpath to the resource string
    - ids (tuple or None) – values to substitute in the `resource_format` string

  `find_transitionid_by_name`(issue, transition_name)

    Get a transitionid available on the specified issue to the current user.

    Look at https://developer.atlassian.com/static/rest/jira/6.1.html#d2e1074 for json reference

    Parameters:

    - issue – ID or key of the issue to get the transitions from
    - trans_name – iname of transition we are looking for

  `get_igrid`(issueid, customfield, schemeid)
  `group_members`(group)

    Return a hash or users with their information. Requires JIRA 6.0 or will raise NotImplemented.

  `groups`(query=None, exclude=None, maxResults=9999)

    Return a list of groups matching the specified criteria.

    Parameters:

    - query – filter groups by name with this string
    - exclude – filter out groups by name with this string
    - maxResults – maximum results to return. defaults to 9999

  `incompletedIssuesEstimateSum`(board_id, sprint_id)

    Return the total incompleted points this sprint.

  `issue`(id, fields=None, expand=None)

    Get an issue Resource from the server.

    Parameters:

    - id – ID or key of the issue to get
    - fields – comma-separated string of issue fields to include in the results
    - expand – extra information to fetch inside each resource

  `issue_link`(id)

    Get an issue link Resource from the server.

    Parameters: | id – ID of the issue link to get

  `issue_link_type`(id)

    Get an issue link type Resource from the server.

    Parameters: | id – ID of the issue link type to get

  `issue_link_types`()

    Get a list of issue link type Resources from the server.

  `issue_type`(id)

    Get an issue type Resource from the server.

    Parameters: | id – ID of the issue type to get

  `issue_type_by_name`(name)
  `issue_types`()

    Get a list of issue type Resources from the server.

  `kill_session`()

    Destroy the session of the current authenticated user.

  `kill_websudo`()

    Destroy the user’s current WebSudo session.

    Works only for non-cloud deployments, for others does nothing.

  `move_to_backlog`(issue_keys)

    Move issues in `issue_keys` to the backlog, removing them from all sprints that have not been completed.

    Parameters: | issue_keys – the issues to move to the backlog

  `move_version`(id, after=None, position=None)

    Move a version within a project’s ordered version list and return a new version Resource for it.

    One, but not both, of `after` and `position` must be specified.

    Parameters:

    - id – ID of the version to move
    - after – the self attribute of a version to place the specified version after (that is, higher in the list)
    - position – the absolute position to move this version to: must be one of `First`, `Last`, `Earlier`, or `Later`

  `my_permissions`(projectKey=None, projectId=None, issueKey=None, issueId=None)

    Get a dict of all available permissions on the server.

    Parameters:

    - projectKey – limit returned permissions to the specified project
    - projectId – limit returned permissions to the specified project
    - issueKey – limit returned permissions to the specified issue
    - issueId – limit returned permissions to the specified issue

  `myself`()

    Get a dict of server information for this JIRA instance.

  `priorities`()

    Get a list of priority Resources from the server.

  `priority`(id)

    Get a priority Resource from the server.

    Parameters: | id – ID of the priority to get

  `project`(id)

    Get a project Resource from the server.

    Parameters: | id – ID or key of the project to get

  `project_avatars`(project)

    Get a dict of all avatars for a project visible to the current authenticated user.

    Parameters: | project – ID or key of the project to get avatars for

  `project_components`(project)

    Get a list of component Resources present on a project.

    Parameters: | project – ID or key of the project to get components from

  `project_role`(project, id)

    Get a role Resource.

    Parameters:

    - project – ID or key of the project to get the role from
    - id – ID of the role to get

  `project_roles`(project)

    Get a dict of role names to resource locations for a project.

    Parameters: | project – ID or key of the project to get roles from

  `project_versions`(project)

    Get a list of version Resources present on a project.

    Parameters: | project – ID or key of the project to get versions from

  `projects`()

    Get a list of project Resources from the server visible to the current authenticated user.

  `rank`(issue, next_issue)

    Rank an issue before another using the default Ranking field, the one named ‘Rank’.

    Parameters:

    - issue – issue key of the issue to be ranked before the second one.
    - next_issue – issue key of the second issue.

  `reindex`(force=False, background=True)

    Start jira re-indexing. Returns True if reindexing is in progress or not needed, or False.

    If you call reindex() without any parameters it will perform a background reindex only if JIRA thinks it should do it.

    Parameters:

    - force – reindex even if JIRA doesn’t say this is needed, False by default.
    - background – reindex in background, slower but does not impact the users, defaults to True.

  `remote_link`(issue, id)

    Get a remote link Resource from the server.

    Parameters:

    - issue – the issue holding the remote link
    - id – ID of the remote link

  `remote_links`(issue)

    Get a list of remote link Resources from an issue.

    Parameters: | issue – the issue to get remote links from

  `remove_group`(groupname)

    Delete a group from the JIRA instance.

    Parameters: | groupname – The group to be deleted from the JIRA instance.
    Returns: | Boolean. Returns True on success.

  `remove_user_from_group`(username, groupname)

    Remove a user from a group.

    Parameters:

    - username – The user to remove from the group.
    - groupname – The group that the user will be removed from.

  `remove_vote`(issue)

    Remove the current authenticated user’s vote from an issue.

    Parameters: | issue – ID or key of the issue to remove vote on

  `remove_watcher`(issue, watcher)

    Remove a user from an issue’s watch list.

    Parameters:

    - issue – ID or key of the issue affected
    - watcher – username of the user to remove from the watchers list

  `removedIssuesEstimateSum`(board_id, sprint_id)

    Return the total incompleted points this sprint.

  `removed_issues`(board_id, sprint_id)

    Return the completed issues for the sprint.

  `rename_user`(old_user, new_user)

    Rename a JIRA user.

    Parameters:

    - old_user – string with username login
    - new_user – string with username login

  `request_type_by_name`(service_desk, name)
  `request_types`(service_desk)
  `resolution`(id)

    Get a resolution Resource from the server.

    Parameters: | id – ID of the resolution to get

  `resolutions`()

    Get a list of resolution Resources from the server.

  `search_allowed_users_for_issue`(user, issueKey=None, projectKey=None, startAt=0, maxResults=50)

    Get a list of user Resources that match a username string and have browse permission for the issue or project.

    Parameters:

    - user – a string to match usernames against.
    - issueKey – find users with browse permission for this issue.
    - projectKey – find users with browse permission for this project.
    - startAt – index of the first user to return.
    - maxResults – maximum number of users to return. If maxResults evaluates as False, it will try to get all items in batches.

  `search_assignable_users_for_issues`(username, project=None, issueKey=None, expand=None, startAt=0, maxResults=50)

    Get a list of user Resources that match the search string for assigning or creating issues.

    This method is intended to find users that are eligible to create issues in a project or be assigned to an existing issue. When searching for eligible creators, specify a project. When searching for eligible assignees, specify an issue key.

    Parameters:

    - username – a string to match usernames against
    - project – filter returned users by permission in this project (expected if a result will be used to create an issue)
    - issueKey – filter returned users by this issue (expected if a result will be used to edit this issue)
    - expand – extra information to fetch inside each resource
    - startAt – index of the first user to return
    - maxResults – maximum number of users to return. If maxResults evaluates as False, it will try to get all items in batches.

  `search_assignable_users_for_projects`(username, projectKeys, startAt=0, maxResults=50)

    Get a list of user Resources that match the search string and can be assigned issues for projects.

    Parameters:

    - username – a string to match usernames against
    - projectKeys – comma-separated list of project keys to check for issue assignment permissions
    - startAt – index of the first user to return
    - maxResults – maximum number of users to return. If maxResults evaluates as False, it will try to get all users in batches.

  `search_issues`(jql_str, startAt=0, maxResults=50, validate_query=True, fields=None, expand=None, json_result=None)

    Get a `ResultList` of issue Resources matching a JQL search string.

    Parameters:

    - jql_str (str) – the JQL search string to use
    - startAt (int) – index of the first issue to return
    - maxResults (int) – maximum number of issues to return. Total number of results is available in the `total` attribute of the returned `ResultList`. If maxResults evaluates as False, it will try to get all issues in batches.
    - fields (str) – comma-separated string of issue fields to include in the results
    - expand (str) – extra information to fetch inside each resource
    - json_result (bool) – JSON response will be returned when this parameter is set to True. Otherwise, `ResultList` will be returned.

    Return type: | dict or `ResultList`

  `search_users`(user, startAt=0, maxResults=50, includeActive=True, includeInactive=False)

    Get a list of user Resources that match the specified search string.

    Parameters:

    - user – a string to match usernames, name or email against.
    - startAt – index of the first user to return.
    - maxResults – maximum number of users to return. If maxResults evaluates as False, it will try to get all items in batches.
    - includeActive – If true, then active users are included in the results.
    - includeInactive – If true, then inactive users are included in the results.

  `security_level`(id)

    Get a security level Resource.

    Parameters: | id – ID of the security level to get

  `server_info`()

    Get a dict of server information for this JIRA instance.

  `service_desk`(id)

    Get a Service Desk Resource from the server.

    Parameters: | id – ID or key of the Service Desk to get

  `service_desks`()

    Get a list of ServiceDesk Resources from the server visible to the current authenticated user.

  `session`(auth=None)

    Get a dict of the current authenticated user’s session information.

  `set_application_property`(key, value)

    Set the application property.

    Parameters:

    - key – key of the property to set
    - value – value to assign to the property

  `set_project_avatar`(project, avatar)

    Set a project’s avatar.

    Parameters:

    - project – ID or key of the project to set the avatar on
    - avatar – ID of the avatar to set

  `set_user_avatar`(username, avatar)

    Set a user’s avatar.

    Parameters:

    - username – the user to set the avatar for
    - avatar – ID of the avatar to set

  `sprint`(id)

    Return the information about a sprint.

    Parameters: | sprint_id (int) – the sprint retrieving issues from
    Return type: | `Sprint`

  `sprint_info`(board_id, sprint_id)

    Return the information about a sprint.

    Parameters:

    - board_id – the board retrieving issues from. Deprecated and ignored.
    - sprint_id – the sprint retrieving issues from

  `sprints`(board_id, extended=False, startAt=0, maxResults=50, state=None)

    Get a list of sprint GreenHopperResources.

    Parameters:

    - board_id (int) – the board to get sprints from
    - extended (bool) – Used only by old GreenHopper API to fetch additional information like startDate, endDate, completeDate, much slower because it requires an additional requests for each sprint. New JIRA Agile API always returns this information without a need for additional requests.
    - startAt (int) – the index of the first sprint to return (0 based)
    - maxResults (int) – the maximum number of sprints to return
    - state (str) – Filters results to sprints in specified states. Valid values: future, active, closed. You can define multiple states separated by commas

    Return type: | list of `Sprint`
    Returns: | (content depends on API version, but always contains id, name, state, startDate and endDate) When old GreenHopper private API is used, paging is not enabled, and startAt, maxResults and state parameters are ignored.

  `sprints_by_name`(id, extended=False)
  `status`(id)

    Get a status Resource from the server.

    Parameters: | id – ID of the status resource to get

  `statuses`()

    Get a list of status Resources from the server.

  `supports_service_desk`()
  `transition_issue`(issue, transition, fields=None, comment=None, worklog=None, **fieldargs)

    Perform a transition on an issue.

    Each keyword argument (other than the predefined ones) is treated as a field name and the argument’s value is treated as the intended value for that field – if the fields argument is used, all other keyword arguments will be ignored. Field values will be set on the issue as part of the transition process.

    Parameters:

    - issue – ID or key of the issue to perform the transition on
    - transition – ID or name of the transition to perform
    - comment – Optional String to add as comment to the issue when performing the transition.
    - fields – a dict containing field names and the values to use. If present, all other keyword arguments will be ignored

  `transitions`(issue, id=None, expand=None)

    Get a list of the transitions available on the specified issue to the current user.

    Parameters:

    - issue – ID or key of the issue to get the transitions from
    - id – if present, get only the transition matching this ID
    - expand – extra information to fetch inside each transition

  `update_filter`(filter_id, name=None, description=None, jql=None, favourite=None)

    Update a filter and return a filter Resource for it.

    Parameters:

    - name – name of the new filter
    - description – useful human readable description of the new filter
    - jql – query string that defines the filter
    - favourite – whether to add this filter to the current user’s favorites

  `update_sprint`(id, name=None, startDate=None, endDate=None, state=None)
  `user`(id, expand=None)

    Get a user Resource from the server.

    Parameters:

    - id – ID of the user to get
    - expand – extra information to fetch inside each resource

  `user_avatars`(username)

    Get a dict of avatars for the specified user.

    Parameters: | username – the username to get avatars for

  `version`(id, expand=None)

    Get a version Resource.

    Parameters:

    - id – ID of the version to get
    - expand – extra information to fetch inside each resource

  `version_count_related_issues`(id)

    Get a dict of the counts of issues fixed and affected by a version.

    Parameters: | id – the version to count issues for

  `version_count_unresolved_issues`(id)

    Get the number of unresolved issues for a version.

    Parameters: | id – ID of the version to count issues for

  `votes`(issue)

    Get a votes Resource from the server.

    Parameters: | issue – ID or key of the issue to get the votes for

  `watchers`(issue)

    Get a watchers Resource from the server for an issue.

    Parameters: | issue – ID or key of the issue to get the watchers for

  `worklog`(issue, id)

    Get a specific worklog Resource from the server.

    Parameters:

    - issue – ID or key of the issue to get the worklog from
    - id – ID of the worklog to get

  `worklogs`(issue)

    Get a list of worklog Resources from the server for an issue.

    Parameters: | issue – ID or key of the issue to get worklogs from

## 6.2. Issue

class `jira.``Issue`(options, session, raw=None)

  Bases: `jira.resources.Resource`

  A JIRA issue.

  `add_field_value`(field, value)

    Add a value to a field that supports multiple values, without resetting the existing values.

    This should work with: labels, multiple checkbox lists, multiple select

    Parameters:

    - field (str) – The field name
    - value – The field’s value

  `delete`(deleteSubtasks=False)

    Delete this issue from the server.

    Parameters: | deleteSubtasks (bool) – if the issue has subtasks, this argument must be set to true for the call to succeed.

  `fields` = None

    Type: | `_IssueFields`

  `id` = None

    Type: | int

  `key` = None

    Type: | str

  `permalink`()

    Get the URL of the issue, the browsable one not the REST one.

    Returns: | URL of the issue
    Return type: | str

  `update`(fields=None, update=None, async_=None, jira=None, notify=True, **fieldargs)

    Update this issue on the server.

    Each keyword argument (other than the predefined ones) is treated as a field name and the argument’s value is treated as the intended value for that field – if the fields argument is used, all other keyword arguments will be ignored.

    JIRA projects may contain many different issue types. Some issue screens have different requirements for fields in an issue. This information is available through the `JIRA.editmeta()` method. Further examples are available here: https://developer.atlassian.com/display/JIRADEV/JIRA+REST+API+Example+-+Edit+issues

    Parameters:

    - fields (dict) – a dict containing field names and the values to use
    - update (dict) – a dict containing update operations to apply
    - fieldargs – keyword arguments will generally be merged into fields, except lists, which will be merged into updates

## 6.3. Priority

class `jira.``Priority`(options, session, raw=None)

  Bases: `jira.resources.Resource`

  Priority that can be set on an issue.

## 6.4. Comment

class `jira.``Comment`(options, session, raw=None)

  Bases: `jira.resources.Resource`

  An issue comment.

  `update`(fields=None, async_=None, jira=None, body='', visibility=None)

    Update this resource on the server.

    Keyword arguments are marshalled into a dict before being sent. If this resource doesn’t support `PUT`, a `JIRAError` will be raised; subclasses that specialize this method will only raise errors in case of user error.

    Parameters: | async – if true the request will be added to the queue so it can be executed later using async_run()

## 6.5. Worklog

class `jira.``Worklog`(options, session, raw=None)

  Bases: `jira.resources.Resource`

  Worklog on an issue.

  `delete`(adjustEstimate=None, newEstimate=None, increaseBy=None)

    Delete this worklog entry from its associated issue.

    Parameters:

    - adjustEstimate – one of `new`, `leave`, `manual` or `auto`. `auto` is the default and adjusts the estimate automatically. `leave` leaves the estimate unchanged by this deletion.
    - newEstimate – combined with `adjustEstimate=new`, set the estimate to this value
    - increaseBy – combined with `adjustEstimate=manual`, increase the remaining estimate by this amount

## 6.6. Watchers

class `jira.``Watchers`(options, session, raw=None)

  Bases: `jira.resources.Resource`

  Watcher information on an issue.

  `delete`(username)

    Remove the specified user from the watchers list.

## 6.7. JIRAError

class `jira.``JIRAError`(status_code=None, text=None, url=None, request=None, response=None, **kwargs)

  Bases: `Exception`

  General error raised for all problems in operation of the client.

  `log_to_tempfile` = True