Jira API

class JiraAPI(base_url: str, api_username: str, api_token: str, configuration: jiratui.config.ApplicationConfiguration)

Implements methods to connect to the Jira REST API provided by the Jira Cloud Platform.

Supported Versions

• https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#version

• https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#version

Versions

• Version 2 and version 3 of the API offer the same collection of operations. However, version 3 provides support for the Atlassian Document Format (ADF) in:

  • body in comments, including where comments are used in issue, issue link, and transition resources.

  • comment in work-logs.

  • description and environment fields in issues.

  • textarea type custom fields (multi-line text fields) in issues. Single line custom fields (textfield) accept a string and don’t handle Atlassian Document Format content.

Initialization

async search_projects(offset: int | None = None, limit: int | None = None, query: str | None = None, order_by: str | None = None, keys: list[str] = None) → dict

Retrieves a paginated list of projects visible to the user making the request.

See Also:

• api-rest-api-3-project-search-get

Parameters:

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page. Must be less than or equal to 100.

• query – filter the results using a literal string. Projects with a matching key or name are returned (case-insensitive).

• order_by – sort the results by a field: key (default), category, issueCount, lastIssueUpdatedTime, name, owner, archivedDate, deletedDate.

• keys – the project keys to filter the results by.

Returns:

A dictionary with the details of the projects.

async get_project_statuses(project_key: str) → list[dict]

Retrieves the valid statuses for a project.

The statuses are grouped by issue type, as each project has a set of valid issue types and each issue type has a set of valid statuses.

See Also:

• api-rest-api-3-project-projectidorkey-statuses-get

Parameters:

project_key – the (case-sensitive) project ID or project key.

Returns:

A list of dictionaries.

async get_issue_types_for_user() → list[dict]

Retrieves all the issue types.

See Also:

• api-rest-api-3-issuetype-get

Returns:

A list of dictionaries with the details of the types of issues.

async get_statuses(project_id: str | None = None, offset: int | None = None, limit: int | None = None) → dict

Retrieves a paginated list of statuses that match a search on project.

See Also:

• api-rest-api-3-statuses-search-get

Parameters:

• project_id – the ID of the project the status is part of or null for global statuses.

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page. The Default is 200.

Returns:

A dictionary with the statuses.

async get_project(key: str) → dict

Retrieves the details of a project.

See Also:

• api-rest-api-3-project-projectidorkey-get

Parameters:

key – the project ID or project key (case-sensitive).

Returns:

A dictionary with the details of the project.

async user_assignable_search(project_id_or_key: str | None = None, issue_key: str | None = None, issue_id: str | None = None, account_id: str | None = None, offset: int | None = None, limit: int | None = 50, query: str | None = None) → list[dict]

Retrieves a list of users that can be assigned to an issue.

See Also:

• api-rest-api-3-user-assignable-search-get

Parameters:

• project_id_or_key – the project ID or project key (case-sensitive). Required, unless issue_key or issue_id is specified.

• issue_key – the key of the issue. Required, unless issueId or project is specified.

• issue_id – the ID of the issue. Required, unless issueKey or project is specified.

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return. Default is 50.

• query – a string that is matched against user attributes, such as displayName, and emailAddress, to find relevant users. The string can match the prefix of the attribute’s value. For example, query=john matches a user with a displayName of John Smith and a user with an emailAddress of johnson@example.com. Required, unless username or accountId is specified.

• account_id – a query string that is matched exactly against user accountId. Required, unless query is specified.

Returns:

A list of dictionaries with the details of the users.

async user_assignable_multi_projects(project_keys: list[str] = None, query: str | None = None, offset: int | None = None, limit: int | None = None) → list[dict]

Retrieves the users who can be assigned issues in one or more projects.

See Also:

• api-rest-api-3-user-assignable-multiprojectsearch-get

Parameters:

• project_keys – a list of project keys (case-sensitive). This parameter accepts a comma-separated list.

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page. Default is 50.

