Atlassian Projects API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Projects 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: Projects
paths:
  /workspaces/{workspace}/projects/{project_key}/permissions-config/users:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual key assigned to the project.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Projects
      description: This API operation retrieves a list of explicit user permissions that have been granted for a specific project within a Bitbucket workspace. By providing the workspace identifier and project key as path parameters, the endpoint returns details about individual users who have been explicitly assigned permissions to the project, including their access levels and roles. This allows administrators to audit and review which users have direct access to a particular project, separate from any permissions they might inherit through group memberships or workspace-level settings.
      summary: Atlassian List Explicit User Permissions for Project
      responses:
        '200':
          description: Paginated list of explicit user permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_project_user_permissions'
              examples:
                paginated-project-user-permissions:
                  $ref: '#/components/examples/paginated-project-user-permissions'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The user doesn't have admin access to the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or both of the workspace and project don't exist for the given identifiers or the requesting user is not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:project:bitbucket
        - read:user:bitbucket
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      operationId: listExplicitUserPermissionsForProject
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workspaces/{workspace}/projects/{project_key}/permissions-config/users/{selected_user_id}:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual key assigned to the project.

        '
      required: true
      schema:
        type: string
    - name: selected_user_id
      in: path
      description: 'This can either be the username, the Users UUID surrounded by curly-braces,

        for example: {account UUID}, or the Users Atlassian ID.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    delete:
      tags:
      - Projects
      description: This API operation removes an explicitly assigned permission for a specific user within a Bitbucket project by making a DELETE request to the specified endpoint. It requires the workspace slug, project key, and the selected user's ID as path parameters to identify and revoke the user's direct access rights to the project. This operation is useful for project administrators who need to manage team access by removing individual user permissions, though it only affects explicit permissions and does not impact permissions inherited through group memberships or workspace-level access. Upon successful deletion, the user will lose their direct permission assignment for the specified project unless they retain access through other means.
      summary: Atlassian Delete an Explicit User Permission for Project
      responses:
        '204':
          description: The project user permission was deleted and no content returned.
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
      operationId: deleteAnExplicitUserPermissionForProject
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Projects
      description: 'Retrieves the explicit permission details for a specific user within a designated project in a Bitbucket workspace. This endpoint requires three path parameters: the workspace slug identifying the Bitbucket workspace, the project key for the specific project, and the selected user ID representing the user whose permissions are being queried. When called, it returns the permission level that has been directly assigned to the specified user for that project, excluding any inherited permissions from groups or workspace-level access. This is useful for auditing individual user access rights, verifying specific permission assignments, or displaying user-level access information in administrative interfaces.'
      summary: Atlassian Get an Explicit User Permission for Project
      responses:
        '200':
          description: Explicit user permission for user and project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project_user_permission'
              examples:
                project-user-permission:
                  $ref: '#/components/examples/project-user-permission'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:project:bitbucket
        - read:user:bitbucket
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      operationId: getAnExplicitUserPermissionForProject
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Projects
      description: Updates the explicit permission level for a specific user within a Bitbucket project workspace. This PUT operation requires the workspace slug, project key, and the selected user's ID as path parameters, allowing administrators to modify individual user access rights at the project level. The endpoint is used to grant, revoke, or change permission levels (such as read, write, or admin) for a particular user, overriding any inherited permissions from groups or workspace-level settings. This provides fine-grained access control for project resources and is typically used when a user needs different permissions than what they would inherit from their group memberships.
      summary: Atlassian Update an Explicit User Permission for Project
      responses:
        '200':
          description: Explicit user permission updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project_user_permission'
              examples:
                project-user-permission_2:
                  $ref: '#/components/examples/project-user-permission_2'
        '400':
          description: No permission value was provided or the value is invalid (not one of read, write, create-repo, or admin)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: The user couldn't be authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '402':
          description: You have reached your plan's user limit and must upgrade before giving access to additional users.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't an admin of the project, or the authentication method was not via app password.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        $ref: '#/components/requestBodies/bitbucket.apps.permissions.serializers.ProjectPermissionUpdateSchema'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      operationId: updateAnExplicitUserPermissionForProject
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workspaces/{workspace}/projects:
    parameters:
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Projects
      description: This API operation retrieves a paginated list of all projects within a specified Bitbucket workspace, where the workspace is identified by its slug in the URL path. It returns project information including project keys, names, descriptions, and other metadata associated with each project that the authenticated user has permission to view. The response follows Bitbucket's standard pagination format, allowing clients to navigate through large result sets using page parameters, making it useful for applications that need to display or process all projects belonging to a particular workspace.
      summary: Atlassian List Projects in a Workspace
      responses:
        '200':
          description: The list of projects in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_projects'
              examples:
                paginated-projects:
                  $ref: '#/components/examples/paginated-projects'
        '404':
          description: A workspace doesn't exist at this location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:project:bitbucket
      operationId: atlassianListProjectsInAWorkspace
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Projects
      description: This API operation creates a new project within a specified Bitbucket workspace by sending a POST request to the /workspaces/{workspace}/projects endpoint, where {workspace} is replaced with the unique identifier or slug of the target workspace. The operation allows workspace administrators to programmatically establish new projects that serve as containers for organizing related repositories, enabling better code management and team collaboration. When invoked, the endpoint accepts project details in the request body such as project name, key, description, and access permissions, then returns the newly created project object with its assigned metadata including a unique project identifier, timestamps, and configuration settings. This operation requires appropriate authentication credentials and workspace-level permissions, typically administrator or write access, to successfully create projects within the organizational structure of the Bitbucket workspace.
      summary: Atlassian Create a Project in a Workspace
      responses:
        '201':
          description: A new project has been created.
          headers:
            Location:
              description: The location of the newly created project
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project'
              examples:
                project:
                  $ref: '#/components/examples/project'
        '403':
          description: The requesting user isn't authorized to create the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: A workspace doesn't exist at this location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        $ref: '#/components/requestBodies/project'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:project:bitbucket
      operationId: atlassianCreateAProjectInAWorkspace
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workspaces/{workspace}/projects/{project_key}:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual `key` assigned

        to the project.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    delete:
      tags:
      - Projects
      description: 'The delete operation on the `/workspaces/{workspace}/projects/{project_key}` endpoint in the Atlassian Bitbucket Workspaces API permanently removes a specified project from a workspace. This operation requires authentication and appropriate permissions to delete projects within the designated workspace. When executed, it takes two path parameters: the workspace identifier and the project key that uniquely identifies the project to be deleted. Upon successful deletion, the project and its associated metadata are removed from the workspace, though this typically does not affect the repositories contained within the project unless specifically configured to do so. This is a destructive operation that cannot be undone, so it should be used with caution in production environments.'
      summary: Atlassian Delete a Project for a Workspace
      responses:
        '204':
          description: Successful deletion.
        '403':
          description: The requesting user isn't authorized to delete the project or the project isn't empty.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: A project isn't hosted at this location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:project:bitbucket
      operationId: atlassianDeleteAProjectForAWorkspace
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Projects
      description: 'The Get A Project For A Workspace operation in the Atlassian Bitbucket Workspaces API retrieves detailed information about a specific project within a designated workspace by making a GET request to the endpoint /workspaces/{workspace}/projects/{project_key}. This operation requires two path parameters: the workspace identifier (which can be the workspace''s UUID, ID, or slug) and the project_key (a unique identifier for the project within that workspace). When successfully invoked, it returns comprehensive project details including the project''s name, description, key, creation date, visibility settings, owner information, associated links, and other metadata. This endpoint is commonly used by developers and integrations to fetch project-level configuration data, validate project existence, or retrieve project attributes before performing additional operations within that project''s scope.'
      summary: Atlassian Get a Project for a Workspace
      responses:
        '200':
          description: The project that is part of a workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project'
              examples:
                project_2:
                  $ref: '#/components/examples/project_2'
        '401':
          description: The request wasn't authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: The requesting user isn't authorized to access the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: A project isn't hosted at this location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:project:bitbucket
      operationId: atlassianGetAProjectForAWorkspace
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Projects
      description: This API operation allows you to update an existing project within a specified Bitbucket workspace by making a PUT request to the endpoint with the workspace slug and project key as path parameters. You can modify various project properties such as the project name, description, avatar, and other configurable settings. The request requires appropriate authentication and permissions to modify projects within the workspace, typically requiring admin or write access. Upon successful execution, the API returns the updated project object with all its current properties, reflecting the changes made in the request body. This operation follows RESTful conventions where PUT is used to update the complete resource, and any fields not included in the request may be reset to default values depending on the API's implementation.
      summary: Atlassian Update a Project for a Workspace
      responses:
        '200':
          description: The existing project is has been updated.
          headers:
            Location:
              description: 'The location of the project. This header is only provided

                when the project key is updated.'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project'
              examples:
                project_2:
                  $ref: '#/components/examples/project_2'
        '201':
          description: A new project has been created.
          headers:
            Location:
              description: The location of the newly created project
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project'
              examples:
                project_2:
                  $ref: '#/components/examples/project_2'
        '403':
          description: The requesting user isn't authorized to update or create the project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: A workspace doesn't exist at the location. Note that the project's absence from this location doesn't raise a 404, since a PUT at a non-existent location can be used to create a new project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        $ref: '#/components/requestBodies/project'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:project:bitbucket
      operationId: atlassianUpdateAProjectForAWorkspace
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workspaces/{workspace}/projects/{project_key}/branching-model:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual `key` assigned

        to the project.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Projects
      description: This API operation retrieves the branching model configuration for a specific project within a Bitbucket workspace, allowing you to understand how branches are organized and managed within that project. By providing the workspace identifier and project key as path parameters, the GET request returns details about the project's branching strategy, which may include information about development branches, production branches, branch prefixes, and the overall workflow structure that defines how code changes flow from development to production. This is particularly useful for teams that want to programmatically access or audit their project's Git workflow configuration, integrate branching model information into CI/CD pipelines, or build custom tooling that needs to understand the project's branch organization scheme.
      summary: Atlassian Get the Branching Model for a Project
      responses:
        '200':
          description: The branching model object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project_branching_model'
              examples:
                project-branching-model:
                  $ref: '#/components/examples/project-branching-model'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have read access to the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the project does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      operationId: atlassianGetTheBranchingModelForAProject
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /workspaces/{workspace}/projects/{project_key}/branching-model/settings:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual `key` assigned

        to the project.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Projects
      description: This API endpoint retrieves the branching model configuration settings for a specific project within a designated workspace in Atlassian Bitbucket. By making a GET request to this endpoint with the appropriate workspace identifier and project key, users can access the project's branching strategy configuration, which typically includes details about branch types, naming conventions, and workflow patterns such as Git Flow or similar branching models. This information helps teams understand and maintain consistent branching practices across their repositories within the project, ensuring standardized development workflows and version control strategies.
      summary: Atlassian Get the Branching Model Config for a Project
      responses:
        '200':
          description: The branching model configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              examples:
                branching-model-settings:
                  $ref: '#/components/examples/branching-model-settings'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the project does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:project:bitbucket
      operationId: atlassianGetTheBranchingModelConfigForAProject
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Projects
      description: This API operation updates the branching model configuration settings for a specific project within a Bitbucket workspace. It uses a PUT request to the endpoint /workspaces/{workspace}/projects/{project_key}/branching-model/settings, where you specify the workspace slug and project key as path parameters. The branching model defines the workflow for how branches are organized and managed in a project, including settings for development branches, production branches, and branch prefixes for features, releases, hotfixes, and bugfixes. By calling this endpoint, administrators can modify these configuration rules to align with their team's Git workflow strategy, such as Git Flow or a custom branching strategy, ensuring consistent branch naming conventions and automated branch type recognition across the project.
      summary: Atlassian Update the Branching Model Config for a Project
      responses:
        '200':
          description: The updated branching model configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              examples:
                branching-model-settings_2:
                  $ref: '#/components/examples/branching-model-settings_2'
        '400':
          description: If the request contains an invalid branching model configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the project
          content:
            application/json:
              schema:
                $ref:

# --- truncated at 32 KB (238 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-projects-api-openapi.yml