Bitbucket Commit statuses API

openapi: 3.2.0
info:
  title: Bitbucket Commit statuses API
  description: Code against the Bitbucket API to automate simple tasks, embed Bitbucket data into your own site, build mobile or desktop apps, or even add custom UI add-ons into Bitbucket itself using the Connect framework.
  version: '2.0'
  termsOfService: https://www.atlassian.com/legal/customer-agreement
  contact:
    name: Bitbucket Support
    url: https://support.atlassian.com/bitbucket-cloud/
    email: support@bitbucket.org
servers:
- url: https://api.bitbucket.org/2.0
tags:
- name: Commit Statuses
  description: 'Commit statuses provide a way to tag commits with meta data,

    like automated build results.'
paths:
  /repositories/{workspace}/{repo_slug}/commit/{commit}/statuses:
    parameters:
    - name: commit
      in: path
      description: The commit's 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
    get:
      tags:
      - Commit Statuses
      description: Returns all statuses (e.g. build results) for a specific commit.
      summary: List commit statuses for a commit
      responses:
        '200':
          description: A paginated list of all commit statuses for this commit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_commitstatuses'
        '401':
          description: If the repository is private and the request was not authenticated.
        '404':
          description: If the repository or commit does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: refname
        in: query
        description: 'If specified, only return commit status objects that were either

          created without a refname, or were created with the specified refname

          '
        required: false
        schema:
          type: string
      - name: q
        in: query
        description: 'Query string to narrow down the response as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).

          '
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: 'Field by which the results should be sorted as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).

          Defaults to `created_on`.

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
      operationId: getRepositoriesByWorkspaceByRepoSlugCommitByCommitStatuses
      x-operation-id-source: derived
  /repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build:
    parameters:
    - name: commit
      in: path
      description: The commit's 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:
      - Commit Statuses
      description: 'Creates a new build status against the specified commit.


        If the specified key already exists, the existing status object will

        be overwritten.


        Example:


        ```

        curl https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo/commit/e10dae226959c2194f2b07b077c07762d93821cf/statuses/build/ -X POST -u jdoe -H ''Content-Type: application/json'' -d ''{

        "key": "MY-BUILD",

        "state": "SUCCESSFUL",

        "description": "42 tests passed",

        "url": "https://www.example.org/my-build-result"

        }''

        ```


        When creating a new commit status, you can use a URI template for the URL.

        Templates are URLs that contain variable names that Bitbucket will

        evaluate at runtime whenever the URL is displayed anywhere similar to

        parameter substitution in

        Bitbucket Connect.

        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.

        The context variables available are `repository` and `commit`.


        To associate a commit status to a pull request, the refname field must be set to the source branch

        of the pull request.


        Example:

        ```

        curl https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo/commit/e10dae226959c2194f2b07b077c07762d93821cf/statuses/build/ -X POST -u jdoe -H ''Content-Type: application/json'' -d ''{

        "key": "MY-BUILD",

        "state": "SUCCESSFUL",

        "description": "42 tests passed",

        "url": "https://www.example.org/my-build-result",

        "refname": "my-pr-branch"

        }''

        ```'
      summary: Create a build status for a commit
      responses:
        '201':
          description: The newly created build status object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/commitstatus'
        '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
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/commitstatus'
        description: The new commit status object.
      operationId: postRepositoriesByWorkspaceByRepoSlugCommitByCommitStatusesBuild
      x-operation-id-source: derived
  /repositories/{workspace}/{repo_slug}/commit/{commit}/statuses/build/{key}:
    parameters:
    - name: commit
      in: path
      description: The commit's 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:
      - Commit Statuses
      description: Returns the specified build status for a commit.
      summary: Get a build status for a commit
      responses:
        '200':
          description: The build status object with the specified key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/commitstatus'
        '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
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
      operationId: getRepositoriesByWorkspaceByRepoSlugCommitByCommitStatusesBuildByKey
      x-operation-id-source: derived
    put:
      tags:
      - Commit Statuses
      description: 'Used to update the current status of a build status object on the

        specific commit.


        This operation can also be used to change other properties of the

        build status:


        * `state`

        * `name`

        * `description`

        * `url`

        * `refname`


        The `key` cannot be changed.'
      summary: Update a build status for a commit
      responses:
        '200':
          description: The updated build status object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/commitstatus'
        '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'
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/commitstatus'
        description: The updated build status object
      operationId: putRepositoriesByWorkspaceByRepoSlugCommitByCommitStatusesBuildByKey
      x-operation-id-source: derived
  /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/statuses:
    parameters:
    - name: pull_request_id
      in: path
      description: The id of the pull request.
      required: true
      schema:
        type: integer
    - 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:
      - Commit Statuses
      description: 'Returns all statuses (e.g. build results) for the given pull

        request.'
      summary: List commit statuses for a pull request
      responses:
        '200':
          description: A paginated list of all commit statuses for this pull request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_commitstatuses'
        '401':
          description: If the repository is private and the request was not authenticated.
        '404':
          description: If the specified repository or pull request does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: q
        in: query
        description: 'Query string to narrow down the response as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).

          '
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: 'Field by which the results should be sorted as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).

          Defaults to `created_on`.

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - pullrequest
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:pullrequest:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
      operationId: getRepositoriesByWorkspaceByRepoSlugPullrequestsByPullRequestIdStatuses
      x-operation-id-source: derived