• query – a string that is matched against user attributes, such as displayName, and emailAddress, to find relevant users. The string can match the prefix of the attribute’s value. For example, query=john matches a user with a displayName of John Smith and a user with an emailAddress of johnson@example.com. Required, unless username or accountId is specified.

Returns:

A list of dictionaries with the details of the users.

async get_issue(issue_id_or_key: str, fields: str | None = None, properties: str | None = None) → dict

Retrieves the details of a work item by ID or key.

The issue is identified by its ID or key, however, if the identifier doesn’t match an issue, a case-insensitive search and check for moved issues is performed. If a matching issue is found its details are returned, a 302 or other redirect is not returned. The issue key returned in the response is the key of the issue found.

See Also:

• api-rest-api-3-issue-issueidorkey-get

Parameters:

• issue_id_or_key – the ID or case-sensitive key of the work item to retrieve.

• fields –

  a list of fields to return for the issue. This parameter accepts a comma-separated list. Use it to retrieve a subset of fields. Allowed values:

  *all Returns all fields. *navigable Returns navigable fields.

  Any issue field, prefixed with a minus to exclude.

• properties –

  a list of issue properties to return for the issue. This parameter accepts a comma-separated list. Allowed values:

  *all Returns all issue properties. Any issue property key, prefixed with a minus to exclude.

Returns:

A dictionary with the detail sof the issue.

async issue_picker(query: str, project_id: str | None = None, show_sub_tasks: bool = True, current_issue_key: str | None = None) → dict

Retrieves lists of issues matching a query string. Use this resource to provide auto-completion suggestions when the user is looking for an issue using a word or string.

Parameters:

• query – a string to match against text fields in the issue such as title, description, or comments.

• project_id – the ID of a project that suggested issues must belong to.

• show_sub_tasks – indicates whether to include subtasks in the suggestions list. The default is True.

• current_issue_key – the key of an issue to exclude from search results. For example, the issue the user is viewing when they perform this query.

Returns:

A dictionary with 2 lists of issues suggested for use in auto-completion.

async get_issue_remote_links(issue_id_or_key: str, global_id: str | None = None) → list[dict]

Retrieves the remote issue links for an issue.

See Also:

• api-rest-api-3-issue-issueidorkey-remotelink-get

Parameters:

• issue_id_or_key – the key or ID of the issue whose remote links we want to retrieve.

• global_id – the global ID of the remote issue link.

Returns:

A list of dictionaries.

async create_issue_remote_link(issue_id_or_key: str, url: str, title: str) → None

Creates or updates a remote issue link for an issue.

See Also:

• api-rest-api-3-issue-issueidorkey-remotelink-post

Parameters:

• issue_id_or_key – the ID or case-sensitive key of the work item

• url – the URL of the link.

• title – the title of the link.

Returns:

Nothing.

async delete_issue_remote_link(issue_id_or_key: str, link_id: str) → None

Deletes a web link associated to a work item.

See Also:

• api-rest-api-3-issue-issueidorkey-remotelink-linkid-delete

Parameters:

• issue_id_or_key – the ID or case-sensitive key of the work item

• link_id – the IF of the link.

Returns:

Nothing.

async search_issues(project_key: str | None = None, created_from: datetime.date | None = None, created_until: datetime.date | None = None, updated_from: datetime.date | None = None, updated_until: datetime.date | None = None, status: int | None = None, assignee: str | None = None, issue_type: int | None = None, jql_query: str | None = None, search_in_active_sprint: bool = False, fields: list[str] | None = None, next_page_token: str | None = None, offset: int | None = None, limit: int | None = None, order_by: jiratui.models.WorkItemsSearchOrderBy | None = None) → dict

Searches for issues using JQL. Recent updates might not be immediately visible in the returned search results.

See Also:

• api-rest-api-3-search-jql-post

Parameters:

• project_key – search items that belong to the project with this (case-sensitive) key.

• created_from – search items created from this date forward.

