Atlassian Jira Project API
The Atlassian Jira Project API enables creating, managing, and configuring projects within Jira including roles and permissions.
OpenAPI Specification
components:
schemas:
PageBeanProject:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Project'
readOnly: true
type: array
type: object
ProjectType:
additionalProperties: false
description: Details about a project type.
properties:
color:
description: The color of the project type.
readOnly: true
type: string
descriptionI18nKey:
description: The key of the project type's description.
readOnly: true
type: string
formattedKey:
description: The formatted key of the project type.
readOnly: true
type: string
icon:
description: The icon of the project type.
readOnly: true
type: string
key:
description: The key of the project type.
readOnly: true
type: string
type: object
Project:
additionalProperties: false
description: Details about a project.
properties:
archived:
description: Whether the project is archived.
readOnly: true
type: boolean
archivedBy:
allOf:
- $ref: '#/components/schemas/User'
description: The user who archived the project.
readOnly: true
archivedDate:
description: The date when the project was archived.
format: date-time
readOnly: true
type: string
assigneeType:
description: The default assignee when creating issues for this project.
enum:
- PROJECT_LEAD
- UNASSIGNED
readOnly: true
type: string
avatarUrls:
allOf:
- $ref: '#/components/schemas/AvatarUrlsBean'
description: The URLs of the project's avatars.
readOnly: true
components:
description: List of the components contained in the project.
items:
$ref: '#/components/schemas/ProjectComponent'
readOnly: true
type: array
deleted:
description: Whether the project is marked as deleted.
readOnly: true
type: boolean
deletedBy:
allOf:
- $ref: '#/components/schemas/User'
description: The user who marked the project as deleted.
readOnly: true
deletedDate:
description: The date when the project was marked as deleted.
format: date-time
readOnly: true
type: string
description:
description: A brief description of the project.
readOnly: true
type: string
email:
description: An email address associated with the project.
type: string
expand:
description: >-
Expand options that include additional project details in the
response.
readOnly: true
type: string
xml:
attribute: true
favourite:
description: Whether the project is selected as a favorite.
type: boolean
id:
description: The ID of the project.
type: string
insight:
allOf:
- $ref: '#/components/schemas/ProjectInsight'
description: Insights about the project.
readOnly: true
isPrivate:
description: >-
Whether the project is private from the user's perspective. This
means the user can't see the project or any associated issues.
readOnly: true
type: boolean
issueTypeHierarchy:
allOf:
- $ref: '#/components/schemas/Hierarchy'
description: The issue type hierarchy for the project.
readOnly: true
issueTypes:
description: List of the issue types available in the project.
items:
$ref: '#/components/schemas/IssueTypeDetails'
readOnly: true
type: array
key:
description: The key of the project.
readOnly: true
type: string
landingPageInfo:
allOf:
- $ref: '#/components/schemas/ProjectLandingPageInfo'
description: The project landing page info.
readOnly: true
lead:
allOf:
- $ref: '#/components/schemas/User'
description: The username of the project lead.
readOnly: true
name:
description: The name of the project.
readOnly: true
type: string
permissions:
allOf:
- $ref: '#/components/schemas/ProjectPermissions'
description: User permissions on the project
readOnly: true
projectCategory:
allOf:
- $ref: '#/components/schemas/ProjectCategory'
description: The category the project belongs to.
readOnly: true
projectTypeKey:
description: >-
The [project
type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes)
of the project.
enum:
- software
- service_desk
- business
readOnly: true
type: string
properties:
additionalProperties:
readOnly: true
description: Map of project properties
readOnly: true
type: object
retentionTillDate:
description: The date when the project is deleted permanently.
format: date-time
readOnly: true
type: string
roles:
additionalProperties:
format: uri
readOnly: true
type: string
description: >-
The name and self URL for each role defined in the project. For more
information, see [Create project role](#api-rest-api-3-role-post).
readOnly: true
type: object
self:
description: The URL of the project details.
format: uri
readOnly: true
type: string
simplified:
description: Whether the project is simplified.
readOnly: true
type: boolean
style:
description: The type of the project.
enum:
- classic
- next-gen
readOnly: true
type: string
url:
description: >-
A link to information about this project, such as project
documentation.
readOnly: true
type: string
uuid:
description: Unique ID for next-gen projects.
format: uuid
readOnly: true
type: string
versions:
description: >-
The versions defined in the project. For more information, see
[Create version](#api-rest-api-3-version-post).
items:
$ref: '#/components/schemas/Version'
readOnly: true
type: array
type: object
xml:
name: project
ProjectAvatars:
additionalProperties: false
description: List of project avatars.
properties:
custom:
description: List of avatars added to Jira. These avatars may be deleted.
items:
$ref: '#/components/schemas/Avatar'
readOnly: true
type: array
system:
description: List of avatars included with Jira. These avatars cannot be deleted.
items:
$ref: '#/components/schemas/Avatar'
readOnly: true
type: array
type: object
PageBeanComponentWithIssueCount:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/ComponentWithIssueCount'
readOnly: true
type: array
type: object
ContainerForProjectFeatures:
additionalProperties: false
description: The list of features on a project.
properties:
features:
description: The project features.
items:
$ref: '#/components/schemas/ProjectFeature'
type: array
type: object
PropertyKeys:
additionalProperties: false
description: List of property keys.
properties:
keys:
description: Property key details.
items:
$ref: '#/components/schemas/PropertyKey'
readOnly: true
type: array
type: object
EntityProperty:
additionalProperties: false
description: >-
An entity property, for more information see [Entity
properties](https://developer.atlassian.com/cloud/jira/platform/jira-entity-properties/).
properties:
key:
description: The key of the property. Required on create and update.
type: string
value:
description: The value of the property. Required on create and update.
type: object
ProjectRole:
additionalProperties: false
description: Details about the roles in a project.
properties:
actors:
description: The list of users who act in this role.
items:
$ref: '#/components/schemas/RoleActor'
readOnly: true
type: array
admin:
description: Whether this role is the admin role for the project.
readOnly: true
type: boolean
currentUserRole:
description: Whether the calling user is part of this role.
type: boolean
default:
description: Whether this role is the default role for the project
readOnly: true
type: boolean
description:
description: The description of the project role.
readOnly: true
type: string
id:
description: The ID of the project role.
format: int64
readOnly: true
type: integer
name:
description: The name of the project role.
type: string
roleConfigurable:
description: Whether the roles are configurable for this project.
readOnly: true
type: boolean
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: >-
The scope of the role. Indicated for roles associated with [next-gen
projects](https://confluence.atlassian.com/x/loMyO).
readOnly: true
self:
description: The URL the project role details.
format: uri
readOnly: true
type: string
translatedName:
description: The translated name of the project role.
type: string
type: object
PageBeanVersion:
additionalProperties: false
description: A page of items.
properties:
isLast:
description: Whether this is the last page.
readOnly: true
type: boolean
maxResults:
description: The maximum number of items that could be returned.
format: int32
readOnly: true
type: integer
nextPage:
description: If there is another page of results, the URL of the next page.
format: uri
readOnly: true
type: string
self:
description: The URL of the page.
format: uri
readOnly: true
type: string
startAt:
description: The index of the first item returned.
format: int64
readOnly: true
type: integer
total:
description: The number of items returned.
format: int64
readOnly: true
type: integer
values:
description: The list of items.
items:
$ref: '#/components/schemas/Version'
readOnly: true
type: array
type: object
ProjectEmailAddress:
additionalProperties: false
description: A project's sender email address.
properties:
emailAddress:
description: The email address.
type: string
emailAddressStatus:
description: When using a custom domain, the status of the email address.
items:
type: string
type: array
type: object
ProjectIssueTypeHierarchy:
additionalProperties: false
description: The hierarchy of issue types within a project.
properties:
hierarchy:
description: Details of an issue type hierarchy level.
items:
$ref: '#/components/schemas/ProjectIssueTypesHierarchyLevel'
readOnly: true
type: array
projectId:
description: The ID of the project.
format: int64
readOnly: true
type: integer
type: object
SecurityScheme:
additionalProperties: false
description: Details about a security scheme.
properties:
defaultSecurityLevelId:
description: The ID of the default security level.
format: int64
readOnly: true
type: integer
description:
description: The description of the issue security scheme.
readOnly: true
type: string
id:
description: The ID of the issue security scheme.
format: int64
readOnly: true
type: integer
levels:
items:
$ref: '#/components/schemas/SecurityLevel'
type: array
name:
description: The name of the issue security scheme.
readOnly: true
type: string
self:
description: The URL of the issue security scheme.
readOnly: true
type: string
type: object
NotificationScheme:
additionalProperties: false
description: Details about a notification scheme.
properties:
description:
description: The description of the notification scheme.
type: string
expand:
description: >-
Expand options that include additional notification scheme details
in the response.
type: string
id:
description: The ID of the notification scheme.
format: int64
type: integer
name:
description: The name of the notification scheme.
type: string
notificationSchemeEvents:
description: The notification events and associated recipients.
items:
$ref: '#/components/schemas/NotificationSchemeEvent'
type: array
projects:
description: The list of project IDs associated with the notification scheme.
items:
format: int64
type: integer
type: array
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: The scope of the notification scheme.
self:
type: string
type: object
PermissionScheme:
additionalProperties: true
description: Details of a permission scheme.
properties:
description:
description: A description for the permission scheme.
type: string
expand:
description: The expand options available for the permission scheme.
readOnly: true
type: string
id:
description: The ID of the permission scheme.
format: int64
readOnly: true
type: integer
name:
description: The name of the permission scheme. Must be unique.
type: string
permissions:
description: >-
The permission scheme to create or update. See [About permission
schemes and
grants](../api-group-permission-schemes/#about-permission-schemes-and-grants)
for more information.
items:
$ref: '#/components/schemas/PermissionGrant'
type: array
scope:
allOf:
- $ref: '#/components/schemas/Scope'
description: The scope of the permission scheme.
self:
description: The URL of the permission scheme.
format: uri
readOnly: true
type: string
required:
- name
type: object
ProjectIssueSecurityLevels:
additionalProperties: false
description: List of issue level security items in a project.
properties:
levels:
description: Issue level security items list.
items:
$ref: '#/components/schemas/SecurityLevel'
readOnly: true
type: array
required:
- levels
type: object
externalDocs:
description: Find out more about Atlassian products and services.
url: http://www.atlassian.com
info:
contact:
email: [email protected]
description: Needs description.
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
termsOfService: http://atlassian.com/terms/
title: 'Atlassian rest/api/3/project/'
version: 1001.0.0-SNAPSHOT-67b5c6e5f3598d7ec1649016d026468ab2838a77
openapi: 3.0.1
paths:
/rest/api/3/project/recent:
get:
deprecated: false
description: >-
Returns a list of up to 20 projects recently viewed by the user that are
still visible to the user.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** Projects
are returned only where the user has one of:<br><br> * *Browse
Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the
project.<br> * *Administer Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the
project.<br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianGetrecent
parameters:
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expanded
options include:
* `description` Returns the project description.
* `projectKeys` Returns all project keys associated with a project.
* `lead` Returns information about the project lead.
* `issueTypes` Returns all issue types associated with the project.
* `url` Returns the URL associated with the project.
* `permissions` Returns the permissions associated with the project.
* `insight` EXPERIMENTAL. Returns the insight details of total issue count and last issue update time for the project.
* `*` Returns the project with all available expand options.
in: query
name: expand
schema:
type: string
- description: >-
EXPERIMENTAL. A list of project properties to return for the
project. This parameter accepts a comma-separated list. Invalid
property names are ignored.
in: query
name: properties
schema:
items:
$ref: '#/components/schemas/StringList'
type: array
responses:
'200':
content:
application/json:
example: >-
[{"avatarUrls":{"16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10000","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10000","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10000","48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10000"},"id":"10000","insight":{"lastIssueUpdateTime":1619069825000,"totalIssueCount":100},"key":"EX","name":"Example","projectCategory":{"description":"First
Project
Category","id":"10000","name":"FIRST","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000"},"self":"https://your-domain.atlassian.net/rest/api/3/project/EX","simplified":false,"style":"CLASSIC"},{"avatarUrls":{"16x16":"https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&pid=10001","24x24":"https://your-domain.atlassian.net/secure/projectavatar?size=small&pid=10001","32x32":"https://your-domain.atlassian.net/secure/projectavatar?size=medium&pid=10001","48x48":"https://your-domain.atlassian.net/secure/projectavatar?size=large&pid=10001"},"id":"10001","insight":{"lastIssueUpdateTime":1619069825000,"totalIssueCount":100},"key":"ABC","name":"Alphabetical","projectCategory":{"description":"First
Project
Category","id":"10000","name":"FIRST","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000"},"self":"https://your-domain.atlassian.net/rest/api/3/project/ABC","simplified":false,"style":"CLASSIC"}]
schema:
items:
$ref: '#/components/schemas/Project'
type: array
description: Returned if the request is successful.
'400':
description: Returned if the request is not valid.
'401':
description: Returned if the authentication credentials are incorrect or missing.
security:
- basicAuth: []
- OAuth2:
- read:jira-work
- {}
summary: Atlassian Get Recent Projects
tags:
- Projects
x-atlassian-data-security-policy:
- app-access-rule-exempt: false
x-atlassian-oauth2-scopes:
- scheme: OAuth2
scopes:
- read:jira-work
state: Current
- scheme: OAuth2
scopes:
- read:issue-type:jira
- read:project:jira
- read:project.property:jira
- read:user:jira
- read:application-role:jira
- read:avatar:jira
- read:group:jira
- read:issue-type-hierarchy:jira
- read:project-category:jira
- read:project-version:jira
- read:project.component:jira
state: Beta
x-experimental: true
x-atlassian-connect-scope: READ
/rest/api/3/project/search:
get:
deprecated: false
description: >-
Returns a [paginated](#pagination) list of projects visible to the
user.<br><br>This operation can be accessed
anonymously.<br><br>**[Permissions](#permissions) required:** Projects
are returned only where the user has one of:<br><br> * *Browse
Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the
project.<br> * *Administer Projects* [project
permission](https://confluence.atlassian.com/x/yodKLg) for the
project.<br> * *Administer Jira* [global
permission](https://confluence.atlassian.com/x/x4dKLg).
operationId: atlassianSearchprojects
parameters:
- description: >-
The index of the first item to return in a page of results (page
offset).
in: query
name: startAt
schema:
default: 0
format: int64
type: integer
- description: The maximum number of items to return per page.
in: query
name: maxResults
schema:
default: 50
format: int32
type: integer
- description: |-
[Order](#ordering) the results by a field.
* `category` Sorts by project category. A complete list of category IDs is found using [Get all project categories](#api-rest-api-3-projectCategory-get).
* `issueCount` Sorts by the total number of issues in each project.
* `key` Sorts by project key.
* `lastIssueUpdatedTime` Sorts by the last issue update time.
* `name` Sorts by project name.
* `owner` Sorts by project lead.
* `archivedDate` EXPERIMENTAL. Sorts by project archived date.
* `deletedDate` EXPERIMENTAL. Sorts by project deleted date.
in: query
name: orderBy
schema:
default: key
enum:
- category
- '-category'
- +category
- key
- '-key'
- +key
- name
- '-name'
- +name
- owner
- '-owner'
- +owner
- issueCount
- '-issueCount'
- +issueCount
- lastIssueUpdatedDate
- '-lastIssueUpdatedDate'
- +lastIssueUpdatedDate
- archivedDate
- +archivedDate
- '-archivedDate'
- deletedDate
- +deletedDate
- '-deletedDate'
type: string
- description: >-
The project IDs to filter the results by. To include multiple IDs,
provide an ampersand-separated list. For example,
`id=10000&id=10001`. Up to 50 project IDs can be provided.
in: query
name: id
schema:
items:
format: int64
type: integer
type: array
uniqueItems: true
- description: >-
The project keys to filter the results by. To include multiple keys,
provide an ampersand-separated list. For example, `keys=PA&keys=PB`.
Up to 50 project keys can be provided.
in: query
name: keys
schema:
items:
default: ''
type: string
type: array
uniqueItems: true
- description: >-
Filter the results using a literal string. Projects with a matching
`key` or `name` are returned (case insensitive).
in: query
name: query
schema:
type: string
- description: >-
Orders results by the [project
type](https://confluence.atlassian.com/x/GwiiLQ#Jiraapplicationsoverview-Productfeaturesandprojecttypes).
This parameter accepts a comma-separated list. Valid values are
`business`, `service_desk`, and `software`.
in: query
name: typeKey
schema:
type: string
- description: >-
The ID of the project's category. A complete list of category IDs is
found using the [Get all project
categories](#api-rest-api-3-projectCategory-get) operation.
in: query
name: categoryId
schema:
format: int64
type: integer
- description: |-
Filter results by projects for which the user can:
* `view` the project, meaning that they have one of the following permissions:
* *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.
* *Administer projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.
* *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
* `browse` the project, meaning that they have the *Browse projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.
* `edit` the project, meaning that they have one of the following permissions:
* *Administer projects* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project.
* *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
* `create` the project, meaning that they have the *Create issues* [project permission](https://confluence.atlassian.com/x/yodKLg) for the project in which the issue is created.
in: query
name: action
schema:
default: view
enum:
- view
- browse
- edit
- create
type: string
- description: >-
Use [expand](#expansion) to include additional information in the
response. This parameter accepts a comma-separated list. Expanded
options include:
* `description` Returns the project description.
* `projectKeys` Returns all project keys associated with a project.
* `lead` Returns information about the project lead.
* `issueTypes` Returns all issue types associated with the project.
* `url` Returns the URL associated with the project.
* `insight` EXPERIMENTAL. Returns the insight details of total issue count and last issue update time for the project.
in: query
name: expand
schema:
type: string
- description: |-
EXPERIMENTAL. Filter results by project status:
* `live` Search live projects.
* `archived` Search archived projects.
* `deleted` Search deleted projects, those in the recycle bin.
in: query
name: status
schema:
items:
default: live
enum:
- live
- archived
- deleted
type: string
type: array
- description: >-
EXPERIMENTAL. A list of project properties to return for the
project. This parameter accepts a comma-separated list.
in: query
name: properties
schema:
items:
$ref: '#/components/schemas/StringList'
type: array
- description: >-
EXPERIMENTAL. A query string used to search properties. The query
string cannot be specified using a JSON object. For example, to
search for the value of `nested` from
`{"something":{"nested":1,"other":2}}` use
`[thepropertykey].something.nested=1`. Note that the propertyQuery
key is enclosed in square brackets to enable searching where the
propertyQuery key includes dot (.) or equals (=) characters. Note
that `thepropertykey` is only returned when included in
`properties`.
in: query
name: propertyQuery
schema:
# --- truncated at 32 KB (206 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-rest-api-3-project--openapi-original.yml