Atlassian Project Categories API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Project Categories API
  description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
  version: 1.0.0
  contact:
    name: Atlassian Developer
    url: https://developer.atlassian.com/cloud/admin/
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  x-logo:
    url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
  description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Project Categories
paths:
  /rest/api/3/projectCategory/{id}:
    delete:
      deprecated: false
      description: Deletes a project category.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianRemoveprojectcategory
      parameters:
      - description: ID of the project category to delete.
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '204':
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: Returned if the user does not have the necessary permission.
        '404':
          description: Returned if the project category is not found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      summary: Atlassian Delete Project Category
      tags:
      - Project Categories
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - manage:jira-project
        state: Current
      - scheme: OAuth2
        scopes:
        - delete:project-category:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
    get:
      deprecated: false
      description: Returns a project category.<br><br>**[Permissions](#permissions) required:** Permission to access Jira.
      operationId: atlassianGetprojectcategorybyid
      parameters:
      - description: The ID of the project category.
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              example: '{"description":"First Project Category","id":"10000","name":"FIRST","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000"}'
              schema:
                $ref: '#/components/schemas/ProjectCategory'
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '404':
          description: Returned if the project category is not found.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      summary: Atlassian Get Project Category By Id
      tags:
      - Project Categories
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - read:jira-work
        state: Current
      - scheme: OAuth2
        scopes:
        - read:project-category:jira
        state: Beta
      x-atlassian-connect-scope: READ
    put:
      deprecated: false
      description: Updates a project category.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianUpdateprojectcategory
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            example:
              description: Updated Project Category
              name: UPDATED
            schema:
              $ref: '#/components/schemas/ProjectCategory'
        required: true
      responses:
        '200':
          content:
            application/json:
              example: '{"description":"Updated Project Category","id":"10100","name":"UPDATED","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10100"}'
              schema:
                $ref: '#/components/schemas/UpdatedProjectCategory'
          description: Returned if the request is successful.
        '400':
          description: "Returned if:\n\n *  `name` has been modified and exceeds 255 characters.\n *  `description` has been modified and exceeds 1000 characters."
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: Returned if the user does not have the necessary permission.
        '404':
          description: Returned if the project category is not found.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      summary: Atlassian Update Project Category
      tags:
      - Project Categories
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - manage:jira-project
        state: Current
      - scheme: OAuth2
        scopes:
        - read:project-category:jira
        - write:project-category:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
  /rest/api/3/projectCategory:
    get:
      deprecated: false
      description: Returns all project categories.<br><br>**[Permissions](#permissions) required:** Permission to access Jira.
      operationId: atlassianGetallprojectcategories
      parameters: []
      responses:
        '200':
          content:
            application/json:
              example: '[{"description":"First Project Category","id":"10000","name":"FIRST","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10000"},{"description":"Second Project Category","id":"10001","name":"SECOND","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10001"}]'
              schema:
                items:
                  $ref: '#/components/schemas/ProjectCategory'
                type: array
          description: Returned if the request is successful.
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
      security:
      - basicAuth: []
      - OAuth2:
        - read:jira-work
      summary: Atlassian Get All Project Categories
      tags:
      - Project Categories
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - read:jira-work
        state: Current
      - scheme: OAuth2
        scopes:
        - read:project-category:jira
        state: Beta
      x-atlassian-connect-scope: READ
    post:
      deprecated: false
      description: Creates a project category.<br><br>**[Permissions](#permissions) required:** *Administer Jira* [global permission](https://confluence.atlassian.com/x/x4dKLg).
      operationId: atlassianCreateprojectcategory
      parameters: []
      requestBody:
        content:
          application/json:
            example:
              description: Created Project Category
              name: CREATED
            schema:
              $ref: '#/components/schemas/ProjectCategory'
        required: true
      responses:
        '201':
          content:
            application/json:
              example: '{"description":"Created Project Category","id":"10100","name":"CREATED","self":"https://your-domain.atlassian.net/rest/api/3/projectCategory/10100"}'
              schema:
                $ref: '#/components/schemas/ProjectCategory'
          description: Returned if the request is successful.
        '400':
          description: "Returned if:\n\n *  `name` is not provided or exceeds 255 characters.\n *  `description` exceeds 1000 characters."
        '401':
          description: Returned if the authentication credentials are incorrect or missing.
        '403':
          description: Returned if the user does not have the necessary permission.
        '409':
          description: Returned if the project category name is in use.
      security:
      - basicAuth: []
      - OAuth2:
        - manage:jira-project
      summary: Atlassian Create Project Category
      tags:
      - Project Categories
      x-atlassian-data-security-policy:
      - app-access-rule-exempt: true
      x-atlassian-oauth2-scopes:
      - scheme: OAuth2
        scopes:
        - manage:jira-project
        state: Current
      - scheme: OAuth2
        scopes:
        - write:project-category:jira
        - read:project-category:jira
        state: Beta
      x-atlassian-connect-scope: ADMIN
components:
  schemas:
    UpdatedProjectCategory:
      additionalProperties: false
      description: A project category.
      properties:
        description:
          description: The name of the project category.
          readOnly: true
          type: string
        id:
          description: The ID of the project category.
          readOnly: true
          type: string
        name:
          description: The description of the project category.
          readOnly: true
          type: string
        self:
          description: The URL of the project category.
          readOnly: true
          type: string
      type: object
    ProjectCategory:
      additionalProperties: false
      description: A project category.
      properties:
        description:
          description: The description of the project category.
          type: string
        id:
          description: The ID of the project category.
          readOnly: true
          type: string
        name:
          description: The name of the project category. Required on create, optional on update.
          type: string
        self:
          description: The URL of the project category.
          format: uri
          readOnly: true
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization for Atlassian Cloud APIs.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:org:admin: Read organization information.
            write:org:admin: Modify organization settings.
            read:user:admin: Read user information.
            write:user:admin: Modify user accounts.
            read:policy:admin: Read organization policies.
            write:policy:admin: Modify organization policies.
            read:event:admin: Read organization events.
externalDocs:
  description: Atlassian Admin REST API Documentation
  url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/