• created_until – search items created until this date.

• updated_from – search items updated from this date forward.

• updated_until – search items updated until this date

• status – search items with this status id.

• assignee – search items assigned to this user (by account id).

• issue_type – search items with this type id.

• jql_query – a JQL expression to filter items.

• search_in_active_sprint – if True only work items that belong to the currently active sprint will be retrieved.

• fields – retrieve these fields for every item found.

• next_page_token – an optional token to retrieve the next page of results.

• offset – N/A

• limit – retrieve this max number of results per page.

• order_by – sort the items according to these criteria. This requirement needs to be placed at the end of the JQL query, otherwise the JQL will be invalid. Possible values are: - order by created asc - order by created desc - order by priority asc - order by priority desc - order by key asc - order by key desc

Returns:

A dictionary with the results.

async work_items_search_approximate_count(project_key: str | None = None, created_from: datetime.date | None = None, created_until: datetime.date | None = None, updated_from: datetime.date | None = None, status: int | None = None, assignee: str | None = None, issue_type: int | None = None, jql_query: str | None = None) → dict

Provides an estimated count of the issues that match the JQL. Recent updates might not be immediately visible in the returned output. This endpoint requires JQL to be bounded.

See Also:

• api-rest-api-3-search-approximate-count-post

Important

This is only available for the Jira cloud platform. For on-premises we need another way or to disable the feature.

Parameters:

• project_key – search items that belong to the project with this (case-sensitive) key.

• created_from – search items created from this date forward.

• created_until – search items created until this date.

• updated_from – search items updated from this date forward.

• status – search items with this status id.

• assignee – search items assigned to this user (by account id).

• issue_type – search items with this type id.

• jql_query – a JQL expression to filter items.

Returns:

A dictionary with the estimated number of items that match the search criteria.

async evaluate_expression(expression: str, issue_key: str = None, project_key: str = None) → dict

Evaluates a JQL expression.

See Also:

• api-rest-api-3-expression-evaluate-post

Parameters:

• expression – a JQL expression.

• issue_key – a case-sensitive work item key.

• project_key – a case-sensitive project key.

Returns:

A dictionary with the result of the evaluation.

async global_settings() → dict

Retrieves the global settings in Jira.

These settings determine whether optional features (for example, subtasks, time tracking, and others) are enabled. If time tracking is enabled, this operation also returns the time tracking configuration.

See Also:

• api-rest-api-3-configuration-get

Returns:

A dictionary with the settings.

async server_info() → dict

Retrieves information of the Jira server.

See Also:

• api-group-server-info

Returns:

A dictionary with the details.

async myself() → dict

Retrieves information of the Jira user connecting to the Jira server.

See Also:

• api-rest-api-3-myself-get

Returns:

A dictionary with the details.

async search_users(offset: int | None = None, limit: int | None = None) → list[dict]

Retrieves a list of all users, including active users, inactive users and previously deleted users that have an Atlassian account.

See Also:

• api-rest-api-3-users-search-get

Parameters:

• offset – the index of the first item to return.

• limit – the maximum number of items to return (limited to 1000).

Returns:

A list of dictionaries with the details of the users.

async user_search(username: str | None = None, query: str | None = None, offset: int | None = None, limit: int | None = None) → list[dict]

Retrieves a list of active users that match the search string and property.

See Also:

• api-rest-api-3-user-search-get

Parameters:

• username – the username to filter users.

• query – a query string that is matched against user attributes (displayName, and emailAddress) to find relevant users.

• offset – the index of the first item to return.

• limit – the maximum number of items to return (limited to 1000).

Returns:

A list of dictionaries with the details of the users.

async user_picker(query: str, limit: int | None = None) → dict

Retrieves a list of users whose attributes match the query term.

The returned object includes the html field where the matched query term is highlighted with the HTML strong tag. A list of account IDs can be provided to exclude users from the results.

Important

