Atlassian Builds API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Builds 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: Builds
paths:
  /repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build:
    parameters:
    - name: commit
      in: path
      description: The Commits SHA1.
      required: true
      schema:
        type: string
    - name: repo_slug
      in: path
      description: 'This can either be the repository slug or the UUID of the repository,

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

        '
      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
    post:
      tags:
      - Builds
      description: This POST endpoint creates a build status for a specific commit in a Bitbucket repository, allowing external CI/CD systems and build tools to report the status of automated builds back to Bitbucket. The endpoint requires the workspace ID, repository slug, and commit hash as path parameters, and accepts a JSON payload containing build status information such as state (successful, failed, in progress), key, name, URL, and description. When invoked, it associates the provided build status with the specified commit, which then becomes visible in the Bitbucket UI on pull requests and commit pages, enabling teams to track build results and prevent merging of code that fails automated checks. This integration is essential for maintaining CI/CD pipelines and ensuring code quality by providing real-time feedback on build outcomes directly within the version control interface.
      summary: Atlassian Create Build Status for Commit
      responses:
        '201':
          description: The newly created build status object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/commitstatus'
              examples:
                commit-status_2:
                  $ref: '#/components/examples/commit-status_2'
        '401':
          description: If the repository is private and the request was not authenticated.
        '404':
          description: If the repository, commit, or build status key does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/commitstatus'
            examples:
              commit-status:
                $ref: '#/components/examples/commit-status'
        description: The new commit status object.
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      operationId: createBuildStatusForCommit
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationRequestSchema: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build/{key}:
    parameters:
    - name: commit
      in: path
      description: The Commits SHA1.
      required: true
      schema:
        type: string
    - name: key
      in: path
      description: The build status' unique key
      required: true
      schema:
        type: string
    - name: repo_slug
      in: path
      description: 'This can either be the repository slug or the UUID of the repository,

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

        '
      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:
      - Builds
      description: Retrieves a specific build status object associated with a commit in a Bitbucket repository, identified by a unique key. This endpoint allows you to query the detailed status information of a particular build or CI/CD pipeline execution that was reported for a given commit. You must provide the workspace identifier, repository slug, commit hash, and the unique key of the build status you want to retrieve. The response includes comprehensive details about the build execution such as its state (successful, failed, in progress), description, URL to view the build results, and timestamp information. This is particularly useful for integrating with external CI/CD systems, monitoring build pipelines, or displaying build status information in custom dashboards and applications.
      summary: Atlassian Get Build Status for Commit
      responses:
        '200':
          description: The build status object with the specified key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/commitstatus'
              examples:
                commit-status_2:
                  $ref: '#/components/examples/commit-status_2'
        '401':
          description: If the repository is private and the request was not authenticated.
        '404':
          description: If the repository, commit, or build status key does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      operationId: getBuildStatusForCommit
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Builds
      description: This API operation updates the build status for a specific commit in a Bitbucket repository by making a PUT request to the endpoint that identifies a unique build status entry through the workspace name, repository slug, commit hash, and a unique key identifier. It allows developers and CI/CD systems to modify the state of an existing build status record associated with a particular commit, enabling them to update information such as whether the build is in progress, successful, failed, or stopped, along with relevant metadata like build URLs, descriptions, and timestamps. This is particularly useful for continuous integration workflows where build systems need to communicate the current state of automated builds and tests back to Bitbucket, providing visibility to team members about the health and status of code changes directly within the repository interface.
      summary: Atlassian Update Build Status for Commit
      responses:
        '200':
          description: The updated build status object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/commitstatus'
              examples:
                commit-status_2:
                  $ref: '#/components/examples/commit-status_2'
        '401':
          description: If the repository is private and the request was not authenticated.
        '404':
          description: If the repository or build does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/commitstatus'
            examples:
              commit-status_2:
                $ref: '#/components/examples/commit-status_2'
        description: The updated build status object
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      operationId: updateBuildStatusForCommit
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationRequestSchema: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}/logs/{log_uuid}:
    get:
      tags:
      - Builds
      summary: Atlassian Get the Logs for the Build Container or Service Container for Given Step of Pipeline.
      description: This API endpoint retrieves the logs for a specific build or service container associated with a particular step in a Bitbucket pipeline execution. By providing the workspace identifier, repository slug, pipeline UUID, step UUID, and log UUID, developers can access detailed log information that captures the output and execution details of containers running during the pipeline process. This is particularly useful for debugging pipeline failures, monitoring build processes, and tracking the behavior of services or builds within a specific pipeline step, enabling teams to troubleshoot issues and optimize their CI/CD workflows effectively.
      operationId: getTheLogsForTheBuildContainerOrServiceContainerForGivenStepOfPipeline
      parameters:
      - name: workspace
        description: This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example `{workspace UUID}`.
        required: true
        in: path
        schema:
          type: string
      - name: repo_slug
        description: The repository.
        required: true
        in: path
        schema:
          type: string
      - name: pipeline_uuid
        description: The UUID of the pipeline.
        required: true
        in: path
        schema:
          type: string
      - name: step_uuid
        description: The UUID of the step.
        required: true
        in: path
        schema:
          type: string
      - name: log_uuid
        description: For the main build container specify the step UUID; for a service container specify the service container UUID
        required: true
        in: path
        schema:
          type: string
      responses:
        '200':
          description: The raw log file for the build container or service container.
        '404':
          description: No account, repository, pipeline, step or log exist for the provided path.
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/error'
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:pipeline:bitbucket
      security:
      - oauth2:
        - pipeline
      - basic: []
      - api_key: []
      x-api-evangelist-processing:
        ChooseTags: true
        WriteDescription: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/pipelines_config/build_number:
    put:
      tags:
      - Builds
      summary: Atlassian Update the Next Build Number
      description: This PUT operation updates the next build number for Bitbucket Pipelines in a specific repository. By targeting the endpoint /repositories/{workspace}/{repo_slug}/pipelines_config/build_number, users can set a custom value for the next pipeline build number that will be assigned when a new pipeline is triggered. This is useful for maintaining consistent build numbering across different environments, resetting build numbers after repository migrations, or aligning build numbers with organizational versioning schemes. The operation requires workspace and repository slug parameters to identify the target repository, and the request body should contain the desired build number value. Only users with appropriate repository permissions can modify this configuration setting.
      operationId: updateTheNextBuildNumber
      parameters:
      - name: workspace
        description: This can either be the workspace ID (slug) or the workspace UUID surrounded by curly-braces, for example `{workspace UUID}`.
        required: true
        in: path
        schema:
          type: string
      - name: repo_slug
        description: The repository.
        required: true
        in: path
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pipeline_build_number'
            examples:
              pipeline-build-number:
                $ref: '#/components/examples/pipeline-build-number'
        description: The build number to update.
        required: true
      responses:
        '200':
          description: The build number has been configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pipeline_build_number'
              examples:
                pipeline-build-number_2:
                  $ref: '#/components/examples/pipeline-build-number_2'
        '400':
          description: The update failed because the next number was invalid (it should be higher than the current number).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: The account or repository was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:pipeline:bitbucket
      security:
      - oauth2:
        - pipeline:variable
      - basic: []
      - api_key: []
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationRequestSchema: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    pipeline_build_number:
      allOf:
      - $ref: '#/components/schemas/object'
      - additionalProperties: true
        type: object
        title: Pipeline Build Number
        description: A Pipelines build number.
        properties:
          next:
            type: integer
            description: The next number that will be used as build number.
    error:
      type: object
      title: Error
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
          example: example_value
        error:
          type: object
          properties:
            message:
              type: string
            detail:
              type: string
            data:
              type: object
              description: Optional structured data that is endpoint-specific.
              properties: {}
              additionalProperties: true
          required:
          - message
          additionalProperties: false
          example: example_value
      required:
      - type
      additionalProperties: true
    object:
      type: object
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
          example: example_value
      required:
      - type
      additionalProperties: true
      discriminator:
        propertyName: type
    commitstatus:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Commit Status
        description: A commit status object.
        properties:
          links:
            type: object
            properties:
              self:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              commit:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
            additionalProperties: false
          uuid:
            type: string
            description: The commit status' id.
          key:
            type: string
            description: "An identifier for the status that's unique to\n        its type (current \"build\" is the only supported type) and the vendor,\n        e.g. BB-DEPLOY"
          refname:
            type: string
            description: '

              The name of the ref that pointed to this commit at the time the status

              object was created. Note that this the ref may since have moved off of

              the commit. This optional field can be useful for build systems whose

              build triggers and configuration are branch-dependent (e.g. a Pipeline

              build).

              It is legitimate for this field to not be set, or even apply (e.g. a

              static linting job).'
          url:
            type: string
            description: A URL linking back to the vendor or build system, for providing more information about whatever process produced this status. Accepts context variables `repository` and `commit` that Bitbucket will evaluate at runtime whenever at runtime. For example, one could use https://foo.com/builds/{repository.full_name} which Bitbucket will turn into https://foo.com/builds/foo/bar at render time.
          state:
            type: string
            description: Provides some indication of the status of this commit
            enum:
            - INPROGRESS
            - FAILED
            - STOPPED
            - SUCCESSFUL
          name:
            type: string
            description: An identifier for the build itself, e.g. BB-DEPLOY-1
          description:
            type: string
            description: A description of the build (e.g. "Unit tests in Bamboo")
          created_on:
            type: string
            format: date-time
          updated_on:
            type: string
            format: date-time
        additionalProperties: true
  examples:
    commit-status:
      links:
        self:
          href: https://api.bitbucket.org/2.0/repositories/example/repo/commit/abc123/statuses/build/1
          name: self
        commit:
          href: https://api.bitbucket.org/2.0/repositories/example/repo/commit/abc123
          name: commit
      uuid: '{12345678-1234-1234-1234-123456789abc}'
      key: BB-DEPLOY
      refname: main
      url: https://foo.com/builds/{repository.full_name}
      state: SUCCESSFUL
      name: BB-DEPLOY-1
      description: Unit tests in Bamboo
      created_on: '2023-11-15T10:30:00Z'
      updated_on: '2023-11-15T10:45:00Z'
    pipeline-build-number_2:
      next: 42
    pipeline-build-number:
      next: 42
    commit-status_2:
      links:
        self:
          href: https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo/commit/a1b2c3d4/statuses/build/bb-deploy-123
          name: Self Link
        commit:
          href: https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo/commit/a1b2c3d4
          name: Commit Link
      uuid: '{12345678-1234-5678-1234-567812345678}'
      key: BB-DEPLOY
      refname: main
      url: https://builds.example.com/repositories/{repository.full_name}/commits/{commit}
      state: SUCCESSFUL
      name: BB-DEPLOY-1
      description: Unit tests in Bamboo
      created_on: '2023-11-15T10:30:00Z'
      updated_on: '2023-11-15T10:45:00Z'
  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/