Bitbucket Search API

openapi: 3.2.0
info:
  title: Bitbucket Addon Search 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: Search
paths:
  /teams/{username}/search/code:
    get:
      tags:
      - Search
      summary: Search for code in a team's repositories
      description: 'Search for code in the repositories of the specified team.


        Note that searches can match in the file''s text (`content_matches`),

        the path (`path_matches`), or both.


        You can use the same syntax for the search query as in the UI.

        E.g. to search for "foo" only within the repository "demo",

        use the query parameter `search_query=foo+repo:demo`.


        Similar to other APIs, you can request more fields using a

        `fields` query parameter. E.g. to get some more information about

        the repository of matched files, use the query parameter

        `search_query=foo&fields=%2Bvalues.file.commit.repository`

        (the `%2B` is a URL-encoded `+`).


        Try `fields=%2Bvalues.*.*.*.*` to get an idea what''s possible.

        '
      operationId: searchTeam
      parameters:
      - name: username
        in: path
        description: The account to search in; either the username or the UUID in curly braces
        required: true
        schema:
          type: string
      - name: search_query
        in: query
        description: The search query
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Which page of the search results to retrieve
        required: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pagelen
        in: query
        description: How many search results to retrieve per page
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Successful search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_result_page'
              example:
                size: 1
                page: 1
                pagelen: 10
                query_substituted: false
                values:
                - type: code_search_result
                  content_match_count: 2
                  content_matches:
                  - lines:
                    - line: 2
                      segments: []
                    - line: 3
                      segments:
                      - text: 'def '
                      - text: foo
                        match: true
                      - text: '():'
                    - line: 4
                      segments:
                      - text: '    print("snek")'
                    - line: 5
                      segments: []
                  path_matches:
                  - text: src/
                  - text: foo
                    match: true
                  - text: .py
                  file:
                    path: src/foo.py
                    type: commit_file
                    links:
                      self:
                        href: https://api.bitbucket.org/2.0/repositories/my-workspace/demo/src/ad6964b5fe2880dbd9ddcad1c89000f1dbcbc24b/src/foo.py
        '400':
          description: 'If the search request was invalid due to one of the

            following reasons:


            * the specified type of target account doesn''''t match the actual

            account type;


            * malformed pagination properties;


            * missing or malformed search query, in the latter case an error

            key will be returned in `error.data.key` property.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Search is not enabled for the requested team, navigate to [https://bitbucket.org/search](https://bitbucket.org/search) to turn it on
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: Too many requests, try again later
          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:
      - api-token
  /users/{selected_user}/search/code:
    get:
      tags:
      - Search
      summary: Search for code in a user's repositories
      description: 'Search for code in the repositories of the specified user.


        Note that searches can match in the file''s text (`content_matches`),

        the path (`path_matches`), or both.


        You can use the same syntax for the search query as in the UI.

        E.g. to search for "foo" only within the repository "demo",

        use the query parameter `search_query=foo+repo:demo`.


        Similar to other APIs, you can request more fields using a

        `fields` query parameter. E.g. to get some more information about

        the repository of matched files, use the query parameter

        `search_query=foo&fields=%2Bvalues.file.commit.repository`

        (the `%2B` is a URL-encoded `+`).

        '
      operationId: searchAccount
      parameters:
      - name: selected_user
        in: path
        description: Either the UUID of the account surrounded by curly-braces, for example `{account UUID}`, OR an Atlassian Account ID.
        required: true
        schema:
          type: string
      - name: search_query
        in: query
        description: The search query
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Which page of the search results to retrieve
        required: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pagelen
        in: query
        description: How many search results to retrieve per page
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Successful search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_result_page'
              example:
                size: 1
                page: 1
                pagelen: 10
                query_substituted: false
                values:
                - type: code_search_result
                  content_match_count: 2
                  content_matches:
                  - lines:
                    - line: 2
                      segments: []
                    - line: 3
                      segments:
                      - text: 'def '
                      - text: foo
                        match: true
                      - text: '():'
                    - line: 4
                      segments:
                      - text: '    print("snek")'
                    - line: 5
                      segments: []
                  path_matches:
                  - text: src/
                  - text: foo
                    match: true
                  - text: .py
                  file:
                    path: src/foo.py
                    type: commit_file
                    links:
                      self:
                        href: https://api.bitbucket.org/2.0/repositories/my-workspace/demo/src/ad6964b5fe2880dbd9ddcad1c89000f1dbcbc24b/src/foo.py
        '400':
          description: 'If the search request was invalid due to one of the

            following reasons:


            * the specified type of target account doesn''''t match the actual

            account type;


            * malformed pagination properties;


            * missing or malformed search query, in the latter case an error

            key will be returned in `error.data.key` property.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Search is not enabled for the requested user, navigate to [https://bitbucket.org/search](https://bitbucket.org/search) to turn it on
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: Too many requests, try again later
          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:
      - api-token
  /workspaces/{workspace}/search/code:
    get:
      tags:
      - Search
      summary: Search for code in a workspace
      description: 'Search for code in the repositories of the specified workspace.


        Note that searches can match in the file''s text (`content_matches`),

        the path (`path_matches`), or both.


        You can use the same syntax for the search query as in the UI.

        E.g. to search for "foo" only within the repository "demo",

        use the query parameter `search_query=foo+repo:demo`.


        Similar to other APIs, you can request more fields using a

        `fields` query parameter. E.g. to get some more information about

        the repository of matched files, use the query parameter

        `search_query=foo&fields=%2Bvalues.file.commit.repository`

        (the `%2B` is a URL-encoded `+`).


        Try `fields=%2Bvalues.*.*.*.*` to get an idea what''s possible.

        '
      operationId: searchWorkspace
      parameters:
      - name: workspace
        in: path
        description: The workspace to search in; either the slug or the UUID in curly braces
        required: true
        schema:
          type: string
      - name: search_query
        in: query
        description: The search query
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Which page of the search results to retrieve
        required: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pagelen
        in: query
        description: How many search results to retrieve per page
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: Successful search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/search_result_page'
              example:
                size: 1
                page: 1
                pagelen: 10
                query_substituted: false
                values:
                - type: code_search_result
                  content_match_count: 2
                  content_matches:
                  - lines:
                    - line: 2
                      segments: []
                    - line: 3
                      segments:
                      - text: 'def '
                      - text: foo
                        match: true
                      - text: '():'
                    - line: 4
                      segments:
                      - text: '    print("snek")'
                    - line: 5
                      segments: []
                  path_matches:
                  - text: src/
                  - text: foo
                    match: true
                  - text: .py
                  file:
                    path: src/foo.py
                    type: commit_file
                    links:
                      self:
                        href: https://api.bitbucket.org/2.0/repositories/my-workspace/demo/src/ad6964b5fe2880dbd9ddcad1c89000f1dbcbc24b/src/foo.py
        '400':
          description: 'If the search request was invalid due to one of the

            following reasons:


            * the specified type of target account doesn''''t match the actual

            account type;


            * malformed pagination properties;


            * missing or malformed search query, in the latter case an error

            key will be returned in `error.data.key` property.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Search is not enabled for the requested workspace, navigate to [https://bitbucket.org/search](https://bitbucket.org/search) to turn it on
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: Too many requests, try again later
          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:
      - api-token
components:
  schemas:
    ref:
      type: object
      title: Ref
      description: A ref object, representing a branch or tag in a repository.
      properties:
        type:
          type: string
        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
            commits:
              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
          additionalProperties: false
        name:
          type: string
          description: The name of the ref.
        target:
          $ref: '#/components/schemas/commit'
      required:
      - type
      additionalProperties: true
    commit:
      allOf:
      - $ref: '#/components/schemas/base_commit'
      - type: object
        title: Commit
        description: A repository commit object.
        properties:
          repository:
            $ref: '#/components/schemas/repository'
          participants:
            type: array
            items:
              $ref: '#/components/schemas/participant'
            minItems: 0
        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
    search_code_search_result:
      type: object
      properties:
        type:
          type: string
          readOnly: true
        content_match_count:
          type: integer
          format: int64
          readOnly: true
        content_matches:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/search_content_match'
        path_matches:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/search_segment'
        file:
          readOnly: true
          $ref: '#/components/schemas/commit_file'
    search_line:
      type: object
      properties:
        line:
          type: integer
          format: int32
          readOnly: true
        segments:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/search_segment'
    commit_file:
      type: object
      title: Commit File
      description: A file object, representing a file at a commit in a repository
      properties:
        type:
          type: string
        path:
          type: string
          description: The path in the repository
        commit:
          $ref: '#/components/schemas/commit'
        attributes:
          type: string
          enum:
          - link
          - executable
          - subrepository
          - binary
          - lfs
        escaped_path:
          type: string
          description: The escaped version of the path as it appears in a diff. If the path does not require escaping this will be the same as path.
      required:
      - type
      additionalProperties: true
    search_segment:
      type: object
      properties:
        text:
          type: string
          readOnly: true
        match:
          type: boolean
          readOnly: true
    account_links:
      type: object
      title: Account Links
      description: Links related to an Account.
      properties:
        avatar:
          $ref: '#/components/schemas/link'
      additionalProperties: true
    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.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              commits:
                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
              forks:
                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
              watchers:
                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
              downloads:
                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
              clone:
                type: array
                items:
                  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
              hooks:
                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 repository's immutable id. This can be used as a substitute for the slug segment in URLs. Doing this guarantees your URLs will survive renaming of the repository by its owner, or even transfer of the repository to a different user.
          full_name:
            type: string
            description: The concatenation of the repository owner's username and the slugified name, e.g. "evzijst/interruptingcow". This is the same string used in Bitbucket URLs.
          is_private:
            type: boolean
          parent:
            $ref: '#/components/schemas/repository'
          scm:
            type: string
            enum:
            - git
          owner:
            $ref: '#/components/schemas/account'
          name:
            type: string
          description:
            type: string
          created_on:
            type: string
            format: date-time
          updated_on:
            type: string
            format: date-time
          size:
            type: integer
          language:
            type: string
          has_issues:
            type: boolean
            description: '

              The issue tracker for this repository is enabled. Issue Tracker

              features are not supported for repositories in workspaces

              administered through admin.atlassian.com.

              '
          has_wiki:
            type: boolean
            description: '

              The wiki for this repository is enabled. Wiki

              features are not supported for repositories in workspaces

              administered through admin.atlassian.com.

              '
          fork_policy:
            type: string
            description: "\nControls the rules for forking this repository.\n\n* **allow_forks**: unrestricted forking\n* **no_public_forks**: restrict forking to private forks (forks cannot\n  be made public later)\n* **no_forks**: deny all forking\n"
            enum:
            - allow_forks
            - no_public_forks
            - no_forks
          project:
            $ref: '#/components/schemas/project'
          mainbranch:
            $ref: '#/components/schemas/branch'
        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
    search_result_page:
      type: object
      properties:
        size:
          type: integer
          format: int64
          readOnly: true
        page:
          type: integer
          format: int32
          readOnly: true
        pagelen:
          type: integer
          format: int32
          readOnly: true
        query_substituted:
          type: boolean
          readOnly: true
        next:
          type: string
          format: uri
          readOnly: true
        previous:
          type: string
          format: uri
          readOnly: true
        values:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/search_code_search_result'
    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
    team:
      allOf:
      - $ref: '#/components/schemas/account'
      - type: object
        title: Team
        description: A team object.
        properties:
          links:
            $ref: '#/components/schemas/team_links'
        additionalProperties: true
    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
          uuid:
            type: string
        additionalProperties: true
    link:
      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
    base_commit:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Base Commit
        description: The common base type for both repository and snippet commits.
        properties:
          hash:
            type: string
            pattern: '[0-9a-f]{7,}?'
          date:
            type: string
            format: date-time
          author:
            $ref: '#/components/schemas/author'
          committer:
            $ref: '#/components/schemas/committer'
          message:
            type: string
          summary:
            type: object
            properties:
              raw:
                type: string
                description: The text as it was typed by a user.
              markup:
                type: string
                description: The type of markup language the raw content is to be interpreted in.
                enum:
                - markdown
                - creole
                - plaintext
              html:
                type: string
                description: The user's content rendered as HTML.
            additionalProperties: false
          parents:
            type: array
            items:
              $ref: '#/components/schemas/base_commit'
            minItems: 0
        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
    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
    committer:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Committer
        description: The committer of a change in a repository
        properties:
          raw:
            type: string
            description: The raw committer value from the repository. This may be the only value available if the committer does not match a user in Bitbucket.
          user:
            $ref: '#/components/schemas/account'
        additionalProperties: true
    branch:
      allOf:
      - $ref: '#/components/schemas/ref'
      - type: object
        title: Branch
        description: A branch object, representing a branch in a repository.
        properties:
          merge_strategies:
            type: array
            description: Available merge strategies for pull requests targeting this branch.
     

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