This operation takes the users in the range defined by maxResults, up to the thousandth user, and then returns only the users from that range that match the query term. This means the operation usually returns fewer users than specified in maxResults

Parameters:

• query – query: string that is matched against user attributes, such as displayName, and emailAddress, to find relevant users.

• limit – the maximum number of items to return. The total number of matched users is returned in the total key. The default value is 50.

Returns:

A dictionary with a users key that contains the list of users found.

async get_groups_in_bulk(offset: int | None = None, limit: int | None = None, groups_ids: list[str] | None = None, groups_names: list[str] | None = None) → dict

Retrieves a paginated list of groups.

See Also:

• api-rest-api-3-group-bulk-get

Parameters:

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page. The default is 50.

• groups_ids – a list of groups IDs to retrieve.

• groups_names – a list of groups names to retrieve.

Returns:

A dictionary with the results of the current page.

async get_users_in_group(group_id: str, offset: int | None = None, limit: int | None = None) → dict

Retrieves a paginated list of all (active) users in a group.

Note

Note that users are ordered by username, however the username is not returned in the results due to privacy reasons.

See Also:

• api-rest-api-3-group-member-get

• default-groups-and-permissions

Parameters:

• group_id – The ID of the group.

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page (number should be between 1 and 50).

Returns:

A dictionary with the details of the users.

async get_user(account_id: str) → dict

Retrieves the details of a single user.

See Also:

• api-rest-api-3-user-get

Parameters:

account_id – the account ID of the user, which uniquely identifies the user across all Atlassian products.

Returns:

A dictionary with the details of the user

Examples

get_user(account_id='5b10ac8d82e05b22cc7d4ef5')

async add_comment(issue_id_or_key: str, message: str | dict) → dict

Adds a comment to an issue.

See Also:

• api-rest-api-3-issue-issueidorkey-comment-post

Parameters:

• issue_id_or_key – the case-sensitive key of the work item whose comment we want to retrieve.

• message – an ADF dictionary with the message of the comment or, a string with the comment if we are connecting to Jira DC API or Jira Cloud Platform API v2.

Returns:

A dictionary with the details of the comment.

async get_comment(issue_id_or_key: str, comment_id: str) → dict

Retrieves the detail sof a comment.

See Also:

• api-rest-api-3-issue-issueidorkey-comment-id-get

Parameters:

• issue_id_or_key – the case-sensitive key of the work item whose comment we want to retrieve.

• comment_id – the ID of the comment.

Returns:

A dictionary with the details of the comment.

async get_comments(issue_id_or_key: str, offset: int | None = None, limit: int | None = None) → dict

Retrieves the comments of a work item.

See Also:

• api-rest-api-3-issue-issueidorkey-comment-get

Parameters:

• issue_id_or_key – the case-sensitive key of the work item whose comment we want to retrieve.

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page. The default is 50.

Returns:

A dictionary with the details of the comments.

async delete_comment(issue_id_or_key: str, comment_id: str) → None

Deletes a comment.

See Also:

• api-rest-api-3-issue-issueidorkey-comment-id-delete

Parameters:

• issue_id_or_key – the case-sensitive key of the work item whose comment we want to delete.

• comment_id – the ID of the comment.

Returns:

Nothing if the comment is deleted; an exception otherwise.

async issue_edit_metadata(issue_id_or_key: str) → dict

Retrieves the edit screen fields for an issue that are visible to and editable by the user.

See Also:

• api-rest-api-3-issue-issueidorkey-editmeta-get

Parameters:

issue_id_or_key – the case-sensitive key of the work item.

Returns:

A dictionary with the metadata.

async update_issue(issue_id_or_key: str, payload: dict) → dict

Updates a work item.

See Also:

• api-rest-api-3-issue-issueidorkey-put

Parameters:

• issue_id_or_key – the case-sensitive key of the work item.

• payload – the fields and their values.

Returns:

A dictionary with the details of the work item after the update.

async create_work_item(fields: dict) → dict

Creates a work item.

