Search for code in a workspace

Deprecated

GET

/workspaces/{workspace}/search/code

This API will be deprecated on November 1, 2026.

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.

Authorizations

oauth2
repository
basic
api_key

Parameters

Path Parameters

workspace

required

string

The workspace to search in; either the slug or the UUID in curly braces

Query Parameters

search_query

required

string

The search query

page

integer format: int32

default: 1

Which page of the search results to retrieve

pagelen

integer format: int32

default: 10

How many search results to retrieve per page

Responses

200

Successful search

application/json

object

size

integer format: int64

page

integer format: int32

pagelen

integer format: int32

query_substituted

boolean

next

string format: uri

previous

string format: uri

values

Array<object>

object

type

string

content_match_count

integer format: int64

content_matches

Array<object>

object

lines

Array<object>

object

line

integer format: int32

segments

Array<object>

object

text

string

match

boolean

path_matches

Array<object>

object

text

string

match

boolean

file

Commit File

A file object, representing a file at a commit in a repository

object

type

required

string

path

The path in the repository

string

commit

object

type

required

string

hash

string

/[0-9a-f]{7,}?/

date

string format: date-time

author

object

type

required

string

raw

The raw author value from the repository. This may be the only value available if the author does not match a user in Bitbucket.

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

committer

object

type

required

string

raw

The raw committer value from the repository. This may be the only value available if the committer does not match a user in Bitbucket.

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

message

string

summary

object

raw

The text as it was typed by a user.

string

markup

The type of markup language the raw content is to be interpreted in.

string

Allowed values: markdown creole plaintext

html

The user’s content rendered as HTML.

string

parents

Array<object> recursive

repository

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

pullrequests

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

commits

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

forks

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

watchers

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

downloads

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

clone

Array<object>

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

hooks

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

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.

string

full_name

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.

string

is_private

boolean

parent

object recursive

scm

string

Allowed values: git

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

name

string

description

string

created_on

string format: date-time

updated_on

string format: date-time

size

integer

language

string

has_issues

The issue tracker for this repository is enabled. Issue Tracker features are not supported for repositories in workspaces administered through admin.atlassian.com.

boolean

has_wiki

The wiki for this repository is enabled. Wiki features are not supported for repositories in workspaces administered through admin.atlassian.com.

boolean

fork_policy

Controls the rules for forking this repository.

allow_forks: unrestricted forking
no_public_forks: restrict forking to private forks (forks cannot be made public later)
no_forks: deny all forking

string

Allowed values: allow_forks no_public_forks no_forks

project

object

type

required

string

links

object

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

uuid

The project’s immutable id.

string

key

The project’s key.

string

owner

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

links

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

members

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

projects

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

repositories

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

name

The name of the project.

string

description

string

is_private

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.

boolean

created_on

string format: date-time

updated_on

string format: date-time

has_publicly_visible_repos

Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories.

boolean

mainbranch

object

type

required

string

links

object

self

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

commits

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

html

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

name

The name of the ref.

string

target

object recursive

merge_strategies

Available merge strategies for pull requests targeting this branch.

Array<string>

Allowed values: merge_commit squash fast_forward squash_fast_forward rebase_fast_forward rebase_merge

default_merge_strategy

The default merge strategy for pull requests targeting this branch.

string

participants

Array

object

type

required

string

user

object

type

required

string

links

Account Links

Links related to an Account.

object

avatar

Link

A link to a resource related to this object.

object

href

string format: uri

name

string

key

additional properties

any

created_on

string format: date-time

display_name

string

uuid

string

role

string

Allowed values: PARTICIPANT REVIEWER

approved

boolean

state

string

Allowed values: approved changes_requested

participated_on

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.

string format: date-time

attributes

string

Allowed values: link executable subrepository binary lfs

escaped_path

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.

string

key

additional properties

any

Examples

response

{
  "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

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.

application/json

Error

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.

object

type

required

string

error

object

message

required

string

detail

string

data

Optional structured data that is endpoint-specific.

object

key

additional properties

any

key

additional properties

any

Example ^generated

{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

404

Search is not enabled for the requested workspace, navigate to https://bitbucket.org/search to turn it on

application/json

Error

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.

object

type

required

string

error

object

message

required

string

detail

string

data

Optional structured data that is endpoint-specific.

object

key

additional properties

any

key

additional properties

any

Example ^generated

{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

429

Too many requests, try again later

application/json

Error

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.

object

type

required

string

error

object

message

required

string

detail

string

data

Optional structured data that is endpoint-specific.

object

key

additional properties

any

key

additional properties

any

Example ^generated

{
  "type": "example",
  "error": {
    "message": "example",
    "detail": "example",
    "data": {}
  }
}

Search for code in a workspace

Authorizations

Parameters

Path Parameters

Query Parameters

Responses

200

Examples

400

Example generated

404

Example generated

429

Example generated

Example ^generated

Example ^generated

Example ^generated