openapi: 3.1.0
info:
title: Jira Cloud Platform REST Issue Comments Projects API
description: The Jira Cloud platform REST API v3 for building apps and integrations with Atlassian Jira. This specification covers core resources including issues, projects, and search (JQL). All responses use Atlassian Document Format (ADF) for rich text fields. Authentication is via OAuth 2.0 (3LO), API tokens with basic auth, or Atlassian Connect JWT.
version: '3'
license:
name: Atlassian Developer Terms
url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
termsOfService: https://www.atlassian.com/legal/cloud-terms-of-service
contact:
name: Atlassian Developer Support
url: https://developer.atlassian.com/support
email: ecosystem@atlassian.com
x-atlassian-api-version: '3'
servers:
- url: https://{domain}.atlassian.net/rest/api/3
description: Jira Cloud instance
variables:
domain:
description: Your Jira Cloud site subdomain (e.g., your-company).
default: your-domain
security:
- basicAuth: []
- oauth2: []
- bearerAuth: []
tags:
- name: Projects
description: Manage Jira projects including metadata, roles, and components.
externalDocs:
description: Jira Projects REST API documentation
url: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/
paths:
/project:
get:
summary: Jira Get All Projects
description: Returns all projects visible to the user. Deprecated, use Get projects paginated that supports search and pagination.
operationId: getAllProjects
tags:
- Projects
externalDocs:
description: API method documentation
url: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-get
parameters:
- name: expand
in: query
description: 'Use expand to include additional information in the response. Accepted values: description, issueTypes, lead, projectKeys, url.'
required: false
schema:
type: string
example: example_value
- name: recent
in: query
description: Returns projects the user has accessed in the last given number of projects, up to 20.
required: false
schema:
type: integer
format: int32
example: 10
- name: properties
in: query
description: A list of project properties to return for each project.
required: false
schema:
type: array
items:
type: string
style: form
explode: true
example: []
responses:
'200':
description: Projects returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Project'
examples:
Getallprojects200Example:
summary: Default getAllProjects 200 response
x-microcks-default: true
value:
- self: https://www.example.com
id: abc123
key: example_value
name: Example Title
description: A sample description.
lead:
self: https://www.example.com
accountId: '500123'
emailAddress: user@example.com
displayName: example_value
active: true
timeZone: example_value
accountType: atlassian
components:
- {}
issueTypes:
- {}
url: https://www.example.com
assigneeType: PROJECT_LEAD
versions:
- {}
roles: example_value
avatarUrls:
16x16: https://www.example.com
24x24: https://www.example.com
32x32: https://www.example.com
48x48: https://www.example.com
projectCategory:
self: https://www.example.com
id: abc123
name: Example Title
description: A sample description.
projectTypeKey: software
simplified: true
style: classic
archived: true
deleted: true
insight:
totalIssueCount: 10
lastIssueUpdateTime: '2026-01-15T10:30:00Z'
'401':
description: Authentication credentials are missing or invalid.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/project/search:
get:
summary: Jira Get Projects Paginated
description: Returns a paginated list of projects visible to the user. This operation can be filtered by project type, category, and action.
operationId: searchProjects
tags:
- Projects
externalDocs:
description: API method documentation
url: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-search-get
parameters:
- name: startAt
in: query
description: The index of the first item to return in a page of results (page offset).
required: false
schema:
type: integer
format: int64
default: 0
example: 10
- name: maxResults
in: query
description: The maximum number of items to return per page.
required: false
schema:
type: integer
format: int32
default: 50
example: 10
- name: orderBy
in: query
description: 'Order the results by a field. Accepted values: category, key, name, owner, issueCount, lastIssueUpdatedTime, archivedDate. Prefix with + or - for ascending/descending.'
required: false
schema:
type: string
default: key
example: example_value
- name: query
in: query
description: Filter results using a literal string match on project name or key.
required: false
schema:
type: string
example: example_value
- name: typeKey
in: query
description: 'The type key of the project. Accepted values: business, service_desk, software.'
required: false
schema:
type: string
example: example_value
- name: categoryId
in: query
description: The ID of the project category to filter by.
required: false
schema:
type: integer
format: int64
example: '500123'
- name: action
in: query
description: 'Filter results by what the user has permission to do. Accepted values: view, browse, edit, create.'
required: false
schema:
type: string
default: view
example: example_value
- name: expand
in: query
description: 'Use expand to include additional information in the response. Accepted values: description, projectKeys, lead, issueTypes, url, insight.'
required: false
schema:
type: string
example: example_value
- name: status
in: query
description: 'The status of the project. Accepted values: live, archived, deleted.'
required: false
schema:
type: array
items:
type: string
enum:
- live
- archived
- deleted
style: form
explode: true
example: []
responses:
'200':
description: Paginated project list returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/PageBeanProject'
examples:
Searchprojects200Example:
summary: Default searchProjects 200 response
x-microcks-default: true
value:
self: https://www.example.com
nextPage: https://www.example.com
maxResults: 10
startAt: 10
total: 10
isLast: true
values:
- self: https://www.example.com
id: abc123
key: example_value
name: Example Title
description: A sample description.
components: {}
issueTypes: {}
url: https://www.example.com
assigneeType: PROJECT_LEAD
versions: {}
roles: example_value
projectTypeKey: software
simplified: true
style: classic
archived: true
deleted: true
insight: {}
'400':
description: The request is invalid.
'401':
description: Authentication credentials are missing or invalid.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/project/{projectIdOrKey}:
get:
summary: Jira Get Project
description: Returns the project details for a project. The returned project includes additional information such as issue types, components, versions, and roles.
operationId: getProject
tags:
- Projects
externalDocs:
description: API method documentation
url: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-get
parameters:
- $ref: '#/components/parameters/projectIdOrKey'
- name: expand
in: query
description: 'Use expand to include additional information in the response. Accepted values: description, issueTypes, lead, projectKeys, url, insight.'
required: false
schema:
type: string
example: example_value
- name: properties
in: query
description: A list of project properties to return for the project.
required: false
schema:
type: array
items:
type: string
style: form
explode: true
example: []
responses:
'200':
description: Project details returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
examples:
Getproject200Example:
summary: Default getProject 200 response
x-microcks-default: true
value:
self: https://www.example.com
id: abc123
key: example_value
name: Example Title
description: A sample description.
lead:
self: https://www.example.com
accountId: '500123'
emailAddress: user@example.com
displayName: example_value
active: true
timeZone: example_value
accountType: atlassian
components:
- self: https://www.example.com
id: abc123
name: Example Title
description: A sample description.
assigneeType: PROJECT_DEFAULT
project: example_value
projectId: '500123'
issueTypes:
- self: https://www.example.com
id: abc123
description: A sample description.
iconUrl: https://www.example.com
name: Example Title
subtask: true
avatarId: '500123'
hierarchyLevel: 10
url: https://www.example.com
assigneeType: PROJECT_LEAD
versions:
- self: https://www.example.com
id: abc123
name: Example Title
description: A sample description.
archived: true
released: true
releaseDate: '2026-01-15'
startDate: '2026-01-15'
overdue: true
projectId: '500123'
roles: example_value
avatarUrls:
16x16: https://www.example.com
24x24: https://www.example.com
32x32: https://www.example.com
48x48: https://www.example.com
projectCategory:
self: https://www.example.com
id: abc123
name: Example Title
description: A sample description.
projectTypeKey: software
simplified: true
style: classic
archived: true
deleted: true
insight:
totalIssueCount: 10
lastIssueUpdateTime: '2026-01-15T10:30:00Z'
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The project was not found or the user does not have permission to view it.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/project/{projectIdOrKey}/statuses:
get:
summary: Jira Get All Statuses for Project
description: Returns the valid statuses for a project. The statuses are grouped by issue type, listing the allowed statuses for each issue type in the project.
operationId: getAllStatuses
tags:
- Projects
externalDocs:
description: API method documentation
url: https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-projects/#api-rest-api-3-project-projectidorkey-statuses-get
parameters:
- $ref: '#/components/parameters/projectIdOrKey'
responses:
'200':
description: Statuses returned successfully.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/IssueTypeWithStatus'
examples:
Getallstatuses200Example:
summary: Default getAllStatuses 200 response
x-microcks-default: true
value:
- self: https://www.example.com
id: abc123
name: Example Title
subtask: true
statuses:
- {}
'401':
description: Authentication credentials are missing or invalid.
'404':
description: The project was not found or the user does not have permission to view it.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Version:
type: object
description: A project version.
properties:
self:
type: string
format: uri
example: https://www.example.com
id:
type: string
example: abc123
name:
type: string
example: Example Title
description:
type: string
example: A sample description.
archived:
type: boolean
example: true
released:
type: boolean
example: true
releaseDate:
type: string
format: date
example: '2026-01-15'
startDate:
type: string
format: date
example: '2026-01-15'
overdue:
type: boolean
example: true
projectId:
type: integer
format: int64
example: '500123'
IssueTypeDetails:
type: object
description: Details of an issue type.
properties:
self:
type: string
format: uri
description: The URL of the issue type in the REST API.
example: https://www.example.com
id:
type: string
description: The ID of the issue type.
example: abc123
description:
type: string
description: The description of the issue type.
example: A sample description.
iconUrl:
type: string
format: uri
description: The URL of the issue type icon.
example: https://www.example.com
name:
type: string
description: The name of the issue type (e.g., Bug, Story, Task, Epic).
example: Example Title
subtask:
type: boolean
description: Whether this issue type is used to create sub-tasks.
example: true
avatarId:
type: integer
format: int64
description: The ID of the avatar for the issue type.
example: '500123'
hierarchyLevel:
type: integer
format: int32
description: The hierarchy level of the issue type.
example: 10
scope:
$ref: '#/components/schemas/Scope'
PageBeanProject:
type: object
description: A paginated list of projects.
properties:
self:
type: string
format: uri
example: https://www.example.com
nextPage:
type: string
format: uri
example: https://www.example.com
maxResults:
type: integer
format: int32
example: 10
startAt:
type: integer
format: int64
example: 10
total:
type: integer
format: int64
example: 10
isLast:
type: boolean
example: true
values:
type: array
items:
$ref: '#/components/schemas/Project'
example: []
IssueTypeWithStatus:
type: object
description: Issue type with its valid statuses.
properties:
self:
type: string
format: uri
example: https://www.example.com
id:
type: string
example: abc123
name:
type: string
example: Example Title
subtask:
type: boolean
example: true
statuses:
type: array
items:
$ref: '#/components/schemas/StatusDetails'
example: []
ProjectCategory:
type: object
description: A project category.
properties:
self:
type: string
format: uri
example: https://www.example.com
id:
type: string
example: abc123
name:
type: string
example: Example Title
description:
type: string
example: A sample description.
StatusCategory:
type: object
description: A status category in Jira.
properties:
self:
type: string
format: uri
example: https://www.example.com
id:
type: integer
format: int64
example: abc123
key:
type: string
description: The key of the status category (e.g., new, indeterminate, done).
example: example_value
colorName:
type: string
description: The color name for the status category.
example: example_value
name:
type: string
description: The name of the status category.
example: Example Title
UserDetails:
type: object
description: A Jira user.
properties:
self:
type: string
format: uri
description: The URL of the user in the REST API.
example: https://www.example.com
accountId:
type: string
description: The account ID of the user, which uniquely identifies the user across all Atlassian products.
maxLength: 128
example: '500123'
emailAddress:
type: string
format: email
description: The email address of the user (may not be available depending on privacy settings).
example: user@example.com
displayName:
type: string
description: The display name of the user.
example: example_value
active:
type: boolean
description: Whether the user account is active.
example: true
timeZone:
type: string
description: The time zone of the user.
example: example_value
accountType:
type: string
description: The type of account.
enum:
- atlassian
- app
- customer
example: atlassian
avatarUrls:
$ref: '#/components/schemas/AvatarUrls'
Project:
type: object
description: A Jira project.
properties:
self:
type: string
format: uri
description: The URL of the project in the REST API.
example: https://www.example.com
id:
type: string
description: The ID of the project.
example: abc123
key:
type: string
description: The key of the project (e.g., PROJ).
example: example_value
name:
type: string
description: The name of the project.
example: Example Title
description:
type: string
description: A description of the project.
example: A sample description.
lead:
$ref: '#/components/schemas/UserDetails'
components:
type: array
description: Components in the project.
items:
$ref: '#/components/schemas/Component'
example: []
issueTypes:
type: array
description: Issue types available in the project.
items:
$ref: '#/components/schemas/IssueTypeDetails'
example: []
url:
type: string
format: uri
description: A URL to the project.
example: https://www.example.com
assigneeType:
type: string
description: The default assignee type for the project.
enum:
- PROJECT_LEAD
- UNASSIGNED
example: PROJECT_LEAD
versions:
type: array
description: The versions defined in the project.
items:
$ref: '#/components/schemas/Version'
example: []
roles:
type: object
description: Project role URLs.
additionalProperties:
type: string
format: uri
example: example_value
avatarUrls:
$ref: '#/components/schemas/AvatarUrls'
projectCategory:
$ref: '#/components/schemas/ProjectCategory'
projectTypeKey:
type: string
description: The project type.
enum:
- software
- service_desk
- business
example: software
simplified:
type: boolean
description: Whether the project is simplified (next-gen/team-managed).
example: true
style:
type: string
description: The style of the project. Classic or next-gen.
enum:
- classic
- next-gen
example: classic
archived:
type: boolean
description: Whether the project is archived.
example: true
deleted:
type: boolean
description: Whether the project is marked as deleted.
example: true
insight:
type: object
description: Insight information about the project.
properties:
totalIssueCount:
type: integer
format: int64
lastIssueUpdateTime:
type: string
format: date-time
example: example_value
StatusDetails:
type: object
description: A status in Jira.
properties:
self:
type: string
format: uri
example: https://www.example.com
id:
type: string
example: abc123
name:
type: string
description: The name of the status (e.g., To Do, In Progress, Done).
example: Example Title
description:
type: string
example: A sample description.
iconUrl:
type: string
format: uri
example: https://www.example.com
statusCategory:
$ref: '#/components/schemas/StatusCategory'
Scope:
type: object
description: The scope of the issue type (project or global).
properties:
type:
type: string
enum:
- PROJECT
- TEMPLATE
example: PROJECT
project:
$ref: '#/components/schemas/ProjectRef'
Component:
type: object
description: A project component.
properties:
self:
type: string
format: uri
example: https://www.example.com
id:
type: string
example: abc123
name:
type: string
example: Example Title
description:
type: string
example: A sample description.
lead:
$ref: '#/components/schemas/UserDetails'
assigneeType:
type: string
enum:
- PROJECT_DEFAULT
- COMPONENT_LEAD
- PROJECT_LEAD
- UNASSIGNED
example: PROJECT_DEFAULT
assignee:
$ref: '#/components/schemas/UserDetails'
project:
type: string
example: example_value
projectId:
type: integer
format: int64
example: '500123'
ProjectRef:
type: object
description: A reference to a Jira project.
properties:
self:
type: string
format: uri
example: https://www.example.com
id:
type: string
example: abc123
key:
type: string
example: example_value
name:
type: string
example: Example Title
avatarUrls:
$ref: '#/components/schemas/AvatarUrls'
projectTypeKey:
type: string
example: example_value
AvatarUrls:
type: object
description: Avatar URLs in multiple sizes.
properties:
16x16:
type: string
format: uri
example: https://www.example.com
24x24:
type: string
format: uri
example: https://www.example.com
32x32:
type: string
format: uri
example: https://www.example.com
48x48:
type: string
format: uri
example: https://www.example.com
parameters:
projectIdOrKey:
name: projectIdOrKey
in: path
description: The ID or key of the project (e.g., 10000 or PROJ).
required: true
schema:
type: string
example: PROJ
securitySchemes:
basicAuth:
type: http
scheme: basic
description: 'Basic authentication using an Atlassian account email and API token. Format: email:api_token, Base64 encoded. Generate API tokens at https://id.atlassian.com/manage-profile/security/api-tokens.'
oauth2:
type: oauth2
description: OAuth 2.0 authorization code grant (3LO) for Jira Cloud apps.
flows:
authorizationCode:
authorizationUrl: https://auth.atlassian.com/authorize
tokenUrl: https://auth.atlassian.com/oauth/token
scopes:
read:jira-work: Read Jira project and issue data.
write:jira-work: Create and edit Jira issues and projects.
manage:jira-project: Manage Jira project settings.
manage:jira-configuration: Manage Jira instance configuration.
read:jira-user: Read Jira user information.
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication using a personal access token (PAT) or OAuth 2.0 access token.
externalDocs:
description: Jira Cloud Platform REST API v3 Documentation
url: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/