The current version of this method does not implement support for setting the value of the environment field. If we want to change this then we would need to take care of the difference in the format of the environment field for API v2 (does nto support ADF) and v3 (supports ADF).

See Also:

• api-rest-api-3-issue-post

Parameters:

fields – a dictionary with the fields and their values to create the item.

Returns:

A dictionary with the details of the new item.

async delete_work_item(issue_id_or_key: str, delete_subtasks: bool = True) → None

Deletes a work item.

An issue cannot be deleted if it has one or more subtasks. To delete an issue with subtasks, set the query parameter deleteSubtasks. This causes the issue’s subtasks to be deleted with the issue.

See Also:

• api-rest-api-3-issue-issueidorkey-delete

Parameters:

• issue_id_or_key – the id of the work item we want to delete.

• delete_subtasks – if True (default) any subtask associated to the work item will also be deleted.

Returns:

None if successful (HTTP 204 was returned); an exception otherwise.

async transitions(issue_id_or_key: str) → dict

Retrieves the applicable transitions for a work item.

See Also:

• api-rest-api-3-issue-issueidorkey-transitions-get

Parameters:

issue_id_or_key – the case-sensitive key of the work item.

Returns:

A dictionary with the details of the transitions.

async transition_issue(issue_id_or_key: str, transition_id: str) → None

Performs an issue transition.

See Also:

• api-rest-api-3-issue-issueidorkey-transitions-post

Parameters:

• issue_id_or_key – the case-sensitive key of the work item.

• transition_id – the ID of the status transition.

Returns:

None

async create_issue_link(left_issue_key: str, right_issue_key: str, link_type: str, link_type_id: str) → None

Creates a link between two issues. Use this operation to indicate a relationship between two issues and optionally add a comment to the “from” (outward) issue

The current version of this method does not implement support for adding a comment in the link between the 2 work items. If we want to change this then we would need to take care of the difference in the format of the comment field for API v2 (does nto support ADF) and v3 (supports ADF).

See Also:

• api-rest-api-3-issuelink-post

Parameters:

• left_issue_key – the case-sensitive key of the work item.

• right_issue_key – the case-sensitive key of the work item.

• link_type – the type of link.

• link_type_id – the ID of the type of link.

Returns:

None.

async issue_link_types() → dict

Retrieves a list of all issue link types.

See Also:

• api-rest-api-3-issuelinktype-get

Returns:

A dictionary with the types of links between work items.

async get_issue_create_meta(project_id_or_key: str, issue_type_id: str, offset: int = 0, limit: int | None = None) → dict

Retrieves a page of field metadata for a specified project and type of issue id.

See Also:

• api-rest-api-3-issue-createmeta-projectidorkey-issuetypes-issuetypeid-get

Parameters:

• project_id_or_key – the case-sensitive key of the project.

• issue_type_id – the ID of a type of issue.

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page.

Returns:

A dictionary with the metadata to create work items of a given project and type.

add_attachment_to_issue(issue_id_or_key: str, filename, file_name: str, mime_type: str | None = None) → list[dict]

Adds an attachment to an issue.

See Also:

• api-rest-api-3-issue-issueidorkey-attachments-post

Attachments are posted as multipart/form-data (RFC 1867).

Parameters:

• issue_id_or_key – the case-sensitive key of the work item.

• filename – the full name of the file to upload.

• file_name – the name of the file to upload.

• mime_type – the MIME type of the file.

Returns:

A list of dictionaries with the results.

async delete_attachment(attachment_id: str) → None

Deletes an attachment from an issue.

See Also:

• api-rest-api-3-attachment-id-delete

Parameters:

attachment_id – The ID of the attachment.

Returns:

None; HTTP 204 if successful or an exception otherwise.

async get_attachment(attachment_id: str) → dict

Retrieves an attachment (metadata).

See Also:

• api-rest-api-3-attachment-id-get

• api-rest-api-2-attachment-id-get

Parameters:

attachment_id – the ID of the attachment.

