Bitbucket Pipelines Search API
The Search API from Bitbucket Pipelines — 3 operation(s) for search.
OpenAPI Specification
swagger: '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
host: api.bitbucket.org
basePath: /2.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Search
paths:
/teams/{username}/search/code:
get:
tags:
- Search
deprecated: true
summary: Search for code in a team's repositories
description: 'This API will be deprecated on November 1, 2026.
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
produces:
- application/json
parameters:
- name: username
in: path
description: The account to search in; either the username or the UUID in curly braces
required: true
type: string
- name: search_query
in: query
description: The search query
required: true
type: string
- name: page
in: query
description: Which page of the search results to retrieve
required: false
type: integer
default: 1
format: int32
- name: pagelen
in: query
description: How many search results to retrieve per page
required: false
type: integer
default: 10
format: int32
responses:
'200':
description: Successful search
schema:
$ref: '#/definitions/search_result_page'
examples:
application/json:
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.
'
schema:
$ref: '#/definitions/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
schema:
$ref: '#/definitions/error'
'429':
description: Too many requests, try again later
schema:
$ref: '#/definitions/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
deprecated: true
summary: Search for code in a user's repositories
description: 'This API will be deprecated on November 1, 2026.
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
produces:
- application/json
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
type: string
- name: search_query
in: query
description: The search query
required: true
type: string
- name: page
in: query
description: Which page of the search results to retrieve
required: false
type: integer
default: 1
format: int32
- name: pagelen
in: query
description: How many search results to retrieve per page
required: false
type: integer
default: 10
format: int32
responses:
'200':
description: Successful search
schema:
$ref: '#/definitions/search_result_page'
examples:
application/json:
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.
'
schema:
$ref: '#/definitions/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
schema:
$ref: '#/definitions/error'
'429':
description: Too many requests, try again later
schema:
$ref: '#/definitions/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
deprecated: true
summary: Search for code in a workspace
description: '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.
'
operationId: searchWorkspace
produces:
- application/json
parameters:
- name: workspace
in: path
description: The workspace to search in; either the slug or the UUID in curly braces
required: true
type: string
- name: search_query
in: query
description: The search query
required: true
type: string
- name: page
in: query
description: Which page of the search results to retrieve
required: false
type: integer
default: 1
format: int32
- name: pagelen
in: query
description: How many search results to retrieve per page
required: false
type: integer
default: 10
format: int32
responses:
'200':
description: Successful search
schema:
$ref: '#/definitions/search_result_page'
examples:
application/json:
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.
'
schema:
$ref: '#/definitions/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
schema:
$ref: '#/definitions/error'
'429':
description: Too many requests, try again later
schema:
$ref: '#/definitions/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
definitions:
project:
allOf:
- $ref: '#/definitions/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: '#/definitions/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
base_commit:
allOf:
- $ref: '#/definitions/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: '#/definitions/author'
committer:
$ref: '#/definitions/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: '#/definitions/base_commit'
minItems: 0
additionalProperties: true
search_line:
type: object
properties:
line:
type: integer
format: int32
readOnly: true
segments:
type: array
readOnly: true
items:
$ref: '#/definitions/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: '#/definitions/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_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: '#/definitions/search_code_search_result'
account:
allOf:
- $ref: '#/definitions/object'
- type: object
title: Account
description: An account object.
properties:
links:
$ref: '#/definitions/account_links'
created_on:
type: string
format: date-time
display_name:
type: string
uuid:
type: string
additionalProperties: true
branch:
allOf:
- $ref: '#/definitions/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.
items:
type: string
enum:
- merge_commit
- squash
- fast_forward
- squash_fast_forward
- rebase_fast_forward
- rebase_merge
default_merge_strategy:
type: string
description: The default merge strategy for pull requests targeting this branch.
additionalProperties: true
participant:
allOf:
- $ref: '#/definitions/object'
- type: object
title: Participant
description: Object describing a user's role on resources like commits or pull requests.
properties:
user:
$ref: '#/definitions/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
search_segment:
type: object
properties:
text:
type: string
readOnly: true
match:
type: boolean
readOnly: true
team_links:
allOf:
- $ref: '#/definitions/account_links'
- type: object
title: Team Links
description: Links related to a Team.
properties:
self:
$ref: '#/definitions/link'
html:
$ref: '#/definitions/link'
members:
$ref: '#/definitions/link'
projects:
$ref: '#/definitions/link'
repositories:
$ref: '#/definitions/link'
additionalProperties: true
search_content_match:
type: object
properties:
lines:
type: array
readOnly: true
items:
$ref: '#/definitions/search_line'
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: '#/definitions/commit'
required:
- type
additionalProperties: true
author:
allOf:
- $ref: '#/definitions/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: '#/definitions/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: '#/definitions/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: '#/definitions/account'
additionalProperties: true
account_links:
type: object
title: Account Links
description: Links related to an Account.
properties:
avatar:
$ref: '#/definitions/link'
additionalProperties: true
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: '#/definitions/search_content_match'
path_matches:
type: array
readOnly: true
items:
$ref: '#/definitions/search_segment'
file:
readOnly: true
$ref: '#/definitions/commit_file'
commit:
allOf:
- $ref: '#/definitions/base_commit'
- type: object
title: Commit
description: A repository commit object.
properties:
repository:
$ref: '#/definitions/repository'
participants:
type: array
items:
$ref: '#/definitions/participant'
minItems: 0
additionalProperties: true
repository:
allOf:
- $ref: '#/definitions/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: '#/definitions/repository'
scm:
type: string
enum:
- git
owner:
$ref: '#/definitions/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: '#/definitions/project'
mainbranch:
$ref: '#/definitions/branch'
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
team:
allOf:
- $ref: '#/definitions/account'
- type: object
title: Team
description: A team object.
properties:
links:
$ref: '#/definitions/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
required:
- type
additionalProperties: true
discriminator: type
securityDefinitions:
basic:
type: 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
description: OAuth 2 as per [RFC-6749](https://tools.ietf.org/html/rfc6749).
flow: accessCode
authorizationUrl: https://bitbucket.org/site/oauth2/authorize
tokenUrl: https://bitbucket.org/site/oauth2/access_token
scopes:
repository: Read your repositories
repository:write: Read and modify your repositories
repository:admin: Administer your repositorie
# --- truncated at 32 KB (143 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket-pipelines/refs/heads/main/openapi/bitbucket-pipelines-search-api-openapi.yml