Atlassian Files API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Files 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: Files
paths:
  /repositories/{workspace}/{repo_slug}/filehistory/{commit}/{path}:
    parameters:
    - name: commit
      in: path
      description: The Commits SHA1.
      required: true
      schema:
        type: string
    - name: path
      in: path
      description: Path to the file.
      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:
      - Files
      description: This API operation retrieves the commit history for a specific file in a Bitbucket repository by listing all commits that have modified the file at the given path. The endpoint requires the workspace ID, repository slug, a specific commit SHA, and the file path as parameters. It returns a paginated list of commits in reverse chronological order, showing each commit that touched the specified file up to and including the provided commit reference. This is particularly useful for tracking changes to individual files, understanding file evolution, performing code archaeology, or identifying when specific changes were introduced to a particular file in the repository's history.
      summary: Atlassian List Commits That Modified File
      responses:
        '200':
          description: A paginated list of commits that modified the specified file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_files'
              examples:
                paginated-files:
                  $ref: '#/components/examples/paginated-files'
        '404':
          description: If the repository does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: renames
        in: query
        description: '

          When `true`, Bitbucket will follow the history of the file across

          renames (this is the default behavior). This can be turned off by

          specifying `false`.'
        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: '

          Name of a response property sort the result by as per

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

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      operationId: listCommitsThatModifiedFile
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}/log:
    get:
      tags:
      - Files
      summary: Atlassian Get Log File for Step
      description: This API operation retrieves the log file for a specific step within a Bitbucket pipeline. By providing the workspace ID, repository slug, pipeline UUID, and step UUID, you can access the detailed execution logs generated during that particular pipeline step. The logs contain console output, error messages, and other diagnostic information that occurred while the step was running, which is useful for debugging failed builds, monitoring deployment processes, or auditing pipeline execution history. This endpoint returns the raw log content that was captured during the step's execution in the CI/CD pipeline.
      operationId: getLogFileForStep
      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
      responses:
        '200':
          description: The raw log file for this pipeline step.
        '304':
          description: The log has the same etag as the provided If-None-Match header.
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: A pipeline with the given UUID does not exist, a step with the given UUID does not exist in the pipeline or a log file does not exist for the given step.
          content:
            application/octet-stream:
              schema:
                $ref: '#/components/schemas/error'
        '416':
          description: The requested range does not exist for requests that specified the [HTTP Range header](https://tools.ietf.org/html/rfc7233#section-3.1).
          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:
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/src:
    parameters:
    - 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:
      - Files
      description: This operation allows you to create a new commit in a Bitbucket repository by uploading one or more files directly through the API. You specify the target workspace and repository via the path parameters, then provide the file content along with commit metadata such as the commit message, branch name, author information, and optional parent commit references in the request body. The files are uploaded as multipart form data, where each file can be specified with its path in the repository and its content. Upon successful execution, the API creates a new commit containing the uploaded files and returns details about the newly created commit including its hash, timestamp, and author information. This is particularly useful for automating file updates, CI/CD pipelines, or any workflow that needs to programmatically modify repository contents without requiring a local git clone or manual file operations.
      summary: Atlassian Create Commit by Uploading File
      responses:
        '201':
          description: '

            '
        '403':
          description: If the authenticated user does not have write or admin access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: message
        in: query
        description: The commit message. When omitted, Bitbucket uses a canned string.
        required: false
        schema:
          type: string
      - name: author
        in: query
        description: '

          The raw string to be used as the new Commits author.

          This string follows the format

          `Erik van Zijst <evzijst@atlassian.com>`.


          When omitted, Bitbucket uses the authenticated user''s

          full/display name and primary email address. Commits cannot

          be created anonymously.'
        required: false
        schema:
          type: string
      - name: parents
        in: query
        description: '

          A comma-separated list of SHA1s of the commits that should

          be the parents of the newly created commit.


          When omitted, the new commit will inherit from and become

          a child of the main branch''s tip/HEAD commit.


          When more than one SHA1 is provided, the first SHA1

          identifies the commit from which the content will be

          inherited.".'
        required: false
        schema:
          type: string
      - name: files
        in: query
        description: '

          Optional field that declares the files that the request is

          manipulating. When adding a new file to a repo, or when

          overwriting an existing file, the client can just upload

          the full contents of the file in a normal form field and

          the use of this `files` meta data field is redundant.

          However, when the `files` field contains a file path that

          does not have a corresponding, identically-named form

          field, then Bitbucket interprets that as the client wanting

          to replace the named file with the null set and the file is

          deleted instead.


          Paths in the repo that are referenced in neither files nor

          an individual file field, remain unchanged and carry over

          from the parent to the new commit.


          This API does not support renaming as an explicit feature.

          To rename a file, simply delete it and recreate it under

          the new name in the same commit.

          '
        required: false
        schema:
          type: string
      - name: branch
        in: query
        description: '

          The name of the branch that the new commit should be

          created on. When omitted, the commit will be created on top

          of the main branch and will become the main branch''s new

          head.


          When a branch name is provided that already exists in the

          repo, then the commit will be created on top of that

          branch. In this case, *if* a parent SHA1 was also provided,

          then it is asserted that the parent is the branch''s

          tip/HEAD at the time the request is made. When this is not

          the case, a 409 is returned.


          When a new branch name is specified (that does not already

          exist in the repo), and no parent SHA1s are provided, then

          the new commit will inherit from the current main branch''s

          tip/HEAD commit, but not advance the main branch. The new

          commit will be the new branch. When the request *also*

          specifies a parent SHA1, then the new commit and branch

          are created directly on top of the parent commit,

          regardless of the state of the main branch.


          When a branch name is not specified, but a parent SHA1 is

          provided, then Bitbucket asserts that it represents the

          main branch''s current HEAD/tip, or a 409 is returned.


          When a branch name is not specified and the repo is empty,

          the new commit will become the repo''s root commit and will

          be on the main branch.


          When a branch name is specified and the repo is empty, the

          new commit will become the repo''s root commit and also

          define the repo''s main branch going forward.


          This API cannot be used to create additional root commits

          in non-empty repos.


          The branch field cannot be repeated.


          As a side effect, this API can be used to create a new

          branch without modifying any files, by specifying a new

          branch name in this field, together with `parents`, but

          omitting the `files` fields, while not sending any files.

          This will create a new commit and branch with the same

          contents as the first parent. The diff of this commit

          against its first parent will be empty.

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - repository:write
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - write:repository:bitbucket
      operationId: createCommitByUploadingFile
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/src/{commit}/{path}:
    parameters:
    - name: commit
      in: path
      description: The Commits SHA1.
      required: true
      schema:
        type: string
    - name: path
      in: path
      description: Path to the file.
      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:
      - Files
      description: This GET operation retrieves the raw content of a file or the contents of a directory from a specific Bitbucket repository at a particular commit. By providing the workspace identifier, repository slug, commit hash or branch name, and the file or directory path, users can access the exact state of their source code at any point in the repository's history. When targeting a file, the endpoint returns the raw file content, while targeting a directory returns a listing of its contents including files and subdirectories with their metadata, making it essential for browsing repository structure, retrieving specific versions of files, or implementing custom code review and analysis tools.
      summary: Atlassian Get File or Directory Contents
      responses:
        '200':
          description: 'If the path matches a file, then the raw contents of the file are

            returned.  If the `format=meta` query parameter is provided,

            a json document containing the file''s meta data is

            returned.  If the `format=rendered` query parameter is provided,

            the contents of the file in HTML-formated rendered markup is returned.

            If the path matches a directory, then a paginated

            list of file and directory entries is returned (if the

            `format=meta` query parameter was provided, then the json document

            containing the directory''s meta data is returned.)

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_treeentries'
              examples:
                paginated-tree-entry_2:
                  $ref: '#/components/examples/paginated-tree-entry_2'
        '404':
          description: If the path or commit in the URL does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '555':
          description: If the call times out, possibly because the specified recursion depth is too large.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: format
        in: query
        description: 'If ''meta'' is provided, returns the (json) meta data for the contents of the file.  If ''rendered'' is provided, returns the contents of a non-binary file in HTML-formatted rendered markup. The ''rendered'' option only supports these filetypes: `.md`, `.markdown`, `.mkd`, `.mkdn`, `.mdown`, `.text`, `.rst`, and `.textile`. Since Git does not generally track what text encoding scheme is used, this endpoint attempts to detect the most appropriate character encoding. While usually correct, determining the character encoding can be ambiguous which in exceptional cases can lead to misinterpretation of the characters. As such, the raw element in the response object should not be treated as equivalent to the file''s actual contents.'
        required: false
        schema:
          type: string
          enum:
          - meta
          - rendered
      - name: q
        in: query
        description: Optional filter expression as per [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: Optional sorting parameter as per [filtering and sorting](/cloud/bitbucket/rest/intro/#sorting-query-results).
        required: false
        schema:
          type: string
      - name: max_depth
        in: query
        description: If provided, returns the contents of the repository and its subdirectories recursively until the specified max_depth of nested directories. When omitted, this defaults to 1.
        required: false
        schema:
          type: integer
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      operationId: getFileOrDirectoryContents
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /snippets/{workspace}/{encoded_id}/files/{path}:
    parameters:
    - name: encoded_id
      in: path
      description: The snippet id.
      required: true
      schema:
        type: string
    - name: path
      in: path
      description: Path to the file.
      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:
      - Files
      description: Retrieves the raw, unrendered content of a specific file from a snippet at its latest HEAD revision in Atlassian Bitbucket. This endpoint requires specifying the workspace identifier, the encoded snippet ID, and the full path to the file within the snippet's file structure. The operation returns the file's content in its original format without any Bitbucket rendering or formatting applied, making it useful for programmatically accessing snippet files for download, processing, or display in external applications. Authentication is typically required based on the snippet's visibility settings, with private snippets requiring appropriate permissions to access the raw file content.
      summary: Atlassian Get Snippets Raw File at Head
      responses:
        '302':
          description: A redirect to the most recent revision of the specified file.
          headers:
            Location:
              description: The URL of the most recent file revision.
              schema:
                type: string
        '403':
          description: If the authenticated user does not have access to the snippet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the snippet does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - snippet
      - basic: []
      - api_key: []
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
      operationId: getSnippetsRawFileAtHead
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /snippets/{workspace}/{encoded_id}/{node_id}/files/{path}:
    parameters:
    - name: encoded_id
      in: path
      description: The snippet id.
      required: true
      schema:
        type: string
    - name: node_id
      in: path
      description: A commit revision (SHA1).
      required: true
      schema:
        type: string
    - name: path
      in: path
      description: Path to the file.
      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:
      - Files
      description: This API operation retrieves the raw content of a specific file within a particular revision of a Bitbucket snippet. By providing the workspace identifier, the encoded snippet ID, a specific node ID (representing a commit or revision), and the file path, you can access the unprocessed file content directly. This is particularly useful when you need to programmatically fetch the exact contents of a snippet file at a specific point in its version history, whether for display purposes, downloading, or further processing in your application.
      summary: Atlassian Get Snippets Raw File
      responses:
        '200':
          description: Returns the contents of the specified file.
          headers:
            Content-Type:
              description: The mime type as derived from the filename
              schema:
                type: string
            Content-Disposition:
              description: attachment
              schema:
                type: string
        '403':
          description: If the authenticated user does not have access to the snippet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the file or snippet does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - snippet
      - basic: []
      - api_key: []
      x-api-evangelist-processing:
        PascalCaseOperationSummaries: true
        CaselCaseOperationIds: true
        WriteDescription: true
        ChooseTags: true
      operationId: getSnippetsRawFile
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    account:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Account
        description: An account object.
        properties:
          links:
            $ref: '#/components/schemas/account_links'
          created_on:
            type: string
            format: date-time
          display_name:
            type: string
          username:
            type: string
            pattern: ^[a-zA-Z0-9_\-]+$
          uuid:
            type: string
        additionalProperties: true
    participant:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Participant
        description: Object describing a user's role on resources like commits or pull requests.
        properties:
          user:
            $ref: '#/components/schemas/account'
          role:
            type: string
            enum:
            - PARTICIPANT
            - REVIEWER
          approved:
            type: boolean
          state:
            type: string
            enum:
            - approved
            - changes_requested
            - null
          participated_on:
            type: string
            description: The ISO8601 timestamp of the participant's action. For approvers, this is the time of their approval. For commenters and pull request reviewers who are not approvers, this is the time they last commented, or null if they have not commented.
            format: date-time
        additionalProperties: true
    team_links:
      allOf:
      - $ref: '#/components/schemas/account_links'
      - type: object
        title: Team Links
        description: Links related to a Team.
        properties:
          self:
            $ref: '#/components/schemas/link'
          html:
            $ref: '#/components/schemas/link'
          members:
            $ref: '#/components/schemas/link'
          projects:
            $ref: '#/components/schemas/link'
          repositories:
            $ref: '#/components/schemas/link'
        additionalProperties: true
    project:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Project
        description: "A Bitbucket project.\n            Projects are used by teams to organize repositories."
        properties:
          links:
            type: object
            properties:
              html:
                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
              avatar:
                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 project's immutable id.
          key:
            type: string
            description: The project's key.
          owner:
            $ref: '#/components/schemas/team'
          name:
            type: string
            description: The name of the project.
          description:
            type: string
          is_private:
            type: boolean
            description: '

              Indicates whether the project is publicly accessible, or whether it is

              private to the team and consequently only visible to team members.

              Note that private projects cannot contain public repositories.'
          created_on:
            type: string
            format: date-time
          updated_on:
            type: string
            format: date-time
          has_publicly_visible_repos:
            type: boolean
            description: '

              Indicates whether the project contains publicly visible repositories.

              Note that private projects cannot contain public repositories.'
        additionalProperties: true
    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
    author:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Author
        description: The author of a change in a repository
        properties:
          raw:
            type: string
            description: The raw author value from the repository. This may be the only value available if the author does not match a user in Bitbucket.
          user:
            $ref: '#/components/schemas/account'
        additionalProperties: true
    team:
      allOf:
      - $ref: '#/components/schemas/account'
      - type: object
        title: Team
        description: A team object.
        properties:
          links:
            $ref: '#/components/schemas/team_links'
        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
    repository:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Repository
        description: A Bitbucket repository.
        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
              html:
                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
              avatar:
                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
              pullrequests:
                type: object
                title: Link
                description: A link to a resource related to this object.
   

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