Returns:

A dictionary with the metadata of the attachment.

async get_attachment_content(attachment_id: str) → Any

Retrieves the contents of an attachment.

See Also:

• api-rest-api-3-attachment-content-id-get

• api-rest-api-2-attachment-content-id-get

Parameters:

attachment_id – The ID of the attachment.

Returns:

A bytes representation of the attachment’s content.

async get_issue_work_log(issue_id_or_key: str, offset: int | None = None, limit: int | None = None) → dict

Retrieves work logs for an issue (ordered by created time), starting from the oldest worklog or from the worklog started on or after a date and time.

Important

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

See Also:

• api-rest-api-3-issue-issueidorkey-worklog-get

Parameters:

• issue_id_or_key – the case-sensitive key of the work item.

• offset – the index of the first item to return in a page of results (page offset).

• limit – the maximum number of items to return per page. The default is 5000.

Returns:

A dictionary with the worklog of the work item.

async add_issue_work_log(issue_id_or_key: str, time_spent: str, started: datetime.datetime, time_remaining: str | None = None, comment: str | None = None) → dict

Adds a worklog to an issue.

Important

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

See Also:

• api-rest-api-3-issue-issueidorkey-worklog-post

Parameters:

• issue_id_or_key – the case-sensitive key of the work item.

• comment – a comment about the worklog. Optional when creating or updating a worklog.

• started – the datetime on which the worklog effort was started. Required when creating a worklog. Optional when updating a worklog.

• time_spent – the time spent working on the issue as days (#d), hours (#h), or minutes (#m or #). Required when creating a worklog if timeSpentSeconds isn’t provided. Optional when updating a worklog. Cannot be provided if timeSpentSecond is provided.

• time_remaining – the value to set as the issue’s remaining time estimate, as days (#d), hours (#h), or minutes (#m or #). For example, 2d. Required when adjustEstimate is new.

Returns:

A dictionary with the worklog’s details.

async delete_work_log(issue_id_or_key: str, worklog_id: str) → bool

Deletes a worklog from an issue.

Important

Time tracking must be enabled in Jira, otherwise this operation returns an error. For more information, see Configuring time tracking.

See Also:

• api-rest-api-3-issue-issueidorkey-worklog-id-delete

Parameters:

• issue_id_or_key – the ID or key of the issue.

• worklog_id – the ID of the worklog.

Returns:

True if the operation succeeds.

async get_fields() → list[dict]

Retrieves system and custom issue fields according to the following rules.

• Fields that cannot be added to the issue navigator are always returned.

• Fields that cannot be placed on an issue screen are always returned.

• Fields that depend on global Jira settings are only returned if the setting is enabled. That is, timetracking fields, subtasks, votes, and watches.

• For all other fields, this operation only returns the fields that the user has permission to view (that is, the field is used in at least one project that the user has Browse Projects project permission for.)

See Also:

• api-rest-api-3-field-get

Returns:

A list of dictionaries.

async get_jql_autocomplete_suggestions(field_name: str | None = None, field_value: str | None = None, predicate_name: str | None = None, predicate_value: str | None = None) → dict

Retrieves the JQL search auto complete suggestions for a field.

Suggestions can be obtained by providing:

• fieldName to get a list of all values for the field.

• fieldName and fieldValue to get a list of values containing the text in fieldValue.

• fieldName and predicateName to get a list of all predicate values for the field.

• fieldName, predicateName, and predicateValue to get a list of predicate values containing the text in predicateValue.

Parameters:

• field_name – a field name to get a list of all values for the field.

• field_value – a partial field item name entered by the user.

• predicate_name – the name of the [CHANGED operator predicate](https://confluence.atlassian.com/x/hQORLQ#Advancedsearching-operatorsreference-CHANGEDCHANGED) for which the suggestions are generated. The valid predicate operators are by, from, and to.

• predicate_value – the partial predicate item name entered by the user.

Returns:

List of suggestions or None if request fails.