components:
  schemas:
    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
        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
      required:
      - type
      additionalProperties: true
    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
          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:
            - FAILED
            - INPROGRESS
            - 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
        required:
        - key
        - state
        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
      required:
      - type
      additionalProperties: true
      discriminator:
        propertyName: type
    paginated_commitstatuses:
      type: object
      title: Paginated Commit Statuses
      description: A paginated list of commit status objects.
      properties:
        size:
          type: integer
          description: Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute.
          minimum: 0
        page:
          type: integer
          description: Page number of the current results. This is an optional element that is not provided in all responses.
          minimum: 1
        pagelen:
          type: integer
          description: Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values.
          minimum: 1
        next:
          type: string
          description: Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs.
          format: uri
        previous:
          type: string
          description: Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs.
          format: uri
        values:
          type: array
          items:
            $ref: '#/components/schemas/commitstatus'
          minItems: 0
          uniqueItems: true
      additionalProperties: false
  securitySchemes:
    basic:
      type: http
      scheme: basic
      description: Basic HTTP Authentication as per [RFC-2617](https://tools.ietf.org/html/rfc2617) (Digest not supported). Note that Basic Auth is available only with username and app password as credentials.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            repository: Read your repositories
            repository:write: Read and modify your repositories
            repository:admin: Administer your repositories
            repository:delete: Delete your repositories
            project: Read your workspace's project settings and read repositories contained within your workspace's projects
            project:admin: Read and modify settings for projects in your workspace
            email: Read your account's primary email address
            account: Read your account information
            account:write: Read and modify your account information
            team: Read your team membership information
            team:write: Read and modify your team membership information
            pipeline: Access your repositories' build pipelines
            pipeline:write: Access and rerun your repositories' build pipelines
            pipeline:variable: Access your repositories' build pipelines and configure their variables
            runner: Access your workspaces/repositories' runners
            runner:write: Access and edit your workspaces/repositories' runners
            test: Access your workspaces/repositories' test
            test:write: Access and edit your workspaces/repositories' test
            pullrequest: Read your repositories and their pull requests
            pullrequest:write: Read and modify your repositories and their pull requests
            webhook: Read and modify your repositories' webhooks
            issue: Read your repositories' issues
            issue:write: Read and modify your repositories' issues
            snippet: Read your snippets
            snippet:write: Read and modify your snippets
            wiki: Read and modify your repositories' wikis
          authorizationUrl: https://bitbucket.org/site/oauth2/authorize
          tokenUrl: https://bitbucket.org/site/oauth2/access_token
      description: OAuth 2 as per [RFC-6749](https://tools.ietf.org/html/rfc6749).
    api_key:
      name: Authorization
      type: apiKey
      description: API Keys can be used as Basic HTTP Authentication credentials and provide a substitute for the account's actual username and password. API Keys are only available to team accounts and there is only 1 key per account. API Keys do not support scopes and have therefore access to all contents of the account.
      in: header
x-revision: 84a5dd73aa83
x-atlassian-narrative:
  documents:


# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket/refs/heads/main/openapi/bitbucket-commit-statuses-api-openapi.yml