openapi: 3.0.0 info: title: Atlassian Bit Bucket Workspaces API description: >- The Atlassian BitBucket Workspaces API is a powerful tool that allows users to manage and interact with multiple projects within their BitBucket account. With this API, users can create, update, and delete workspaces, as well as manage permissions and settings for each workspace. Additionally, the API enables users to create and manage repositories within their workspaces, facilitating collaboration and efficient project management. 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 paths: /workspaces/{workspace}: get: tags: - Get - Workspaces description: >- This API operation retrieves detailed information about a specific workspace by making a GET request to the endpoint /workspaces/{workspace}, where {workspace} is a path parameter representing the unique identifier of the workspace you want to access. When executed, it returns the complete data and configuration settings associated with that particular workspace, allowing users or applications to view workspace properties, metadata, and current state information without making any modifications to the workspace itself. summary: Atlassian Get A Workspace responses: '200': description: The workspace. content: application/json: schema: $ref: '#/components/schemas/workspace' examples: workspace: $ref: '#/components/examples/workspace' '404': description: If no workspace exists for the specified name or UUID. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: [] - basic: [] - api_key: [] operationId: atlassianGetAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - 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 /workspaces/{workspace}/hooks: get: tags: - Lists - Webhooks - Workspaces description: >- This API operation retrieves a paginated list of all webhooks that have been configured for a specific Bitbucket workspace. By making a GET request to the /workspaces/{workspace}/hooks endpoint with the workspace identifier, users can view all webhook subscriptions associated with that workspace, including details about the webhook URLs, events they're subscribed to, and their current status. This is useful for auditing, managing, or discovering existing webhook integrations that send HTTP callbacks to external services when specific events occur within the workspace, such as repository pushes, pull request updates, or other Bitbucket activities. summary: Atlassian List Webhooks For A Workspace responses: '200': description: The paginated list of installed webhooks. content: application/json: schema: $ref: '#/components/schemas/paginated_webhook_subscriptions' examples: paginated-webhook-subscriptions: $ref: '#/components/examples/paginated-webhook-subscriptions' '403': description: >- If the authenticated user is not an owner on the specified workspace. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified workspace does not exist. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - webhook - basic: [] - api_key: [] operationId: atlassianListWebhooksForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true post: tags: - Create - Webhooks - Workspaces description: >- This API operation creates a new webhook for a specified Bitbucket workspace by sending a POST request to the /workspaces/{workspace}/hooks endpoint. Webhooks allow workspaces to receive real-time HTTP callbacks when specific events occur within the workspace, such as repository pushes, pull requests, or issue updates. The workspace is identified by the {workspace} path parameter, which represents the workspace ID or slug. The request typically requires authentication and a JSON payload containing webhook configuration details including the target URL where events should be sent, a description, and the specific events to subscribe to. Upon successful creation, the API returns the newly created webhook object with its unique identifier and configuration details, enabling automated integrations and event-driven workflows between Bitbucket and external systems or services. summary: Atlassian Create A Webhook For A Workspace responses: '201': description: If the webhook was registered successfully. headers: Location: description: The URL of new newly created webhook. schema: type: string content: application/json: schema: $ref: '#/components/schemas/webhook_subscription' examples: webhook-subscription: $ref: '#/components/examples/webhook-subscription' '403': description: >- If the authenticated user does not have permission to install webhooks on the specified workspace. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified workspace does not exist. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - webhook - basic: [] - api_key: [] operationId: atlassianCreateAWebhookForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - 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 /workspaces/{workspace}/hooks/{uid}: delete: tags: - Delete - Webhooks - Workspaces description: >- The DELETE operation on the /workspaces/{workspace}/hooks/{uid} endpoint in the Atlassian Bitbucket Workspaces API removes a specific webhook from a workspace. This endpoint requires two path parameters: the workspace identifier and the unique identifier (uid) of the webhook to be deleted. When executed successfully, it permanently removes the webhook configuration, stopping all future webhook event notifications from being sent to the previously configured URL for that workspace. This operation is typically used when a webhook is no longer needed, when cleaning up old integrations, or when reconfiguring webhook settings by removing the old webhook before creating a new one. Authentication and appropriate workspace permissions are required to perform this delete operation. summary: Atlassian Delete A Webhook For A Workspace responses: '204': description: When the webhook was deleted successfully '403': description: >- If the authenticated user does not have permission to delete the webhook. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the webhook or workspace does not exist. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - webhook - basic: [] - api_key: [] operationId: atlassianDeleteAWebhookForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true get: tags: - Get - Webhooks description: >- This API operation retrieves detailed information about a specific webhook configured for an Atlassian Bitbucket workspace. By providing the workspace identifier and the unique webhook ID (uid) in the endpoint path, you can fetch the webhook's configuration details including its URL, events it subscribes to, active status, and other metadata. This is useful for verifying webhook settings, auditing workspace integrations, or programmatically managing webhook configurations within your Bitbucket workspace. summary: Atlassian Get A Webhook For A Workspace responses: '200': description: The webhook subscription object. content: application/json: schema: $ref: '#/components/schemas/webhook_subscription' examples: webhook-subscription_2: $ref: '#/components/examples/webhook-subscription_2' '404': description: If the webhook or workspace does not exist. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - webhook - basic: [] - api_key: [] operationId: atlassianGetAWebhookForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true put: tags: - Update - Webhooks - Workspaces description: >- This operation updates an existing webhook configuration for a specified Bitbucket workspace by making a PUT request to the endpoint with the workspace slug and webhook unique identifier (uid) in the path. It allows you to modify webhook settings such as the URL that receives the webhook payloads, the events that trigger the webhook, whether the webhook is active or inactive, and other configuration options like description and secret tokens for payload verification. The request requires authentication with appropriate permissions to manage workspace webhooks, and upon successful execution, it returns the updated webhook object with all its current configuration details including the modified properties. summary: Atlassian Update A Webhook For A Workspace responses: '200': description: The webhook subscription object. content: application/json: schema: $ref: '#/components/schemas/webhook_subscription' examples: webhook-subscription_2: $ref: '#/components/examples/webhook-subscription_2' '403': description: >- If the authenticated user does not have permission to update the webhook. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the webhook or workspace does not exist. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - webhook - basic: [] - api_key: [] operationId: atlassianUpdateAWebhookForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: uid in: path description: Installed webhook's ID 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 /workspaces/{workspace}/members: get: tags: - Lists - Users - Workspaces description: >- This API endpoint retrieves a list of all members who belong to a specified Atlassian Bitbucket workspace by making a GET request to /workspaces/{workspace}/members, where {workspace} is replaced with the unique identifier or slug of the target workspace. The operation returns member details including user information, roles, and permissions for each member associated with the workspace, allowing administrators and authorized users to view and manage workspace membership. This is particularly useful for auditing purposes, managing team access, or integrating workspace member data with external systems for user management and collaboration workflows. summary: Atlassian List Users In A Workspace responses: '200': description: The list of users that are part of a workspace. content: application/json: schema: $ref: '#/components/schemas/paginated_workspace_memberships' examples: paginated-workspace-memberships: $ref: '#/components/examples/paginated-workspace-memberships' '401': description: The request wasn't authenticated. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - account - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:workspace:bitbucket - read:user:bitbucket operationId: atlassianListUsersInAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - 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 /workspaces/{workspace}/members/{member}: get: tags: - Get - Memberships - Users - Workspaces description: >- This GET operation retrieves detailed information about a specific user's membership within a designated Bitbucket workspace. By providing the workspace identifier and member identifier in the URL path parameters, the API returns the membership details for that particular user, including their role, permissions, and associated account information within the context of the specified workspace. This endpoint is useful for administrators and applications that need to verify a user's access level, check membership status, or retrieve specific member details for workspace management purposes. summary: Atlassian Get User Membership For A Workspace responses: '200': description: The user that is part of a workspace. content: application/json: schema: $ref: '#/components/schemas/workspace_membership' examples: workspace-membership: $ref: '#/components/examples/workspace-membership' '401': description: The request wasn't authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- A workspace cannot be found, or a user cannot be found, or the user is not a a member of the workspace. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - account - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:workspace:bitbucket - read:user:bitbucket operationId: atlassianGetUserMembershipForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: member in: path description: Member's UUID or Atlassian ID. 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 /workspaces/{workspace}/permissions: get: tags: - Lists - Permissions - Users - Workspaces description: >- This API operation retrieves a list of user permissions configured within a specific Bitbucket workspace by making a GET request to the /workspaces/{workspace}/permissions endpoint, where {workspace} is the unique identifier or slug of the target workspace. It returns detailed information about which users have been granted access to the workspace and their corresponding permission levels, such as member, admin, or collaborator roles. This endpoint is useful for workspace administrators who need to audit user access, manage team permissions, or integrate workspace permission data into external systems for security and compliance purposes. The response typically includes user details like usernames, display names, and their associated permission grants within the specified workspace context. summary: Atlassian List User Permissions In A Workspace responses: '200': description: >- The list of users that are part of a workspace, along with their permission. content: application/json: schema: $ref: '#/components/schemas/paginated_workspace_memberships' examples: paginated-workspace-memberships_2: $ref: '#/components/examples/paginated-workspace-memberships_2' '401': description: The request wasn't authenticated. content: application/json: schema: $ref: '#/components/schemas/error' parameters: - name: q in: query description: |2- Query string to narrow down the response as per [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering). required: false schema: type: string security: - oauth2: - account - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:workspace:bitbucket - read:user:bitbucket operationId: atlassianListUserPermissionsInAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - 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 /workspaces/{workspace}/permissions/repositories: get: tags: - All - Lists - Permissions - Repositories - Workspaces description: >- This GET operation retrieves a comprehensive list of all repository permissions configured within a specific Bitbucket workspace. By targeting the /workspaces/{workspace}/permissions/repositories endpoint, it returns permission details for repositories in the specified workspace, allowing administrators and authorized users to audit access controls and understand who has what level of access (read, write, admin) to repositories. The {workspace} path parameter identifies the target workspace, and the response typically includes information about users, groups, and their associated permission levels across all repositories within that workspace scope. summary: Atlassian List All Repository Permissions For A Workspace responses: '200': description: List of workspace's repository permissions. content: application/json: schema: $ref: '#/components/schemas/paginated_repository_permissions' examples: paginated-repository-permissions: $ref: '#/components/examples/paginated-repository-permissions' '403': description: The requesting user isn't an admin of the workspace. content: application/json: schema: $ref: '#/components/schemas/error' parameters: - name: q in: query description: |2- 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: >2 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: - account - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:repository:bitbucket - read:user:bitbucket operationId: atlassianListAllRepositoryPermissionsForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - 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 /workspaces/{workspace}/permissions/repositories/{repo_slug}: get: tags: - Lists - Permissions - Repositories - Workspaces description: >- This API endpoint retrieves the permission settings for a specific repository within an Atlassian Bitbucket workspace. By making a GET request to this endpoint with the workspace identifier and repository slug as path parameters, users can view all the permissions that have been granted for that particular repository, including which users or groups have access and their respective permission levels (such as read, write, or admin). This is useful for workspace administrators who need to audit repository access, verify security settings, or understand who has what level of access to a given repository within their Bitbucket workspace. summary: Atlassian List A Repository Permissions For A Workspace responses: '200': description: The repository permission for all users in this repository. content: application/json: schema: $ref: '#/components/schemas/paginated_repository_permissions' examples: paginated-repository-permissions_2: $ref: '#/components/examples/paginated-repository-permissions_2' '403': description: The requesting user isn't an admin of the repository. content: application/json: schema: $ref: '#/components/schemas/error' parameters: - name: q in: query description: |2- 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: >2 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 - read:user:bitbucket operationId: atlassianListARepositoryPermissionsForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true 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 /workspaces/{workspace}/pipelines-config/identity/oidc/.well-known/openid-configuration: get: tags: - Configuration - Get - Openid Connect - Pipelines summary: Atlassian Get Openid Configuration For Oidc In Pipelines description: >- This API endpoint retrieves the OpenID Connect (OIDC) configuration for Bitbucket Pipelines within a specified workspace. It returns the well-known OpenID configuration document that contains metadata about the OIDC identity provider used by Pipelines, including supported endpoints, token signing algorithms, claims, and other OAuth 2.0 and OIDC protocol details. This configuration is essential for external services and cloud providers that need to establish trust and validate identity tokens issued by Bitbucket Pipelines when using OIDC authentication for secure, keyless deployments without storing long-lived credentials. operationId: atlassianGetoidcconfiguration 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 responses: '200': description: The OpenID configuration '404': description: The workspace was not found. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: [] - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true /workspaces/{workspace}/pipelines-config/identity/oidc/keys.json: get: tags: - Get - Keys - Openid Connect - Pipelines summary: Atlassian Get Keys For Oidc In Pipelines description: >- This API endpoint retrieves the JSON Web Key Set (JWKS) containing the public keys used for OpenID Connect (OIDC) authentication in Bitbucket Pipelines for a specific workspace. It accepts a GET request to the path /workspaces/{workspace}/pipelines-config/identity/oidc/keys.json, where {workspace} is replaced with the workspace ID or slug. The endpoint returns a keys.json file that contains cryptographic keys used to verify JWT tokens issued by Bitbucket Pipelines' OIDC provider, enabling secure identity federation between Pipelines and external services that support OIDC authentication. operationId: atlassianGetoidckeys 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 responses: '200': description: The keys in JSON web key format '404': description: The workspace was not found. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: [] - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true /workspaces/{workspace}/pipelines-config/variables: get: tags: - Lists - Variables - Workspaces summary: Atlassian List Variables For A Workspace description: >- This API operation retrieves all pipeline variables configured at the workspace level in Bitbucket. By making a GET request to the specified endpoint with a workspace identifier, developers can access a list of environment variables that are available to all pipelines within that workspace, including both secured and non-secured variables along with their keys, values (for non-secured variables), and associated metadata. This is useful for managing and auditing centralized configuration settings that apply across multiple repositories within a workspace, enabling administrators to review what variables are defined and available for pipeline executions without needing to check individual repository settings. operationId: atlassianGetpipelinevariablesforworkspace 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 responses: '200': description: The found workspace level variables. content: application/json: schema: $ref: '#/components/schemas/paginated_pipeline_variables' examples: paginated-pipeline-variables: $ref: '#/components/examples/paginated-pipeline-variables' 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 GenerateExampleFromOperationResponseSchema: true post: tags: - Create - Variables - Workspaces summary: Atlassian Create A Variable For A Workspace description: >- The POST operation on the /workspaces/{workspace}/pipelines-config/variables endpoint allows you to create a new pipeline variable within a specific Bitbucket workspace, enabling you to define configuration values that can be used across multiple pipelines in that workspace. This endpoint requires you to specify the workspace slug in the path parameter and provide the variable details in the request body, typically including the variable's key (name), value, and whether it should be secured/encrypted. Workspace-level pipeline variables are useful for storing shared configuration data, credentials, or environment-specific values that need to be accessible to all repositories within the workspace without having to duplicate the variable definitions in each individual repository. The API returns the created variable object upon successful execution, and requires appropriate authentication and workspace admin permissions to perform this operation. operationId: atlassianCreatepipelinevariableforworkspace 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 requestBody: $ref: '#/components/requestBodies/pipeline_variable2' responses: '201': description: The created variable. headers: Location: description: The URL of the newly created pipeline variable. schema: type: string content: application/json: schema: $ref: '#/components/schemas/pipeline_variable' examples: pipeline-variable: $ref: '#/components/examples/pipeline-variable' '404': description: The workspace does not exist. content: application/json: schema: $ref: '#/components/schemas/error' '409': description: A variable with the provided key already exists. content: application/json: schema: $ref: '#/components/schemas/error' x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:pipeline:bitbucket security: - oauth2: - pipeline:variable - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true /workspaces/{workspace}/pipelines-config/variables/{variable_uuid}: get: tags: - Get - Variables - Workspaces summary: Atlassian Get Variable For A Workspace description: >- This API operation retrieves detailed information about a specific pipeline variable configured for a Bitbucket workspace by providing the workspace identifier and the unique UUID of the variable. It allows developers to programmatically access the configuration details of environment variables, secrets, or other pipeline variables that have been set up at the workspace level, which can be used across multiple repositories within that workspace. The endpoint returns the variable's metadata including its key, value (if not secured), type, and whether it's secured or not, making it useful for auditing pipeline configurations or integrating workspace-level pipeline settings into automated workflows and deployment processes. operationId: atlassianGetpipelinevariableforworkspace 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: variable_uuid description: The UUID of the variable to retrieve. required: true in: path schema: type: string responses: '200': description: The variable. content: application/json: schema: $ref: '#/components/schemas/pipeline_variable' examples: pipeline-variable_2: $ref: '#/components/examples/pipeline-variable_2' '404': description: The workspace or variable with the given UUID was not found. content: application/json: 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 GenerateExampleFromOperationResponseSchema: true put: tags: - Update - Variables - Workspaces summary: Atlassian Update Variable For A Workspace description: >- Updates an existing pipeline variable in a Bitbucket workspace by providing the variable's UUID. This operation allows you to modify the value, security settings, or other properties of a workspace-level pipeline variable that can be used across all repositories within the workspace. The variable UUID must be provided in the path, and the updated variable configuration is sent in the request body. Workspace pipeline variables are commonly used to store shared configuration values, credentials, or environment-specific settings that multiple pipelines need to access, with support for secured variables that hide sensitive information in logs. operationId: atlassianUpdatepipelinevariableforworkspace 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: variable_uuid description: The UUID of the variable. required: true in: path schema: type: string requestBody: $ref: '#/components/requestBodies/pipeline_variable' responses: '200': description: The variable was updated. content: application/json: schema: $ref: '#/components/schemas/pipeline_variable' examples: pipeline-variable_2: $ref: '#/components/examples/pipeline-variable_2' '404': description: The workspace or the variable was not found. content: application/json: schema: $ref: '#/components/schemas/error' x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:pipeline:bitbucket security: - oauth2: - pipeline:variable - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true delete: tags: - Delete - Variables - Workspaces summary: Atlassian Delete A Variable For A Workspace description: >- This API operation allows you to delete a specific pipeline variable from an Atlassian Bitbucket workspace by making a DELETE request to the endpoint with the workspace identifier and the unique UUID of the variable you wish to remove. Pipeline variables are typically used to store configuration values, secrets, or environment-specific settings that are used during the execution of Bitbucket Pipelines, and removing a variable through this endpoint will permanently delete it from the workspace's pipeline configuration, making it unavailable for any future pipeline runs that previously referenced it. operationId: atlassianDeletepipelinevariableforworkspace 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: variable_uuid description: The UUID of the variable to delete. required: true in: path schema: type: string responses: '204': description: The variable was deleted '404': description: The workspace or the variable with the provided UUID does not exist. content: application/json: schema: $ref: '#/components/schemas/error' x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:pipeline:bitbucket security: - oauth2: - pipeline:variable - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true /workspaces/{workspace}/projects: get: tags: - Lists - Projects - Workspaces description: >- This API operation retrieves a paginated list of all projects within a specified Bitbucket workspace, where the workspace is identified by its slug in the URL path. It returns project information including project keys, names, descriptions, and other metadata associated with each project that the authenticated user has permission to view. The response follows Bitbucket's standard pagination format, allowing clients to navigate through large result sets using page parameters, making it useful for applications that need to display or process all projects belonging to a particular workspace. summary: Atlassian List Projects In A Workspace responses: '200': description: The list of projects in this workspace. content: application/json: schema: $ref: '#/components/schemas/paginated_projects' examples: paginated-projects: $ref: '#/components/examples/paginated-projects' '404': description: A workspace doesn't exist at this location. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:project:bitbucket operationId: atlassianListProjectsInAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true post: tags: - Create - Projects - Workspaces description: >- This API operation creates a new project within a specified Bitbucket workspace by sending a POST request to the /workspaces/{workspace}/projects endpoint, where {workspace} is replaced with the unique identifier or slug of the target workspace. The operation allows workspace administrators to programmatically establish new projects that serve as containers for organizing related repositories, enabling better code management and team collaboration. When invoked, the endpoint accepts project details in the request body such as project name, key, description, and access permissions, then returns the newly created project object with its assigned metadata including a unique project identifier, timestamps, and configuration settings. This operation requires appropriate authentication credentials and workspace-level permissions, typically administrator or write access, to successfully create projects within the organizational structure of the Bitbucket workspace. summary: Atlassian Create A Project In A Workspace responses: '201': description: A new project has been created. headers: Location: description: The location of the newly created project schema: type: string content: application/json: schema: $ref: '#/components/schemas/project' examples: project: $ref: '#/components/examples/project' '403': description: The requesting user isn't authorized to create the project. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: A workspace doesn't exist at this location. content: application/json: schema: $ref: '#/components/schemas/error' requestBody: $ref: '#/components/requestBodies/project' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:project:bitbucket operationId: atlassianCreateAProjectInAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - 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 /workspaces/{workspace}/projects/{project_key}: delete: tags: - Delete - Projects - Workspaces description: >- The delete operation on the `/workspaces/{workspace}/projects/{project_key}` endpoint in the Atlassian Bitbucket Workspaces API permanently removes a specified project from a workspace. This operation requires authentication and appropriate permissions to delete projects within the designated workspace. When executed, it takes two path parameters: the workspace identifier and the project key that uniquely identifies the project to be deleted. Upon successful deletion, the project and its associated metadata are removed from the workspace, though this typically does not affect the repositories contained within the project unless specifically configured to do so. This is a destructive operation that cannot be undone, so it should be used with caution in production environments. summary: Atlassian Delete A Project For A Workspace responses: '204': description: Successful deletion. '403': description: >- The requesting user isn't authorized to delete the project or the project isn't empty. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: A project isn't hosted at this location. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:project:bitbucket operationId: atlassianDeleteAProjectForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true get: tags: - Get - Projects - Workspaces description: >- The Get A Project For A Workspace operation in the Atlassian Bitbucket Workspaces API retrieves detailed information about a specific project within a designated workspace by making a GET request to the endpoint /workspaces/{workspace}/projects/{project_key}. This operation requires two path parameters: the workspace identifier (which can be the workspace's UUID, ID, or slug) and the project_key (a unique identifier for the project within that workspace). When successfully invoked, it returns comprehensive project details including the project's name, description, key, creation date, visibility settings, owner information, associated links, and other metadata. This endpoint is commonly used by developers and integrations to fetch project-level configuration data, validate project existence, or retrieve project attributes before performing additional operations within that project's scope. summary: Atlassian Get A Project For A Workspace responses: '200': description: The project that is part of a workspace. content: application/json: schema: $ref: '#/components/schemas/project' examples: project_2: $ref: '#/components/examples/project_2' '401': description: The request wasn't authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: The requesting user isn't authorized to access the project. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: A project isn't hosted at this location. content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:project:bitbucket operationId: atlassianGetAProjectForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true put: tags: - Projects - Update - Workspaces description: >- This API operation allows you to update an existing project within a specified Bitbucket workspace by making a PUT request to the endpoint with the workspace slug and project key as path parameters. You can modify various project properties such as the project name, description, avatar, and other configurable settings. The request requires appropriate authentication and permissions to modify projects within the workspace, typically requiring admin or write access. Upon successful execution, the API returns the updated project object with all its current properties, reflecting the changes made in the request body. This operation follows RESTful conventions where PUT is used to update the complete resource, and any fields not included in the request may be reset to default values depending on the API's implementation. summary: Atlassian Update A Project For A Workspace responses: '200': description: The existing project is has been updated. headers: Location: description: |- The location of the project. This header is only provided when the project key is updated. schema: type: string content: application/json: schema: $ref: '#/components/schemas/project' examples: project_2: $ref: '#/components/examples/project_2' '201': description: A new project has been created. headers: Location: description: The location of the newly created project schema: type: string content: application/json: schema: $ref: '#/components/schemas/project' examples: project_2: $ref: '#/components/examples/project_2' '403': description: >- The requesting user isn't authorized to update or create the project. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- A workspace doesn't exist at the location. Note that the project's absence from this location doesn't raise a 404, since a PUT at a non-existent location can be used to create a new project. content: application/json: schema: $ref: '#/components/schemas/error' requestBody: $ref: '#/components/requestBodies/project' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:project:bitbucket operationId: atlassianUpdateAProjectForAWorkspace x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: | The project in question. This is the actual `key` assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/branching-model: get: tags: - Branching - Get - Models - Projects description: >- This API operation retrieves the branching model configuration for a specific project within a Bitbucket workspace, allowing you to understand how branches are organized and managed within that project. By providing the workspace identifier and project key as path parameters, the GET request returns details about the project's branching strategy, which may include information about development branches, production branches, branch prefixes, and the overall workflow structure that defines how code changes flow from development to production. This is particularly useful for teams that want to programmatically access or audit their project's Git workflow configuration, integrate branching model information into CI/CD pipelines, or build custom tooling that needs to understand the project's branch organization scheme. summary: Atlassian Get The Branching Model For A Project responses: '200': description: The branching model object content: application/json: schema: $ref: '#/components/schemas/project_branching_model' examples: project-branching-model: $ref: '#/components/examples/project-branching-model' '401': description: If the request was not authenticated content: application/json: schema: $ref: '#/components/schemas/error' '403': description: If the authenticated user does not have read access to the project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the project does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:repository:bitbucket operationId: atlassianGetTheBranchingModelForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: | The project in question. This is the actual `key` assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/branching-model/settings: get: tags: - Branching - Get - Models - Projects description: >- This API endpoint retrieves the branching model configuration settings for a specific project within a designated workspace in Atlassian Bitbucket. By making a GET request to this endpoint with the appropriate workspace identifier and project key, users can access the project's branching strategy configuration, which typically includes details about branch types, naming conventions, and workflow patterns such as Git Flow or similar branching models. This information helps teams understand and maintain consistent branching practices across their repositories within the project, ensuring standardized development workflows and version control strategies. summary: Atlassian Get The Branching Model Config For A Project responses: '200': description: The branching model configuration content: application/json: schema: $ref: '#/components/schemas/branching_model_settings' examples: branching-model-settings: $ref: '#/components/examples/branching-model-settings' '401': description: If the request was not authenticated content: application/json: schema: $ref: '#/components/schemas/error' '403': description: If the authenticated user does not have admin access to the project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the project does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:project:bitbucket operationId: atlassianGetTheBranchingModelConfigForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true put: tags: - Branching - Models - Projects - Update description: >- This API operation updates the branching model configuration settings for a specific project within a Bitbucket workspace. It uses a PUT request to the endpoint /workspaces/{workspace}/projects/{project_key}/branching-model/settings, where you specify the workspace slug and project key as path parameters. The branching model defines the workflow for how branches are organized and managed in a project, including settings for development branches, production branches, and branch prefixes for features, releases, hotfixes, and bugfixes. By calling this endpoint, administrators can modify these configuration rules to align with their team's Git workflow strategy, such as Git Flow or a custom branching strategy, ensuring consistent branch naming conventions and automated branch type recognition across the project. summary: Atlassian Update The Branching Model Config For A Project responses: '200': description: The updated branching model configuration content: application/json: schema: $ref: '#/components/schemas/branching_model_settings' examples: branching-model-settings_2: $ref: '#/components/examples/branching-model-settings_2' '400': description: If the request contains an invalid branching model configuration content: application/json: schema: $ref: '#/components/schemas/error' '401': description: If the request was not authenticated content: application/json: schema: $ref: '#/components/schemas/error' '403': description: If the authenticated user does not have admin access to the project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the project does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:project:bitbucket operationId: atlassianUpdateTheBranchingModelConfigForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: | The project in question. This is the actual `key` assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/default-reviewers: get: tags: - Lists - Projects - Reviewers description: >- This API endpoint retrieves the list of default reviewers configured for a specific project within a Bitbucket workspace. When accessed via a GET request to `/workspaces/{workspace}/projects/{project_key}/default-reviewers`, it returns information about users who are automatically added as reviewers to new pull requests in the specified project. The endpoint requires both the workspace slug and project key as path parameters to identify the target project. Default reviewers help streamline the code review process by ensuring that designated team members are automatically notified and assigned to review pull requests, maintaining consistency in code quality oversight across the project. summary: Atlassian List The Default Reviewers In A Project responses: '200': description: The list of project default reviewers content: application/json: schema: $ref: '#/components/schemas/paginated_default_reviewer_and_type' examples: paginated-default-reviewer-and-type: $ref: '#/components/examples/paginated-default-reviewer-and-type' '403': description: If the authenticated user does not have admin access to the project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the workspace or project does not exist at this location content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:pullrequest:bitbucket operationId: atlassianListTheDefaultReviewersInAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: | The project in question. This is the actual `key` assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/default-reviewers/{selected_user}: delete: tags: - Projects - Remove - Reviewers - Specific - Users description: >- This API operation removes a specific user from the default reviewers list for a given project within a Bitbucket workspace. When invoked, it performs a DELETE request to the endpoint /workspaces/{workspace}/projects/{project_key}/default-reviewers/{selected_user}, where the workspace parameter identifies the workspace containing the project, project_key specifies the particular project, and selected_user indicates the user to be removed from the default reviewers. Once executed, the specified user will no longer be automatically added as a reviewer for new pull requests created in that project, though existing pull request assignments remain unaffected. This operation requires appropriate administrative permissions for the project and helps teams manage their code review workflows by controlling who is automatically involved in the review process. summary: Atlassian Remove The Specific User From The Project S Default Reviewers responses: '204': description: >- The specified user was removed from the list of project default reviewers '400': description: If the specified user is not a default reviewer for the project content: application/json: schema: $ref: '#/components/schemas/error' '403': description: If the authenticated user does not have admin access to the project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified user, project, or workspace does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:project:bitbucket operationId: atlassianRemoveTheSpecificUserFromTheProjectSDefaultReviewers x-api-evangelist-processing: WriteDescription: true ChooseTags: true get: tags: - Get description: >- This GET operation retrieves information about a specific default reviewer for a project within a Bitbucket workspace. By providing the workspace identifier, project key, and the selected user's identifier in the endpoint path, the API returns details about that user's default reviewer configuration for the specified project. Default reviewers are automatically added to pull requests created within the project, streamlining the code review process by ensuring appropriate team members are notified of new changes. This endpoint is useful for auditing reviewer assignments, verifying default reviewer settings, or building administrative interfaces that manage project-level review workflows in Bitbucket. summary: Atlassian Get A Default Reviewer responses: '200': description: The specified user that is a default reviewer content: application/json: schema: $ref: '#/components/schemas/user' examples: user: $ref: '#/components/examples/user' '400': description: If the specified user is not a default reviewer for the project content: application/json: schema: $ref: '#/components/schemas/error' '403': description: If the authenticated user does not have admin access to the project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified user, project, or workspace does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:pullrequest:bitbucket operationId: atlassianGetADefaultReviewer x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true put: tags: - Add - Projects - Specific - Users description: >- This PUT operation adds a specified user as a default reviewer for a particular project within a Bitbucket workspace. By targeting the endpoint with the workspace slug, project key, and the selected user's identifier, it configures that user to be automatically added as a reviewer on all new pull requests created in the project. This helps streamline the code review process by ensuring designated team members are consistently included in pull request reviews without manual assignment, making it useful for maintaining quality control and ensuring appropriate oversight across a project's development workflow. summary: Atlassian Add The Specific User As A Default Reviewer For The Project responses: '200': description: The specified user was added as a project default reviewer content: application/json: schema: $ref: '#/components/schemas/user' examples: user_2: $ref: '#/components/examples/user_2' '400': description: >- If the specified user cannot be added as a default reviewer for the project content: application/json: schema: $ref: '#/components/schemas/error' '403': description: If the authenticated user does not have admin access to the project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified user, project, or workspace does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - admin:project:bitbucket operationId: atlassianAddTheSpecificUserAsADefaultReviewerForTheProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: | The project in question. This can either be the actual `key` assigned to the project or the `UUID` (surrounded by curly-braces (`{}`)). required: true schema: type: string - name: selected_user in: path description: | This can either be the username or the UUID of the default reviewer, surrounded by curly-braces, for example: `{account 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 /workspaces/{workspace}/projects/{project_key}/deploy-keys: get: tags: - Deploy - Keys - Lists - Projects description: >- This GET operation retrieves a paginated list of all deploy keys configured for a specific project within a Bitbucket workspace. Deploy keys are SSH keys that grant read-only or read-write access to project repositories, commonly used for automated deployments and CI/CD pipelines. The endpoint requires both the workspace slug and project key as path parameters to identify the target project, and returns an array of deploy key objects containing details such as the key ID, label, public key value, creation date, and associated permissions. This allows administrators and developers to audit which deploy keys have access to their project's repositories and manage authentication credentials programmatically. summary: Atlassian List Project Deploy Keys responses: '200': description: Deploy keys matching the project content: application/json: schema: $ref: '#/components/schemas/paginated_project_deploy_keys' examples: paginated-project-deploy-keys: $ref: '#/components/examples/paginated-project-deploy-keys' '403': description: >- If the specified workspace or project is not accessible to the current user content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified workspace or project does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project - project:admin - basic: [] - api_key: [] operationId: atlassianListProjectDeployKeys x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true post: tags: - Create - Deploy - Keys - Projects description: >- This API operation creates a new deploy key for a specific project within a Bitbucket workspace, allowing secure, read-only SSH access to repositories within that project. By making a POST request to the endpoint with the workspace slug and project key as path parameters, users can generate an SSH key that can be used for automated deployments or CI/CD pipelines without requiring personal credentials. The deploy key is scoped to the project level, meaning it can access all repositories within the specified project, and the request body typically includes the SSH public key content and an optional label for identification purposes. This is particularly useful for granting automated systems or external services controlled access to project repositories for deployment purposes while maintaining security best practices by avoiding the use of user account credentials. summary: Atlassian Create A Project Deploy Key responses: '200': description: The project deploy key that was created content: application/json: schema: $ref: '#/components/schemas/project_deploy_key' examples: project-deploy-key: $ref: '#/components/examples/project-deploy-key' '400': description: Invalid deploy key inputs content: application/json: schema: $ref: '#/components/schemas/error' '403': description: >- If the specified workspace or project is not accessible to the current user content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified workspace or project does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project - project:admin - basic: [] - api_key: [] operationId: atlassianCreateAProjectDeployKey x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: | The project in question. This is the actual `key` assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/deploy-keys/{key_id}: delete: tags: - Deployments description: >- This API operation removes a specific deploy key from a project within a Bitbucket workspace by sending a DELETE request to the endpoint with the workspace identifier, project key, and deploy key ID as path parameters. Deploy keys are SSH keys that provide read-only or read-write access to repositories, and deleting one revokes that key's access to all repositories within the specified project. This is typically used when rotating keys for security purposes, removing access for discontinued services or team members, or cleaning up unused authentication credentials. The operation requires appropriate administrative permissions on the project and will permanently remove the deploy key association, though it won't affect deploy keys in other projects that may use the same SSH key. summary: Atlassian Delete A Deploy Key From A Project responses: '204': description: The project deploy key has been deleted '403': description: >- If the current user does not have permission to delete a key for the specified project content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- If the specified workspace, project, or project deploy key does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project - project:admin - basic: [] - api_key: [] operationId: atlassianDeleteADeployKeyFromAProject x-api-evangelist-processing: WriteDescription: true get: tags: - Deploy - Get - Keys - Projects description: >- This API operation retrieves detailed information about a specific deploy key that has been added to a project within a Bitbucket workspace. By providing the workspace identifier, project key, and the unique key ID, you can fetch the deploy key's properties including its public SSH key content, label, creation date, and associated permissions. Deploy keys are SSH keys that grant read-only or read-write access to repositories within a project, commonly used for automated deployments and CI/CD pipelines to securely access repository code without requiring user credentials. summary: Atlassian Get A Project Deploy Key responses: '200': description: Project deploy key matching the key ID content: application/json: schema: $ref: '#/components/schemas/project_deploy_key' examples: project-deploy-key_2: $ref: '#/components/examples/project-deploy-key_2' '403': description: >- If the specified workspace or project is not accessible to the current user content: application/json: schema: $ref: '#/components/schemas/error' '404': description: If the specified workspace or project does not exist content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project - project:admin - basic: [] - api_key: [] operationId: atlassianGetAProjectDeployKey x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: key_id in: path description: The key ID matching the project deploy key. required: true schema: type: string - name: project_key in: path description: | The project in question. This is the actual `key` assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/permissions-config/groups: get: tags: - Explicit - Groups - Lists - Permissions - Projects description: >- This API endpoint retrieves a paginated list of explicit group permissions that have been directly granted to groups for a specific project within a Bitbucket workspace. By making a GET request to this endpoint with the workspace identifier and project key as path parameters, you can view all groups that have been explicitly assigned permissions to the project, along with their corresponding permission levels. This is useful for auditing access control, understanding who has what level of access to a project, and managing team permissions. The response excludes inherited permissions and only shows permissions that have been directly configured at the project level for groups, making it easier to track and manage explicit access grants without the noise of inherited permissions from workspace-level settings. summary: Atlassian List Explicit Group Permissions For A Project responses: '200': description: Paginated list of project group permissions content: application/json: schema: $ref: '#/components/schemas/paginated_project_group_permissions' examples: paginated-project-group-permissions: $ref: '#/components/examples/paginated-project-group-permissions' '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: The user doesn't have admin access to the project. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or both of the workspace and project don't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:project:bitbucket - read:user:bitbucket operationId: atlassianListExplicitGroupPermissionsForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: > The project in question. This is the actual key assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/permissions-config/groups/{group_slug}: delete: tags: - Delete - Explicit - Groups - Permissions - Projects description: >- This API operation removes an explicitly granted group permission from a specific project within a Bitbucket workspace by sending a DELETE request to the designated endpoint, which requires the workspace identifier, project key, and group slug as path parameters to target the exact permission configuration that needs to be revoked, effectively revoking that group's direct access rights to the project while potentially leaving inherited or other permission types intact, allowing workspace administrators to maintain granular control over project-level access by selectively removing group permissions without affecting individual user permissions or other security settings associated with the project. summary: Atlassian Delete An Explicit Group Permission For A Project responses: '204': description: The project group permission was deleted and no content returned. '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: >- The requesting user isn't an admin of the project, or the authentication method was not via app password. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or more of the workspace, project, and group doesn't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] operationId: atlassianDeleteAnExplicitGroupPermissionForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true get: tags: - Explicit - Get - Groups - Permissions - Projects description: >- This API operation retrieves the explicit permission settings assigned to a specific group for a particular project within a Bitbucket workspace. By providing the workspace identifier, project key, and group slug as path parameters, the endpoint returns detailed information about what access level and permissions have been directly granted to that group for the specified project. This is useful for auditing group-level permissions, understanding access control configurations, and managing team-based security policies within Bitbucket projects, as it shows only the permissions explicitly set for the group rather than inherited or default permissions. summary: Atlassian Get An Explicit Group Permission For A Project responses: '200': description: Project group permission content: application/json: schema: $ref: '#/components/schemas/project_group_permission' examples: project-group-permission: $ref: '#/components/examples/project-group-permission' '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: The user doesn't have admin access to the project. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or more of the workspace, project, and group doesn't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:project:bitbucket - read:user:bitbucket operationId: atlassianGetAnExplicitGroupPermissionForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true put: tags: - Explicit - Groups - Permissions - Projects - Update description: >- This API operation updates the explicit permissions assigned to a specific group within a Bitbucket project. By making a PUT request to the endpoint with the workspace identifier, project key, and group slug, administrators can modify the access level granted to that group for the specified project. This allows for fine-grained control over project permissions by adjusting what actions members of a particular group can perform, such as read, write, or admin privileges. The operation requires proper authentication and administrative rights within the workspace, and it directly modifies the existing permission configuration rather than creating a new one, making it useful for maintaining and adjusting team access controls as project requirements evolve. summary: Atlassian Update An Explicit Group Permission For A Project responses: '200': description: Project group permission updated. content: application/json: schema: $ref: '#/components/schemas/project_group_permission' examples: project-group-permission_2: $ref: '#/components/examples/project-group-permission_2' '400': description: >- No permission value was provided or the value is invalid(not one of read, write, create-repo, or admin). content: application/json: schema: $ref: '#/components/schemas/error' '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '402': description: >- You have reached your plan's user limit and must upgrade before giving access to additional users. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: >- The requesting user isn't an admin of the project, or the authentication method was not via app password. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or more of the workspace, project, and group doesn't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' requestBody: $ref: >- #/components/requestBodies/bitbucket.apps.permissions.serializers.ProjectPermissionUpdateSchema security: - oauth2: - project:admin - basic: [] - api_key: [] operationId: atlassianUpdateAnExplicitGroupPermissionForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: group_slug in: path description: Slug of the requested group. required: true schema: type: string - name: project_key in: path description: > The project in question. This is the actual key assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/permissions-config/users: get: tags: - Explicit - Lists - Permissions - Projects - Users description: >- This API operation retrieves a list of all users who have been explicitly granted permissions for a specific project within a Bitbucket workspace. By providing the workspace identifier and project key as path parameters, the endpoint returns detailed information about individual user permissions that have been directly assigned at the project level, excluding any permissions inherited from group memberships or workspace-level settings. This is useful for administrators who need to audit project access, review security configurations, or understand the granular permission structure for specific users within a particular project in their Bitbucket Cloud instance. summary: Atlassian List Explicit User Permissions For A Project responses: '200': description: Paginated list of explicit user permissions. content: application/json: schema: $ref: '#/components/schemas/paginated_project_user_permissions' examples: paginated-project-user-permissions: $ref: '#/components/examples/paginated-project-user-permissions' '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: The user doesn't have admin access to the project. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or both of the workspace and project don't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:project:bitbucket - read:user:bitbucket operationId: atlassianListExplicitUserPermissionsForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: > The project in question. This is the actual key assigned to the project. 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 /workspaces/{workspace}/projects/{project_key}/permissions-config/users/{selected_user_id}: delete: tags: - Delete - Explicit - Permissions - Projects - Users description: >- This API operation removes an explicitly granted permission for a specific user from a Bitbucket project within a workspace. By making a DELETE request to the endpoint with the workspace identifier, project key, and the target user's ID, administrators can revoke direct access permissions that were previously assigned to that user for the specified project. This is useful for managing user access control when team members change roles, leave projects, or when permissions need to be adjusted as part of security or organizational restructuring, ensuring that only authorized users maintain access to project resources. summary: Atlassian Delete An Explicit User Permission For A Project responses: '204': description: The project user permission was deleted and no content returned. '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: >- The requesting user isn't an admin of the project, or the authentication method was not via app password. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] operationId: atlassianDeleteAnExplicitUserPermissionForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true get: tags: - Explicit - Get - Permissions - Projects - Users description: >- This API operation retrieves the explicit permission settings for a specific user within a designated project in a Bitbucket workspace. By providing the workspace identifier, project key, and selected user ID in the endpoint path, you can query the exact permission level that has been directly assigned to that particular user for the project, excluding any inherited permissions from groups or workspace-level settings. The response returns details about the user's explicit project access rights, which may include permissions such as read, write, or admin capabilities that have been individually granted to them for that specific project context. summary: Atlassian Get An Explicit User Permission For A Project responses: '200': description: Explicit user permission for user and project content: application/json: schema: $ref: '#/components/schemas/project_user_permission' examples: project-user-permission: $ref: '#/components/examples/project-user-permission' '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: The requesting user isn't an admin of the project. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' security: - oauth2: - project:admin - basic: [] - api_key: [] x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:project:bitbucket - read:user:bitbucket operationId: atlassianGetAnExplicitUserPermissionForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true put: tags: - Explicit - Permissions - Projects - Update - Users description: >- This API operation updates an explicit user permission for a specific project within a Bitbucket workspace by sending a PUT request to the endpoint with the workspace slug, project key, and selected user ID as path parameters. It allows administrators to modify the access level granted to an individual user for a particular project, such as changing their role from read-only to write access or adjusting other permission settings. The operation replaces the existing permission configuration for the specified user on that project with the new values provided in the request body, enabling granular control over project-level access rights for team members within the workspace. summary: Atlassian Update An Explicit User Permission For A Project responses: '200': description: Explicit user permission updated content: application/json: schema: $ref: '#/components/schemas/project_user_permission' examples: project-user-permission_2: $ref: '#/components/examples/project-user-permission_2' '400': description: >- No permission value was provided or the value is invalid (not one of read, write, create-repo, or admin) content: application/json: schema: $ref: '#/components/schemas/error' '401': description: The user couldn't be authenticated. content: application/json: schema: $ref: '#/components/schemas/error' '402': description: >- You have reached your plan's user limit and must upgrade before giving access to additional users. content: application/json: schema: $ref: '#/components/schemas/error' '403': description: >- The requesting user isn't an admin of the project, or the authentication method was not via app password. content: application/json: schema: $ref: '#/components/schemas/error' '404': description: >- One or more of the workspace, project, and selected user doesn't exist for the given identifiers or the requesting user is not authenticated content: application/json: schema: $ref: '#/components/schemas/error' requestBody: $ref: >- #/components/requestBodies/bitbucket.apps.permissions.serializers.ProjectPermissionUpdateSchema security: - oauth2: - project:admin - basic: [] - api_key: [] operationId: atlassianUpdateAnExplicitUserPermissionForAProject x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true parameters: - name: project_key in: path description: > The project in question. This is the actual key assigned to the project. required: true schema: type: string - name: selected_user_id in: path description: > This can either be the username, the user's UUID surrounded by curly-braces, for example: {account UUID}, or the user's Atlassian ID. 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 /workspaces/{workspace}/search/code: get: tags: - Code - Search - Workspaces summary: Atlassian Search For Code In A Workspace description: >- This GET endpoint allows you to search for code across repositories within a specified Atlassian Bitbucket workspace. By providing the workspace identifier in the path parameter, you can perform code searches using query parameters to find specific strings, patterns, or code snippets across all accessible repositories in that workspace. The operation returns matching results that include file paths, repository information, and code context where the search terms appear, making it useful for developers who need to locate specific code implementations, function definitions, or configuration settings across multiple repositories within their workspace. operationId: atlassianSearchworkspace 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' examples: undefined_2: $ref: '#/components/examples/undefined_2' '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' x-atlassian-oauth2-scopes: - state: Current scheme: oauth2 scopes: - read:repository:bitbucket security: - oauth2: - repository - basic: [] - api_key: [] x-api-evangelist-processing: WriteDescription: true ChooseTags: true GenerateExampleFromOperationResponseSchema: true tags: - name: Add - name: All - name: Branching - name: Code - name: Configuration - name: Create - name: Delete - name: Deploy - name: Deployments - name: Explicit - name: Get - name: Groups - name: Keys - name: Lists - name: Memberships - name: Models - name: Openid Connect - name: Permissions - name: Pipelines - name: Projects - name: Remove - name: Repositories - name: Reviewers - name: Search - name: Specific - name: Update - name: Users - name: Variables - name: Webhooks - name: Workspaces x-revision: 3c039d08312e x-atlassian-narrative: documents: - anchor: authentication title: Authentication methods description: How to authenticate API actions icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxOTcuNjQ3MyAxODYuODEzOCI+CiAgPGRlZnM+CiAgICA8c3R5bGU+CiAgICAgIC5jbHMtMSB7CiAgICAgICAgaXNvbGF0aW9uOiBpc29sYXRlOwogICAgICB9CgogICAgICAuY2xzLTIgewogICAgICAgIGZpbGw6ICNkZTM1MGI7CiAgICAgIH0KCiAgICAgIC5jbHMtMyB7CiAgICAgICAgZmlsbDogI2ZmNTYzMDsKICAgICAgfQoKICAgICAgLmNscy00IHsKICAgICAgICBmaWxsOiAjZGZlMWU1OwogICAgICAgIG1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsKICAgICAgfQoKICAgICAgLmNscy01IHsKICAgICAgICBmaWxsOiAjZmFmYmZjOwogICAgICB9CgogICAgICAuY2xzLTYgewogICAgICAgIGZpbGw6ICNlYmVjZjA7CiAgICAgIH0KCiAgICAgIC5jbHMtNyB7CiAgICAgICAgZmlsbDogbm9uZTsKICAgICAgICBzdHJva2U6ICMwMDY1ZmY7CiAgICAgICAgc3Ryb2tlLW1pdGVybGltaXQ6IDEwOwogICAgICAgIHN0cm9rZS13aWR0aDogMnB4OwogICAgICB9CgogICAgICAuY2xzLTggewogICAgICAgIGZpbGw6ICM1ZTZjODQ7CiAgICAgIH0KCiAgICAgIC5jbHMtOSB7CiAgICAgICAgZmlsbDogIzI1Mzg1ODsKICAgICAgfQoKICAgICAgLmNscy0xMCB7CiAgICAgICAgZmlsbDogIzI2ODRmZjsKICAgICAgfQoKICAgICAgLmNscy0xMSB7CiAgICAgICAgZmlsbDogIzAwNjVmZjsKICAgICAgfQogICAgPC9zdHlsZT4KICA8L2RlZnM+CiAgPHRpdGxlPlNlY3VyaXR5IHdpdGggS2V5PC90aXRsZT4KICA8ZyBjbGFzcz0iY2xzLTEiPgogICAgPGcgaWQ9IkxheWVyXzIiIGRhdGEtbmFtZT0iTGF5ZXIgMiI+CiAgICAgIDxnIGlkPSJPYmplY3RzIj4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik00Mi4wNjcyLDBoLjYxMTRhOCw4LDAsMCwxLDgsOFYyMy4yMzM4YTAsMCwwLDAsMSwwLDBIMzQuMDY3MmEwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDQyLjA2NzIsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xMDguMjIsMGguNjExNGE4LDgsMCwwLDEsOCw4VjIzLjIzMzhhMCwwLDAsMCwxLDAsMEgxMDAuMjJhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSwxMDguMjIsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xNzQuMzcyMiwwaC42MTE0YTgsOCwwLDAsMSw4LDhWMjMuMjMzOGEwLDAsMCwwLDEsMCwwSDE2Ni4zNzIyYTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMTc0LjM3MjIsMFoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjM0LjA2NzIiIHk9IjIzLjIzMzgiIHdpZHRoPSIxNjMuNTgiIGhlaWdodD0iMTYzLjU4Ii8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNNDIuMDY3MiwwSDU5LjI5YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDM0LjA2NzJhMCwwLDAsMCwxLDAsMFY4YTgsOCwwLDAsMSw4LThaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTA3LjI0NTgsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDk5LjI0NThhMCwwLDAsMCwxLDAsMFY4YTgsOCwwLDAsMSw4LThaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTcyLjQyNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDE2NC40MjQ0YTAsMCwwLDAsMSwwLDBWOGE4LDgsMCwwLDEsOC04WiIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMyIgeD0iMTcuNDU1OCIgeT0iMjMuMjMzOCIgd2lkdGg9IjE2My41OCIgaGVpZ2h0PSIxNjMuNTgiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTMiIGQ9Ik0yNS40NTU4LDBINDIuNjc4NmE4LDgsMCwwLDEsOCw4VjIzLjIyMjhhMCwwLDAsMCwxLDAsMEgxNy40NTU4YTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMjUuNDU1OCwwWiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMyIgZD0iTTkwLjYzNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDgyLjYzNDRhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSw5MC42MzQ0LDBaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTU1LjgxMywwaDE3LjIyMjhhOCw4LDAsMCwxLDgsOFYyMy4yMjI4YTAsMCwwLDAsMSwwLDBIMTQ3LjgxM2EwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDE1NS44MTMsMFoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTMiIGQ9Ik0yNS40NTU4LDBINDIuNjc4NmE4LDgsMCwwLDEsOCw4VjIzLjIyMjhhMCwwLDAsMCwxLDAsMEgxNy40NTU4YTAsMCwwLDAsMSwwLDBWOEE4LDgsMCwwLDEsMjUuNDU1OCwwWiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMyIgZD0iTTkwLjYzNDQsMGgxNy4yMjI4YTgsOCwwLDAsMSw4LDhWMjMuMjIyOGEwLDAsMCwwLDEsMCwwSDgyLjYzNDRhMCwwLDAsMCwxLDAsMFY4QTgsOCwwLDAsMSw5MC42MzQ0LDBaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTU1LjgxMywwaDE3LjIyMjhhOCw4LDAsMCwxLDgsOFYyMy4yMjI4YTAsMCwwLDAsMSwwLDBIMTQ3LjgxM2EwLDAsMCwwLDEsMCwwVjhBOCw4LDAsMCwxLDE1NS44MTMsMFoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjM1Ljc1OTYiIHk9IjU2LjgwNjUiIHdpZHRoPSIzMy4yMjI4IiBoZWlnaHQ9IjE1LjYwMzgiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTIiIHg9IjEzMS4yMDE2IiB5PSIxMzYuOTYxNSIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNCIgZD0iTTU3LjM3MDksNzEuNjAzNmg3MC43NWE5LDksMCwwLDEsOSw5djM1LjM3NDlhNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLTQ0LjM3NDgsNDQuMzc0OGgwYTQ0LjM3NDgsNDQuMzc0OCwwLDAsMS00NC4zNzQ4LTQ0LjM3NDhWODAuNjAzNkE5LDksMCwwLDEsNTcuMzcwOSw3MS42MDM2WiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNSIgZD0iTTY2LjM3MSw2Ni42NjE3aDcwLjc1YTksOSwwLDAsMSw5LDl2MzUuMzc0OWE0NC4zNzQ4LDQ0LjM3NDgsMCwwLDEtNDQuMzc0OCw0NC4zNzQ4aDBBNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLDU3LjM3MSwxMTEuMDM2NlY3NS42NjE3YTksOSwwLDAsMSw5LTlaIi8+CiAgICAgICAgPHBhdGggaWQ9Il9SZWN0YW5nbGVfIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTYiIGQ9Ik02MS4zNzEsNjYuNjYxN2g3MC43NWE5LDksMCwwLDEsOSw5djM1LjM3NDlhNDQuMzc0OCw0NC4zNzQ4LDAsMCwxLTQ0LjM3NDgsNDQuMzc0OGgwQTQ0LjM3NDgsNDQuMzc0OCwwLDAsMSw1Mi4zNzEsMTExLjAzNjZWNzUuNjYxN0E5LDksMCwwLDEsNjEuMzcxLDY2LjY2MTdaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy03IiBkPSJNOTYuNzQ1OSwxNDcuNzQ0MWEzNi43NDg3LDM2Ljc0ODcsMCwwLDEtMzYuNzA3NC0zNi43MDc0Vjc4LjA1ODRhMy43MzMzLDMuNzMzMywwLDAsMSwzLjcyOS0zLjcyOWg2NS45NTYzYTMuNzMzMywzLjczMzMsMCwwLDEsMy43MjksMy43Mjl2MzIuOTc4NEEzNi43NDg2LDM2Ljc0ODYsMCwwLDEsOTYuNzQ1OSwxNDcuNzQ0MVoiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTQiIGQ9Ik0xMDAuNjg5MywxNjMuMzE2N1YxMTEuMDk3M2EzLjk0NDMsMy45NDQzLDAsMCwwLTcuODg4NywwdjUyLjIyYTIyLjUyNTIsMjIuNTI1MiwwLDAsMC0xOC41NDc5LDIyLjE0YzAsLjQ1Ni4wMTc4LjkwNzguMDQ0NywxLjM1NzFIODIuMjFjLS4wNDE0LS40NDc0LS4wNjg4LS44OTktLjA2ODgtMS4zNTcxYTE0LjYyLDE0LjYyLDAsMCwxLDE0LjU5NzQtMTQuNjA0MWwuMDA2MS4wMDA2LjAwNjgtLjAwMDdBMTQuNjIxMSwxNC42MjExLDAsMCwxLDExMS4zNSwxODUuNDU2NmMwLC40NTgxLS4wMjczLjkxLS4wNjg4LDEuMzU3MWg3LjkxMjhjLjAyNjktLjQ0OTMuMDQ0Ny0uOTAxMS4wNDQ3LTEuMzU3MUEyMi41MjU5LDIyLjUyNTksMCwwLDAsMTAwLjY4OTMsMTYzLjMxNjdaIi8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxNy40NTU4IiB5PSIzNi40NzAyIiB3aWR0aD0iMzMuMjIyOCIgaGVpZ2h0PSIxNS42MDM4Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxNy40NTU4IiB5PSIxNTguMTIxNyIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMiIgeD0iMTQ3LjgxMyIgeT0iMzYuNDcwMiIgd2lkdGg9IjMzLjIyMjgiIGhlaWdodD0iMTUuNjAzOCIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMiIgeD0iMTUwLjA2NDMiIHk9IjE1Ny41NTEzIiB3aWR0aD0iMzMuMjIyOCIgaGVpZ2h0PSIxNS42MDM4Ii8+CiAgICAgICAgPHBhdGggaWQ9Il9QYXRoXyIgZGF0YS1uYW1lPSImbHQ7UGF0aCZndDsiIGNsYXNzPSJjbHMtOCIgZD0iTTEwNy41MjU0LDEwMS4wMDI3YTExLjc3OTQsMTEuNzc5NCwwLDEsMC0xOS44Niw4LjU1NDhBNC4wNDE3LDQuMDQxNywwLDAsMSw4OC44NSwxMTMuNjJsLTIuMTA0LDcuMjY4MWEzLDMsMCwwLDAsMi44ODE3LDMuODM0MmgxMi4yMzcxYTMsMywwLDAsMCwyLjg4MTctMy44MzQybC0yLjA5NTktNy4yNGE0LjA3NDMsNC4wNzQzLDAsMCwxLDEuMTgwOC00LjA5NDVBMTEuNzE3MiwxMS43MTcyLDAsMCwwLDEwNy41MjU0LDEwMS4wMDI3WiIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtOSIgZD0iTTEwNC43NDYxLDEyMC44ODc3bC0yLjA5NTktNy4yNGE0LjA3NDQsNC4wNzQ0LDAsMCwxLDEuMTgwOC00LjA5NDUsMTEuNzYyOSwxMS43NjI5LDAsMCwwLTUuMDYtMTkuOTMxMywxMS45MSwxMS45MSwwLDAsMC04Ljc5OCwxMC45OTQ5LDExLjcxODUsMTEuNzE4NSwwLDAsMCwzLjY5MjksOC45NDFBNC4wNDE2LDQuMDQxNiwwLDAsMSw5NC44NSwxMTMuNjJsLTMuMjE0LDExLjEwMjNoMTAuMjI4OEEzLDMsMCwwLDAsMTA0Ljc0NjEsMTIwLjg4NzdaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTgxLjc5NzUsMTAwLjMxYTMuOTQzOSwzLjk0MzksMCwwLDAtMy45NDQzLTMuOTQ0M0g0MS4wNDE3YTMuOTQ0MywzLjk0NDMsMCwwLDAsMCw3Ljg4ODdINzcuODUzMkEzLjk0MzksMy45NDM5LDAsMCwwLDgxLjc5NzUsMTAwLjMxWiIvPgogICAgICAgIDxwYXRoIGlkPSJfUGF0aF8yIiBkYXRhLW5hbWU9IiZsdDtQYXRoJmd0OyIgY2xhc3M9ImNscy0xMSIgZD0iTTQxLjA0MTYsMTA0LjI1MzlIOTYuODUzMmEzLjk0NDMsMy45NDQzLDAsMCwwLDAtNy44ODg3SDQxLjA0MTZhMy45NDQzLDMuOTQ0MywwLDAsMCwwLDcuODg4N1oiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTEwIiBkPSJNODEuNzk3NSwxMDAuMzFhMy45NDM5LDMuOTQzOSwwLDAsMC0zLjk0NDMtMy45NDQzSDQxLjA0MTdhMy45NDQzLDMuOTQ0MywwLDAsMCwwLDcuODg4N0g3Ny44NTMyQTMuOTQzOSwzLjk0MzksMCwwLDAsODEuNzk3NSwxMDAuMzFaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTIyLjQ5MzIsMTIyLjgwMjlBMjIuNDkyOSwyMi40OTI5LDAsMSwxLDQ0Ljk4NTgsMTAwLjMxLDIyLjUxODUsMjIuNTE4NSwwLDAsMSwyMi40OTMyLDEyMi44MDI5Wm0wLTM3LjA5NzJBMTQuNjA0MiwxNC42MDQyLDAsMSwwLDM3LjA5NzIsMTAwLjMxLDE0LjYyMDcsMTQuNjIwNywwLDAsMCwyMi40OTMyLDg1LjcwNTdaIi8+CiAgICAgIDwvZz4KICAgIDwvZz4KICA8L2c+Cjwvc3ZnPgo=' body: >2 The purpose of this section is to describe how to authenticate when making API calls using the Bitbucket REST API. -- * [Basic auth](#basic-auth) * [Access Tokens](#access-tokens) * [Repository Access Tokens](#repository-access-tokens) * [Project Access Tokens](#project-access-tokens) * [Workspace Access Tokens](#workspace-access-tokens) * [App passwords](#app-passwords) * [OAuth 2.0](#oauth-2-0) * [Making requests](#making-requests) * [Repository cloning](#repository-cloning) * [Refresh tokens](#refresh-tokens) * [Bitbucket OAuth 2.0 Scopes](#bitbucket-oauth-2-0-scopes) * [Forge App Scopes](#forge-app-scopes) ### Basic auth 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](https://bitbucket.org/account/settings/app-passwords/) as credentials. ### Access Tokens Access Tokens are passwords (or tokens) that provide access to a _single_ repository, project or workspace. These tokens can authenticate with Bitbucket APIs for scripting, CI/CD tools, Bitbucket Cloud-connected apps, and Bitbucket Cloud integrations. Access Tokens are linked to a repository, project, or workspace, not a user account. The level of access provided by the token is set when a repository, or workspace admin creates it, by setting permission scopes. There are three types of Access Token: * **Repository Access Tokens** can connect to a single repository, preventing them from accessing any other repositories or workspaces. * **Project Access Tokens** can connect to a single project, providing access to any repositories within the project. * **Workspace Access Tokens** can connect to a single workspace and have access to any projects and repositories within that workspace. When using Bitbucket APIs with an Access Token, the token will be treated as the "user" in the Bitbucket UI and Bitbucket logs. This includes when using the Access Token to leave a comment on a pull request, push a commit, or merge a pull request. The Bitbucket UI and API responses will show the Repository/Project/Workspace Access Token as a user. The username shown in the Bitbucket UI is the Access Token _name_, and a custom icon is used to differentiate it from a regular user in the UI. #### Considerations for using Access Tokens * After creation, an Access Token can't be viewed or modified. The token's name, created date, last accessed date, and scopes are visible on the repository, project, or workspace **Access Tokens** page. * Access Tokens can access a limited set of Bitbucket's permission scopes. * Provided you set the correct permission scopes, you can use an Access Token to clone (`repository`) and push (`repository:write`) code to the token's repository or the repositories the token can access. * You can't use an Access Token to log into the Bitbucket website. * Access Tokens don't require two-step verification. * You can set permission scopes (specific access rights) for each Access Token. * You can't use an Access Token to manipulate or query repository, project, or workspace permissions. * Access Tokens are not listed in any repository or workspace permission API response. * Access Tokens are deactivated when deleting the resource tied to it (a repository, project, or workspace). Repository Access Tokens are also revoked when transferring the repository to another workspace. * Any content created by the Access Token will persist after the Access Token has been revoked. * Access Tokens can interact with branch restriction APIs, but the token can't be configured as a user with merge access when using branch restrictions. There are some APIs which are inaccessible for Access Tokens, these are: * [Add a repository deploy key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-post) * [Update a repository deploy key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-key-id-put) * [Delete a repository deploy key](/cloud/bitbucket/rest/api-group-deployments/#api-repositories-workspace-repo-slug-deploy-keys-key-id-delete) #### Repository Access Tokens For details on creating, managing, and using Repository Access Tokens, visit [Repository Access Tokens](https://support.atlassian.com/bitbucket-cloud/docs/repository-access-tokens/). The available scopes for Repository Access Tokens are: - [`repository`](#repository) - [`repository:write`](#repository-write) - [`repository:admin`](#repository-admin) - [`repository:delete`](#repository-delete) - [`pullrequest`](#pullrequest) - [`pullrequest:write`](#pullrequest-write) - [`webhook`](#webhook) - [`pipeline`](#pipeline) - [`pipeline:write`](#pipeline-write) - [`pipeline:variable`](#pipeline-variable) - [`runner`](#runner) - [`runner:write`](#runner-write) #### Project Access Tokens For details on creating, managing, and using Project Access Tokens, visit [Project Access Tokens](https://support.atlassian.com/bitbucket-cloud/docs/project-access-tokens/). The available scopes for Project Access Tokens are: - [`project`](#project) - [`repository`](#repository) - [`repository:write`](#repository-write) - [`repository:admin`](#repository-admin) - [`repository:delete`](#repository-delete) - [`pullrequest`](#pullrequest) - [`pullrequest:write`](#pullrequest-write) - [`webhook`](#webhook) - [`pipeline`](#pipeline) - [`pipeline:write`](#pipeline-write) - [`pipeline:variable`](#pipeline-variable) - [`runner`](#runner) - [`runner:write`](#runner-write) #### Workspace Access Tokens For details on creating, managing, and using Workspace Access Tokens, visit [Workspace Access Tokens](https://support.atlassian.com/bitbucket-cloud/docs/workspace-access-tokens/). The available scopes for Workspace Access Tokens are: - [`project`](#project) - [`project:admin`](#project-admin) - [`repository`](#repository) - [`repository:write`](#repository-write) - [`repository:admin`](#repository-admin) - [`repository:delete`](#repository-delete) - [`pullrequest`](#pullrequest) - [`pullrequest:write`](#pullrequest-write) - [`webhook`](#webhook) - [`account`](#account) - [`pipeline`](#pipeline) - [`pipeline:write`](#pipeline-write) - [`pipeline:variable`](#pipeline-variable) - [`runner`](#runner) - [`runner:write`](#runner-write) ### App passwords App passwords allow users to make API calls to their Bitbucket account through apps such as Sourcetree. Some important points about app passwords: * You cannot view an app password or adjust permissions after you create the app password. Because app passwords are encrypted on our database and cannot be viewed by anyone. They are essentially designed to be disposable. If you need to change the scopes or lost the password just create a new one. * You cannot use them to log into your Bitbucket account. * You cannot use app passwords to manage team actions. App passwords are tied to an individual account's credentials and should not be shared. If you're sharing your app password you're essentially giving direct, authenticated, access to everything that password has been scoped to do with the Bitbucket API's. * You can use them for API call authentication, even if you don't have two-step verification enabled. * You can set permission scopes (specific access rights) for each app password. For details on creating, managing, and using App passwords, visit [App passwords](https://support.atlassian.com/bitbucket-cloud/docs/app-passwords/). ### OAuth 2.0 Our OAuth 2 implementation is merged in with our existing OAuth 1 in such a way that existing OAuth 1 consumers automatically become valid OAuth 2 clients. The only thing you need to do is edit your existing consumer and configure a callback URL. Once that is in place, you'll have the following 2 URLs: https://bitbucket.org/site/oauth2/authorize https://bitbucket.org/site/oauth2/access_token For obtaining access/bearer tokens, we support three of RFC-6749's grant flows, plus a custom Bitbucket flow for exchanging JWT tokens for access tokens. Note that Resource Owner Password Credentials Grant (4.3) is no longer supported. #### 1. Authorization Code Grant (4.1) The full-blown 3-LO flow. Request authorization from the end user by sending their browser to: https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=code The callback includes the `?code={}` query parameter that you can swap for an access token: $ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=authorization_code -d code={code} #### 2. Implicit Grant (4.2) This flow is useful for browser-based add-ons that operate without server-side backends. Request the end user for authorization by directing the browser to: https://bitbucket.org/site/oauth2/authorize?client_id={client_id}&response_type=token That will redirect to your preconfigured callback URL with a fragment containing the access token (`#access_token={token}&token_type=bearer`) where your page's js can pull it out of the URL. #### 3. Client Credentials Grant (4.4) Somewhat like our existing "2-LO" flow for OAuth 1. Obtain an access token that represents not an end user, but the owner of the client/consumer: $ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=client_credentials #### 4. Bitbucket Cloud JWT Grant (urn:bitbucket:oauth2:jwt) If your Atlassian Connect add-on uses JWT authentication, you can swap a JWT for an OAuth access token. The resulting access token represents the account for which the add-on is installed. Make sure you send the JWT token in the Authorization request header using the "JWT" scheme (case sensitive). Note that this custom scheme makes this different from HTTP Basic Auth (and so you cannot use "curl -u"). $ curl -X POST -H "Authorization: JWT {jwt_token}" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=urn:bitbucket:oauth2:jwt #### Making Requests Once you have an access token, as per RFC-6750, you can use it in a request in any of the following ways (in decreasing order of desirability): 1. Send it in a request header: `Authorization: Bearer {access_token}` 2. Include it in a (application/x-www-form-urlencoded) POST body as `access_token={access_token}` 3. Put it in the query string of a non-POST: `?access_token={access_token}` #### Repository Cloning Since add-ons will not be able to upload their own SSH keys to clone with, access tokens can be used as Basic HTTP Auth credentials to clone securely over HTTPS. This is much like GitHub, yet slightly different: $ git clone https://x-token-auth:{access_token}@bitbucket.org/user/repo.git The literal string `x-token-auth` as a substitute for username is required (note the difference with GitHub where the actual token is in the username field). #### Refresh Tokens Our access tokens expire in one hour. When this happens you'll get 401 responses. Most access tokens grant responses (Implicit and JWT excluded). Therefore, you should include a refresh token that can then be used to generate a new access token, without the need for end user participation: $ curl -X POST -u "client_id:secret" \ https://bitbucket.org/site/oauth2/access_token \ -d grant_type=refresh_token -d refresh_token={refresh_token} ### Bitbucket OAuth 2.0 scopes Bitbucket's API applies a number of privilege scopes to endpoints. In order to access an endpoint, a request will need to have the necessary scopes. OAuth 2.0 Scopes are applicable for OAuth 2, Access Tokens, and App passwords auth mechanisms as well as Bitbucket Connect apps. Scopes are declared in the descriptor as a list of strings, with each string being the name of a unique scope. A descriptor lacking the `scopes` element is implicitly assumed to require all scopes and as a result, Bitbucket will require end users authorizing/installing the add-on to explicitly accept all scopes. Our best practice suggests you add only the scopes your add-on needs, but no more than it needs. Invalid scope strings will cause the descriptor to be rejected and the installation to fail. The available scopes are: - [project](#project) - [project:write](#project-write) - [project:admin](#project-admin) - [repository](#repository) - [repository:write](#repository-write) - [repository:admin](#repository-admin) - [repository:delete](#repository-delete) - [pullrequest](#pullrequest) - [pullrequest:write](#pullrequest-write) - [issue](#issue) - [issue:write](#issue-write) - [wiki](#wiki) - [webhook](#webhook) - [snippet](#snippet) - [snippet:write](#snippet-write) - [email](#email) - [account](#account) - [account:write](#account-write) - [pipeline](#pipeline) - [pipeline:write](#pipeline-write) - [pipeline:variable](#pipeline-variable) - [runner](#runner) - [runner:write](#runner-write) #### project Provides access to view the project or projects. This scope implies the [`repository`](#repository) scope, giving read access to all the repositories in a project or projects. #### project:write This scope is deprecated, and has been made obsolete by `project:admin`. Please see the deprecation notice [here](/cloud/bitbucket/deprecation-notice-project-write-scope). #### project:admin Provides admin access to a project or projects. No distinction is made between public and private projects. This scope doesn't implicitly grant the [`project`](#project) scope or the [`repository:write`](#repository-write) scope on any repositories under the project. It gives access to the admin features of a project only, not direct access to its repositories' contents. * ability to create the project * ability to update the project * ability to delete the project #### repository Provides read access to a repository or repositories. Note that this scope does not give access to a repository's pull requests. * access to the repo's source code * clone over HTTPS * access the file browsing API * download zip archives of the repo's contents * the ability to view and use the issue tracker on any repo (created issues, comment, vote, etc) * the ability to view and use the wiki on any repo (create/edit pages) #### repository:write Provides write (not admin) access to a repository or repositories. No distinction is made between public and private repositories. This scope implicitly grants the [`repository`](#repository) scope, which does not need to be requested separately. This scope alone does not give access to the pull requests API. * push access over HTTPS * fork repos #### repository:admin Provides admin access to a repository or repositories. No distinction is made between public and private repositories. This scope doesn't implicitly grant the [`repository`](#repository) or the [`repository:write`](#repository-write) scopes. It gives access to the admin features of a repo only, not direct access to its contents. This scope can be used or misused to grant read access to other users, who can then clone the repo, but users that need to read and write source code would also request explicit read or write. This scope comes with access to the following functionality: * View and manipulate committer mappings * List and edit deploy keys * Ability to delete the repo * View and edit repo permissions * View and edit branch permissions * Import and export the issue tracker * Enable and disable the issue tracker * List and edit issue tracker version, milestones and components * Enable and disable the wiki * List and edit default reviewers * List and edit repo links (Jira/Bamboo/Custom) * List and edit the repository webhooks * Initiate a repo ownership transfer #### repository:delete Provides access to delete a repository or repositories. #### pullrequest Provides read access to pull requests. This scope implies the [`repository`](#repository) scope, giving read access to the pull request's destination repository. * see and list pull requests * create and resolve tasks * comment on pull requests #### pullrequest:write Implicitly grants the [`pullrequest`](#pullrequest) scope and adds the ability to create, merge and decline pull requests. This scope also implicitly grants the [`repository:write`](#repository-write) scope, giving write access to the pull request's destination repository. This is necessary to allow merging. * merge pull requests * decline pull requests * create pull requests * approve pull requests #### issue Ability to interact with issue trackers the way non-repo members can. This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository. * view, list and search issues * create new issues * comment on issues * watch issues * vote for issues #### issue:write This scope implicitly grants the [`issue`](#issue) scope and adds the ability to transition and delete issues. This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository. * transition issues * delete issues #### wiki Provides access to wikis. This scope provides both read and write access (wikis are always editable by anyone with access to them). This scope doesn't implicitly grant any other scopes and doesn't give implicit access to the repository. * view wikis * create pages * edit pages * push to wikis * clone wikis #### webhook Gives access to webhooks. This scope is required for any webhook-related operation. This scope gives read access to existing webhook subscriptions on all resources the authorization mechanism can access, without needing further scopes. For example: - A client can list all existing webhook subscriptions on a repository. The [`repository`](#repository) scope is not required. - Existing webhook subscriptions for the issue tracker on a repo can be retrieved without the [`issue`](#issue) scope. All that is required is the `webhook` scope. To create webhooks, the client will need read access to the resource. Such as: for [`issue:created`](#issue-created), the client will need to have both the `webhook` and the [`issue`](#issue) scope. * list webhook subscriptions on any accessible repository, user, team, or snippet * create/update/delete webhook subscriptions. #### snippet Provides read access to snippets. No distinction is made between public and private snippets (public snippets are accessible without any form of authentication). * view any snippet * create snippet comments #### snippet:write Provides write access to snippets. No distinction is made between public and private snippets (public snippets are accessible without any form of authentication). This scope implicitly grants the [`snippet`](#snippet) scope which does not need to be requested separately. * create snippets * edit snippets * delete snippets #### email Ability to see the user's primary email address. This should make it easier to use Bitbucket Cloud as a login provider for apps or external applications. #### account When used for: * **user-related APIs** — Gives read-only access to the user's account information. Note that this doesn't include any ability to change any of the data. This scope allows you to view the user's: * email addresses * language * location * website * full name * SSH keys * user groups * **workspace-related APIs** — Grants access to view the workspace's: * users * user permissions * projects #### account:write Ability to change properties on the user's account. * delete the authorizing user's account * manage the user's groups * change a user's email addresses * change username, display name and avatar #### pipeline Gives read-only access to pipelines, steps, deployment environments and variables. #### pipeline:write Gives write access to pipelines. This scope allows a user to: * Stop pipelines * Rerun failed pipelines * Resume halted pipelines * Trigger manual pipelines. This scope is not needed to trigger a build using a push. Performing a `git push` (or equivalent actions) will trigger the build. The token doing the push only needs the [`repository:write`](#repository-write) scope. This doesn't give write access to create variables. #### pipeline:variable Gives write access to create variables in pipelines at the various levels: * Workspace * Repository * Deployment #### runner Gives read-only access to pipelines runners setup against a workspace or repository. #### runner:write Gives write access to create/edit/disable/delete pipelines runners setup against a workspace or repository. ### Forge app scopes In order for a Forge app integration to access Bitbucket API endpoints, it needs to include certain privilege scopes in the app manifest. These are different from Bitbucket OAuth 2.0 scopes. Unlike OAuth 2.0 scopes, Forge app scopes do not implicitly grant other scopes, for example, `write:repository:bitbucket` does not implicitly grant `read:repository:bitbucket`. Only a subset of Bitbucket API endpoints are currently available for Forge app integrations. These will be labeled with Forge app scopes. Our best practice suggests you only add the scopes your app needs, but no more than it needs. The available scopes are: - [`read:repository:bitbucket`](#read-repository-bitbucket) - [`write:repository:bitbucket`](#write-repository-bitbucket) - [`admin:repository:bitbucket`](#admin-repository-bitbucket) - [`delete:repository:bitbucket`](#delete-repository-bitbucket) - [`read:pullrequest:bitbucket`](#read-pullrequest-bitbucket) - [`write:pullrequest:bitbucket`](#write-pullrequest-bitbucket) - [`read:project:bitbucket`](#read-project-bitbucket) - [`admin:project:bitbucket`](#admin-project-bitbucket) - [`read:workspace:bitbucket`](#read-workspace-bitbucket) - [`read:user:bitbucket`](#read-user-bitbucket) - [`read:pipeline:bitbucket`](#read-pipeline-bitbucket) - [`write:pipeline:bitbucket`](#write-pipeline-bitbucket) - [`admin:pipeline:bitbucket`](#admin-pipeline-bitbucket) - [`read:runner:bitbucket`](#read-runner-bitbucket) - [`write:runner:bitbucket`](#write-runner-bitbucket) #### read:repository:bitbucket Allows viewing of repository data. Note that this scope does not give access to a repository's pull requests. * access to the repository's source code * access the file browsing API * access to certain repository configurations such as branching model, default reviewers, etc. #### write:repository:bitbucket Allows modification of repository data. No distinction is made between public and private repositories. This scope does not imply the `read:repository:bitbucket` scope, so you need to request that separately if required. This scope alone does not give access to the pull request API. * update/delete source, branches, tags, etc. * fork repositories #### admin:repository:bitbucket Allows admin activities on repositories. No distinction is made between public and private repositories. This scope does not implicitly grant the `read:repository:bitbucket` or the `write:repository:bitbucket` scopes. It gives access to the admin features of a repository only, not direct access to its contents. This scope does not allow modification of repository permissions. This scope comes with access to the following functionality: * create repository * view repository permissions * view and edit branch restrictions * edit branching model settings * edit default reviewers * view and edit inheritance state for repository settings #### delete:repository:bitbucket Allows deletion of repositories. #### read:pullrequest:bitbucket Allows viewing of pull requests, plus the ability to comment on pull requests. This scope does not imply the `read:repository:bitbucket` scope. With this scope, you could retrieve some data specific to the source/destination repositories of a pull request using pull request endpoints, but it does not give access to repository API endpoints. #### write:pullrequest:bitbucket Allows the ability to create, update, approve, decline, and merge pull requests. This scope does not imply the `write:repository:bitbucket` scope. #### read:project:bitbucket Allows viewing of project and project permission data. #### admin:project:bitbucket Allows the ability to create, update, and delete project. No distinction is made between public and private projects. This scope does not implicitly grant the `read:project:bitbucket` scope or any repository scopes. It gives access to the admin features of a project only, not direct access to its repositories' contents. #### read:workspace:bitbucket Allows viewing of workspace and workspace permission data. #### read:user:bitbucket Allows viewing of user data. This scope is typically required for permission related endpoints. #### read:pipeline:bitbucket Allows read access to all pipeline information (pipelines, steps, caches, artifacts, logs, tests, code-insights). #### write:pipeline:bitbucket Allows running pipelines (i.e., start/stop/create pipeline) and uploading tests/code-insights. This scope does not imply the `read:pipeline:bitbucket` scope. #### admin:pipeline:bitbucket Allows admin activities, such as creating pipeline variables. This scope does not implicitly grant the `read:pipeline:bitbucket` or the `write:pipeline:bitbucket` scopes. #### read:runner:bitbucket Allows viewing of runners information. #### write:runner:bitbucket Allows runners management. This scope does not imply the `read:runners:bitbucket` scope. - anchor: filtering title: Filter and sort API objects description: Query the 2.0 API for specific objects icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTk0LjE5MTkgMTQ3LjYwOTIiPgogIDxkZWZzPgogICAgPHN0eWxlPgogICAgICAuY2xzLTEgewogICAgICAgIGlzb2xhdGlvbjogaXNvbGF0ZTsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBmaWxsOiAjY2ZkNGRiOwogICAgICB9CgogICAgICAuY2xzLTMsIC5jbHMtNCB7CiAgICAgICAgZmlsbDogIzg3NzdkOTsKICAgICAgfQoKICAgICAgLmNscy00IHsKICAgICAgICBtaXgtYmxlbmQtbW9kZTogbXVsdGlwbHk7CiAgICAgIH0KCiAgICAgIC5jbHMtNSB7CiAgICAgICAgZmlsbDogIzAwNjVmZjsKICAgICAgfQoKICAgICAgLmNscy02IHsKICAgICAgICBmaWxsOiAjY2NlMGZmOwogICAgICB9CgogICAgICAuY2xzLTcgewogICAgICAgIGZpbGw6IHVybCgjbGluZWFyLWdyYWRpZW50KTsKICAgICAgfQogICAgPC9zdHlsZT4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50IiB4MT0iNDE2LjMwODIiIHkxPSI3NS4wNDc5IiB4Mj0iNTg0Ljg1NTYiIHkyPSI3NS4wNDc5IiBncmFkaWVudFRyYW5zZm9ybT0idHJhbnNsYXRlKC00NDMuOTQ2NyAxMjMuMDY4Nikgcm90YXRlKC0xMy43OTc2KSIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgogICAgICA8c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNmZmYiLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIwLjY5MDgiIHN0b3AtY29sb3I9IiNmZmYiIHN0b3Atb3BhY2l0eT0iMC4xIi8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogIDwvZGVmcz4KICA8dGl0bGU+TWFnbmlmeWluZyBHbGFzczwvdGl0bGU+CiAgPGcgY2xhc3M9ImNscy0xIj4KICAgIDxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPgogICAgICA8ZyBpZD0iT2JqZWN0cyI+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTMxLjExMjUsOTQuOTMwN2wtOS44ODc4LTUuOTg4OC04LjMyOTIsMTMuNzUxOSw5Ljg4NzgsNS45ODg4YTE1LjYwMywxNS42MDMsMCwwLDEsNS44OCw2LjM4MzVoMGExNS42MDMsMTUuNjAzLDAsMCwwLDUuODgsNi4zODM1bDQwLjExNDMsMjQuMjk2NGExMi44NjY0LDEyLjg2NjQsMCwwLDAsMTcuNjcwOS00LjM0aDBhMTIuODY2NCwxMi44NjY0LDAsMCwwLTQuMzQtMTcuNjcwOUwxNDcuODc0OSw5OS40MzkyYTE1LjYwMywxNS42MDMsMCwwLDAtOC4zODEyLTIuMjU0MmgwQTE1LjYwMywxNS42MDMsMCwwLDEsMTMxLjExMjUsOTQuOTMwN1oiLz4KICAgICAgICA8cGF0aCBpZD0iX1BhdGhfIiBkYXRhLW5hbWU9IiZsdDtQYXRoJmd0OyIgY2xhc3M9ImNscy0zIiBkPSJNMTMxLjExMjUsOTQuOTMwN2wtMy4wMTE4LTEuODI0MkE4LjAzODgsOC4wMzg4LDAsMCwwLDExNy4wNiw5NS44MTc4aDBhOC4wMzg4LDguMDM4OCwwLDAsMCwyLjcxMTMsMTEuMDQwNWwzLjAxMTgsMS44MjQyYTE1LjYwMywxNS42MDMsMCwwLDEsNS44OCw2LjM4MzVoMGExNS42MDMsMTUuNjAzLDAsMCwwLDUuODgsNi4zODM1bDQwLjExNDMsMjQuMjk2NGExMi44NjY0LDEyLjg2NjQsMCwwLDAsMTcuNjcwOS00LjM0aDBhMTIuODY2NCwxMi44NjY0LDAsMCwwLTQuMzQtMTcuNjcwOUwxNDcuODc0OSw5OS40MzkyYTE1LjYwMywxNS42MDMsMCwwLDAtOC4zODEyLTIuMjU0M2gwQTE1LjYwMywxNS42MDMsMCwwLDEsMTMxLjExMjUsOTQuOTMwN1oiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTQiIGQ9Ik0xMzkuMTQzNyw5Ny4xNzkyYTE1LjU5NzMsMTUuNTk3MywwLDAsMS04LjAzMTItMi4yNDg1bC0zLjAxMTgtMS44MjQyQTguMDM4OCw4LjAzODgsMCwwLDAsMTE3LjA2LDk1LjgxNzhoMGE4LjAzODgsOC4wMzg4LDAsMCwwLDIuNzExMywxMS4wNDA1bDMuMDExOCwxLjgyNDJhMTUuNTk3LDE1LjU5NywwLDAsMSw1LjcwNjksNi4wNjQ4LDY3Ljg0ODEsNjcuODQ4MSwwLDAsMCwxMC42NTM2LTE3LjU2ODFaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy01IiBkPSJNODMuMjUzNywxMzIuNTU2QTY3LjIzNDgsNjcuMjM0OCwwLDAsMSw5LjcxLDMyLjQyOTUsNjYuNzk3NCw2Ni43OTc0LDAsMCwxLDUxLjE4MzcsMS45NjY2bC4wMDA3LDBBNjYuNzk2Miw2Ni43OTYyLDAsMCwxLDEwMi4wNTEsOS43NTI1aDBBNjcuMjM0Niw2Ny4yMzQ2LDAsMCwxLDgzLjI1MzcsMTMyLjU1NloiLz4KICAgICAgICA8cGF0aCBpZD0iX1BhdGhfMiIgZGF0YS1uYW1lPSImbHQ7UGF0aCZndDsiIGNsYXNzPSJjbHMtNiIgZD0iTTIzLjQzOSw0MC43NDgyQTUxLjE5MDgsNTEuMTkwOCwwLDAsMCwxMTEuMDEsOTMuNzg4OSw1MS4xOTA4LDUxLjE5MDgsMCwwLDAsMjMuNDM5LDQwLjc0ODJaIi8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy03IiBkPSJNNzkuNDMzLDExNi45ODJBNTEuMjE2Miw1MS4yMTYyLDAsMCwwLDExOC40MjQxLDY3LjAzN2E0OS4xMzkxLDQ5LjEzOTEsMCwwLDEtNS4wODY3LDIuMjc4OWMtMTUuNzAyOSw1Ljk2MDktMjkuNjg5NSwyLjExLTM2LjQ5ODcuMTMwOC0yMC40MzA3LTUuOTM5LTI0Ljc5LTE3LjM3ODUtMzkuMDQxNC0yNC41ODIzYTQ4LjMwOTIsNDguMzA5MiwwLDAsMC0xNC4wOTM5LTQuNTNjLS4wODYyLjEzOTUtLjE3OTMuMjczLS4yNjQ0LjQxMzVBNTEuMTkwNyw1MS4xOTA3LDAsMCwwLDc5LjQzMywxMTYuOTgyWiIvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K' body: "\nYou can query the 2.0 API for specific objects using a simple language which resembles SQL.\n\nNote that filtering and querying by username has been deprecated, due to privacy changes. \nSee the [announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr/#changes-to-querying) \nfor details.\n\n\n\n* [Supported endpoints](#supported-endpoints)\n* [Operators](#operators)\n* [Data types](#data-types)\n* [Querying](#querying)\n* [Sorting query results](#sorting-query-results)\n\n-\n\n### Supported endpoints\n\nMost 2.0 API resources that return paginated collections of objects support a single, shared, generic querying language that is used to filter down a result set.\n\nThis includes, but is in no way limited to:\n\n /2.0/repositories/{username}\n /2.0/repositories/{username}/{slug}/refs\n /2.0/repositories/{username}/{slug}/refs/branches\n /2.0/repositories/{username}/{slug}/refs/tags\n /2.0/repositories/{username}/{slug}/forks\n /2.0/repositories/{username}/{slug}/src\n /2.0/repositories/{username}/{slug}/issues\n /2.0/repositories/{username}/{slug}/pullrequests\n\nFiltering and sorting supports several distinct operators and data types as well as basic features, like logical operators (AND, OR).\nAs examples, the following queries could be used on the issue tracker endpoint (`/2.0/repositories/{workspace}/{slug}/issues/`):\n\n\t(state = \"open\" OR state = \"new\") AND assignee = null\n\treporter.nickname != \"evzijst\" AND priority >= \"major\"\n\t(title ~ \"unicode\" OR content.raw ~ \"unicode\") AND created_on > 2015-10-04T14:00:00-07:00\n\nFilter queries can be added to the URL using the q= query parameter. To sort the response, add sort=. Note that the entire query string is put in the q parameter and hence needs to be URL-encoded as shown in the following example:\n\n\t/2.0/repositories/foo/bar/issues?q=state=\"new\"&sort=-updated_on\n\n\n### Operators\n\nFiltering and sorting supports the following operators:\n\n| Operator | Definition | Example |\n|-|--|-|\n| \"=\" | test for equality | `nickname = \"evzijst\"` |\n| \"!=\" | not equal | `is_private != true` |\n| \"~\" | case-insensitive text contains | `description ~ \"beef\"` |\n| \"!~\" | case-insensitive not contains | `description !~ \"fubar\"` |\n| \">\" | greater than | `priority > \"major\"` |\n| \">=\" | greater than or equal | `priority <= \"trivial\"` |\n| \"<\" | less than | `id < 1234` |\n| \"<=\" | less than or equal | `updated_on <= 2015-03-04` |\n\n### Data types\n\nFiltering and sorting supports the following data types:\n\n| Type | Description | Example |\n|--|--||\n| **String** | any text inside double quotes | `\"foo\"` |\n| **Number** | arbitrary precision integers and floats | `1, -10.302` |\n| **Null** | to test for the absence of a value | `null` |\n| **boolean** | the unquoted strings true or false | `true, false` |\n| **datetime** | an unquoted [ISO-8601][iso-8601] date time string with the timezone offset, milliseconds and entire time component being optional | `2015-03-04T14:08:59.123+02:00`, `2015-03-04T14:08:59` Date time strings are assumed to be in UTC, unless an explicit timezone offset is provided |\n\n[https://en.wikipedia.org/wiki/ISO_8601]: /iso-8601\n\n### Querying\n\nObjects can be filtered based on their properties. In principle, every element in an object's JSON document schema can be used as a filter criterion.\n\nNote that while the array of objects in a paginated response is wrapped in an\nenvelope with a `values` element, this prefix should not be included in the\nquery fields (so use `/2.0/repositories/foo/bar/issues?q=state=\"new\"`, not\n`/2.0/repositories/foo/bar/issues?q=values.state=\"new\"`).\n\n\n### Examples\n\nFields that contain embedded instances of other object types (e.g. owner is an embedded user object, while parent is an embedded repository) can be traversed recursively. For instance:\n\n\tparent.owner.nickname = \"bitbucket\"\n\nTo find pull requests which merge into master, come from a fork of the repo rather than a branch inside the repo, and on which I am a reviewer:\n\n```\nsource.repository.full_name != \"main/repo\" AND state = \"OPEN\" AND reviewers.nickname = \"evzijst\" AND destination.branch.name = \"master\"\n```\n```\n/2.0/repositories/main/repo/pullrequests?q=source.repository.full_name+%21%3D+%22main%2Frepo%22+AND+state+%3D+%22OPEN%22+AND+reviewers.nickname+%3D+%22evzijst%22+AND+destination.branch.name+%3D+%22master%22\n```\n\nTo find new or on-hold issues related to the UI, created or updated in the last day (SF local time), that have not yet been assigned to anyone:\n\n```\n(state = \"new\" OR state = \"on hold\") AND assignee = null AND component = \"UI\" and updated_on > 2015-11-11T00:00:00-07:00\n```\n```\n/2.0/repositories/main/repo/issues?q=%28state+%3D+%22new%22+OR+state+%3D+%22on+hold%22%29+AND+assignee+%3D+null+AND+component+%3D+%22UI%22+and+updated_on+%3E+2015-11-11T00%3A00%3A00-07%3A00\n```\n\nTo find all tags with the string \"2015\" in the name:\n\n```\nname ~ \"2015\"\n```\n```\n/2.0/repositories/{username}/{slug}/refs/tags?q=name+%7E+%222015%22\n```\nOr all my branches:\n\n```\nname ~ \"erik/\"\n```\n```\n/2.0/repositories/{username}/{slug}/refs/?q=name+%7E+%22erik%2F%22\n```\n### Sorting query results\n\nYou can sort result sets using the ?sort= query parameter, available on the same resources that support filtering:\n\n* In principle, every field that can be queried can also be used as a key for sorting.\n* By default the sort order is ascending. To reverse the order, prefix the field name with a hyphen (e.g. ?sort=-updated_on).\n* Only one field can be sorted on. Compound fields (e.g. sort on state first, followed by updated_on) are not supported.\n\n\n" - anchor: pagination title: Pagination description: Learn more about pagination icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMjM4LjgyIDE1MS42Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6I2IyZDRmZjt9LmNscy0ye2ZpbGw6IzRjOWFmZjt9LmNscy0ze2ZpbGw6IzAwNTJjYzt9LmNscy00e29wYWNpdHk6MC42O30uY2xzLTV7ZmlsbDp1cmwoI2xpbmVhci1ncmFkaWVudCk7fS5jbHMtNntmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTIpO30uY2xzLTd7ZmlsbDp1cmwoI2xpbmVhci1ncmFkaWVudC0zKTt9LmNscy04e2ZpbGw6dXJsKCNsaW5lYXItZ3JhZGllbnQtNCk7fS5jbHMtOXtmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTUpO30uY2xzLTEwLC5jbHMtMTEsLmNscy0xMntmaWxsOm5vbmU7fS5jbHMtMTB7c3Ryb2tlOiMzMzg0ZmY7fS5jbHMtMTAsLmNscy0xMSwuY2xzLTEyLC5jbHMtMTN7c3Ryb2tlLW1pdGVybGltaXQ6MTA7c3Ryb2tlLXdpZHRoOjJweDt9LmNscy0xMXtzdHJva2U6I2ZmYWIwMDt9LmNscy0xMntzdHJva2U6I2ZhZmJmYzt9LmNscy0xM3tmaWxsOiNmZmFiMDA7c3Ryb2tlOiMyNjg0ZmY7fTwvc3R5bGU+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQiIHkxPSI2NS4xNyIgeDI9Ijg2LjM4IiB5Mj0iNjUuMTciIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiM0YzlhZmYiLz48c3RvcCBvZmZzZXQ9IjAuMDgiIHN0b3AtY29sb3I9IiM0YzlhZmYiIHN0b3Atb3BhY2l0eT0iMC45NCIvPjxzdG9wIG9mZnNldD0iMC4yNCIgc3RvcC1jb2xvcj0iIzRjOWFmZiIgc3RvcC1vcGFjaXR5PSIwLjc4Ii8+PHN0b3Agb2Zmc2V0PSIwLjQ1IiBzdG9wLWNvbG9yPSIjNGM5YWZmIiBzdG9wLW9wYWNpdHk9IjAuNTMiLz48c3RvcCBvZmZzZXQ9IjAuNTUiIHN0b3AtY29sb3I9IiM0YzlhZmYiIHN0b3Atb3BhY2l0eT0iMC40Ii8+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9ImxpbmVhci1ncmFkaWVudC0yIiB4MT0iMTUyLjQ0IiB5MT0iNjUuMTciIHgyPSIyMzguODIiIHkyPSI2NS4xNyIgeGxpbms6aHJlZj0iI2xpbmVhci1ncmFkaWVudCIvPjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50LTMiIHgxPSIxOC44NSIgeTE9IjExOC43OCIgeDI9IjEyNi4wOCIgeTI9IjExLjU2IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agb2Zmc2V0PSIwLjA2IiBzdG9wLWNvbG9yPSIjMDA2NWZmIi8+PHN0b3Agb2Zmc2V0PSIwLjE5IiBzdG9wLWNvbG9yPSIjMDA2NWZmIiBzdG9wLW9wYWNpdHk9IjAuOTQiLz48c3RvcCBvZmZzZXQ9IjAuNDYiIHN0b3AtY29sb3I9IiMwMDY1ZmYiIHN0b3Atb3BhY2l0eT0iMC43OCIvPjxzdG9wIG9mZnNldD0iMC44MiIgc3RvcC1jb2xvcj0iIzAwNjVmZiIgc3RvcC1vcGFjaXR5PSIwLjUzIi8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMDA2NWZmIiBzdG9wLW9wYWNpdHk9IjAuNCIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQtNCIgeDE9IjExMi43NSIgeTE9IjExOC43OCIgeDI9IjIxOS45NyIgeTI9IjExLjU2IiB4bGluazpocmVmPSIjbGluZWFyLWdyYWRpZW50LTMiLz48bGluZWFyR3JhZGllbnQgaWQ9ImxpbmVhci1ncmFkaWVudC01IiB4MT0iNTAuOTciIHkxPSIxMzMuNjEiIHgyPSIxODcuODYiIHkyPSItMy4yOCIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIG9mZnNldD0iMC42NiIgc3RvcC1jb2xvcj0iIzI1Mzg1OCIvPjxzdG9wIG9mZnNldD0iMC44OCIgc3RvcC1jb2xvcj0iIzI1Mzg1OCIgc3RvcC1vcGFjaXR5PSIwLjgzIi8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMjUzODU4IiBzdG9wLW9wYWNpdHk9IjAuNyIvPjwvbGluZWFyR3JhZGllbnQ+PC9kZWZzPjx0aXRsZT5WaWV3IFZlcnNpb25zPC90aXRsZT48ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIj48ZyBpZD0iU29mdHdhcmUiPjxjaXJjbGUgY2xhc3M9ImNscy0xIiBjeD0iOTQuNTMiIGN5PSIxNDcuOTMiIHI9IjMuNjciLz48Y2lyY2xlIGNsYXNzPSJjbHMtMiIgY3g9IjEwNi45NCIgY3k9IjE0Ny45MyIgcj0iMy42NyIvPjxjaXJjbGUgY2xhc3M9ImNscy0zIiBjeD0iMTE5LjM0IiBjeT0iMTQ3LjkzIiByPSIzLjY3Ii8+PGNpcmNsZSBjbGFzcz0iY2xzLTIiIGN4PSIxMzEuNzUiIGN5PSIxNDcuOTMiIHI9IjMuNjciLz48Y2lyY2xlIGNsYXNzPSJjbHMtMSIgY3g9IjE0NC4xNiIgY3k9IjE0Ny45MyIgcj0iMy42NyIvPjxnIGNsYXNzPSJjbHMtNCI+PHJlY3QgaWQ9Il9SZWN0YW5nbGVfIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTUiIHk9IjI1LjkyIiB3aWR0aD0iODYuMzgiIGhlaWdodD0iNzguNDkiLz48L2c+PGcgY2xhc3M9ImNscy00Ij48cmVjdCBpZD0iX1JlY3RhbmdsZV8yIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTYiIHg9IjE1Mi40NCIgeT0iMjUuOTIiIHdpZHRoPSI4Ni4zOCIgaGVpZ2h0PSI3OC40OSIvPjwvZz48cmVjdCBpZD0iX1JlY3RhbmdsZV8zIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTciIHg9IjE2LjI4IiB5PSIxNC4xMiIgd2lkdGg9IjExMi4zNiIgaGVpZ2h0PSIxMDIuMDkiLz48cmVjdCBpZD0iX1JlY3RhbmdsZV80IiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTgiIHg9IjExMC4xOCIgeT0iMTQuMTIiIHdpZHRoPSIxMTIuMzYiIGhlaWdodD0iMTAyLjA5Ii8+PHJlY3QgaWQ9Il9SZWN0YW5nbGVfNSIgZGF0YS1uYW1lPSImbHQ7UmVjdGFuZ2xlJmd0OyIgY2xhc3M9ImNscy05IiB4PSI0Ny42OSIgd2lkdGg9IjE0My40NSIgaGVpZ2h0PSIxMzAuMzQiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNzkuMTYiIHkxPSIxNi4xOCIgeDI9IjExNy4yNCIgeTI9IjE2LjE4Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjYyLjkzIiB5MT0iMTYuMTgiIHgyPSI3Mi42IiB5Mj0iMTYuMTgiLz48bGluZSBjbGFzcz0iY2xzLTExIiB4MT0iNzkuMTYiIHkxPSIyNi45NSIgeDI9IjExNy4yNCIgeTI9IjI2Ljk1Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjYyLjkzIiB5MT0iMjYuOTUiIHgyPSI3Mi42IiB5Mj0iMjYuOTUiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNzkuMTYiIHkxPSIzNy43MiIgeDI9IjE1MC43IiB5Mj0iMzcuNzIiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSIzNy43MiIgeDI9IjcyLjYiIHkyPSIzNy43MiIvPjxsaW5lIGNsYXNzPSJjbHMtMTEiIHgxPSIxNTAuNyIgeTE9IjQ4LjQ5IiB4Mj0iMTc1LjU5IiB5Mj0iNDguNDkiLz48bGluZSBjbGFzcz0iY2xzLTEyIiB4MT0iMTEwLjMyIiB5MT0iNDguNDkiIHgyPSIxNDMuMDUiIHkyPSI0OC40OSIvPjxsaW5lIGNsYXNzPSJjbHMtMTEiIHgxPSI3OS4xNiIgeTE9IjQ4LjQ5IiB4Mj0iMTAxLjM3IiB5Mj0iNDguNDkiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSI0OC40OSIgeDI9IjcyLjYiIHkyPSI0OC40OSIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI3OS4xNiIgeTE9IjU5LjI2IiB4Mj0iMTUwLjciIHkyPSI1OS4yNiIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjU5LjI2IiB4Mj0iNzIuNiIgeTI9IjU5LjI2Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9Ijc5LjE2IiB5MT0iNzAuMDMiIHgyPSIxNzUuNTkiIHkyPSI3MC4wMyIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjcwLjAzIiB4Mj0iNzIuNiIgeTI9IjcwLjAzIi8+PGxpbmUgY2xhc3M9ImNscy0xMSIgeDE9Ijc5LjE2IiB5MT0iODAuNzkiIHgyPSIxMTcuMjQiIHkyPSI4MC43OSIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjgwLjc5IiB4Mj0iNzIuNiIgeTI9IjgwLjc5Ii8+PGxpbmUgY2xhc3M9ImNscy0xMyIgeDE9Ijc5LjE2IiB5MT0iOTEuNTYiIHgyPSIxNDkuMDYiIHkyPSI5MS41NiIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjkxLjU2IiB4Mj0iNzIuNiIgeTI9IjkxLjU2Ii8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjYyLjkzIiB5MT0iODAuNzkiIHgyPSI3Mi42IiB5Mj0iODAuNzkiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSI5MS41NiIgeDI9IjcyLjYiIHkyPSI5MS41NiIvPjxsaW5lIGNsYXNzPSJjbHMtMTEiIHgxPSI3OS4xNiIgeTE9IjEwMi4zMyIgeDI9IjExNy4yNCIgeTI9IjEwMi4zMyIvPjxsaW5lIGNsYXNzPSJjbHMtMTAiIHgxPSI2Mi45MyIgeTE9IjEwMi4zMyIgeDI9IjcyLjYiIHkyPSIxMDIuMzMiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iMTI1Ljk4IiB5MT0iMTEzLjEiIHgyPSIxNDkuMDYiIHkyPSIxMTMuMSIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSI3OS4xNiIgeTE9IjExMy4xIiB4Mj0iMTE3LjI0IiB5Mj0iMTEzLjEiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iNjIuOTMiIHkxPSIxMTMuMSIgeDI9IjcyLjYiIHkyPSIxMTMuMSIvPjwvZz48L2c+PC9zdmc+' body: >2 Endpoints that return collections of objects should always apply pagination. Paginated collections are always wrapped in the following wrapper object: ```json { "size": 5421, "page": 2, "pagelen": 10, "next": "https://api.bitbucket.org/2.0/repositories/pypy/pypy/commits?page=3", "previous": "https://api.bitbucket.org/2.0/repositories/pypy/pypy/commits?page=1", "values": [ ... ] } ``` Pagination is often page-bound, with a query parameter page indicating which page is to be returned. However, clients are not expected to construct URLs themselves by manipulating the page number query parameter. Instead, the response contains a link to the next page. This link should be treated as an opaque location that is not to be constructed by clients or even assumed to be predictable. The only contract around the next link is that it will return the next chunk of results. Lack of a next link in the response indicates the end of the collection. The paginated response contains the following fields: | Field | Value | ||-| | `size` | Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. | | `page` | Page number of the current results. This is an optional element that is not provided in all responses. | | `pagelen` | Current number of objects on the existing page. Globally, the minimum length is 10 and the maximum is 100. Some APIs may specify a different default. | | `next` | Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. | | `previous` | Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. | | `values` | The list of objects. This contains at most `pagelen` objects. | The link to the next page is included such that you don't have to hardcode or construct any links. Only values and next are guaranteed (except the last page, which lacks next). This is because the previous and size values can be expensive for some data sets. It is important to realize that Bitbucket support both list-based pagination and iterator-based pagination. List-based pagination assumes that the collection is a discrete, immutable, consistently ordered, finite array of objects with a fixed size. Clients navigate a list-based collection by requesting offset-based chunks. In Bitbucket Cloud, list-based responses include the optional size, page, and previous element. The the next and previous links typically resemble something like /foo/bar?page=4. However, not all result sets can be treated as immutable and finite – much like how programming languages tend to distinguish between lists and arrays on one hand and iterators or stream on the other. Where an list-based pagination offers random access into any point in a collection, iterator-based pagination can only navigate forward one element at a time. In Bitbucket such iterator-based pagination contains the next link and pagelen elements, but not necessarily anything else. In these cases, the next link's value often contains an unpredictable hash instead of an explicit page number. The commits resource uses iterator-based pagination. - anchor: partial-response title: Partial responses description: Tweak which fields are returned icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTYyLjQ0ODcgMjEwLjExMTUiPgogIDxkZWZzPgogICAgPHN0eWxlPgogICAgICAuY2xzLTEgewogICAgICAgIGlzb2xhdGlvbjogaXNvbGF0ZTsKICAgICAgfQoKICAgICAgLmNscy0yLCAuY2xzLTYsIC5jbHMtOCB7CiAgICAgICAgZmlsbDogbm9uZTsKICAgICAgfQoKICAgICAgLmNscy0yLCAuY2xzLTggewogICAgICAgIHN0cm9rZTogIzAwNjVmZjsKICAgICAgICBzdHJva2Utd2lkdGg6IDJweDsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBzdHJva2UtbGluZWpvaW46IHJvdW5kOwogICAgICB9CgogICAgICAuY2xzLTMgewogICAgICAgIGZpbGw6ICNlN2U4ZWM7CiAgICAgIH0KCiAgICAgIC5jbHMtNCB7CiAgICAgICAgZmlsbDogI2ZmZTM4MDsKICAgICAgfQoKICAgICAgLmNscy01IHsKICAgICAgICBmaWxsOiAjZmZmMGIyOwogICAgICB9CgogICAgICAuY2xzLTYgewogICAgICAgIHN0cm9rZTogI2ZmOTkxZjsKICAgICAgICBzdHJva2Utd2lkdGg6IDEuODE1NnB4OwogICAgICB9CgogICAgICAuY2xzLTYsIC5jbHMtOCB7CiAgICAgICAgc3Ryb2tlLW1pdGVybGltaXQ6IDEwOwogICAgICB9CgogICAgICAuY2xzLTcgewogICAgICAgIG1peC1ibGVuZC1tb2RlOiBtdWx0aXBseTsKICAgICAgICBmaWxsOiB1cmwoI2xpbmVhci1ncmFkaWVudCk7CiAgICAgIH0KCiAgICAgIC5jbHMtOSB7CiAgICAgICAgZmlsbDogI2Y0ZjVmNzsKICAgICAgfQogICAgPC9zdHlsZT4KICAgIDxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50IiB4MT0iMTEzLjM4MTgiIHkxPSI0OS40MyIgeDI9IjE1My43ODkzIiB5Mj0iOS4wMjI1IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iI2ZhZmJmYyIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjAuMjc4NiIgc3RvcC1jb2xvcj0iI2VmZjFmMyIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjAuNzY4OCIgc3RvcC1jb2xvcj0iI2QxZDZkZCIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNjMWM3ZDAiLz4KICAgIDwvbGluZWFyR3JhZGllbnQ+CiAgPC9kZWZzPgogIDx0aXRsZT5Eb2N1bWVudCBUYWJsZTwvdGl0bGU+CiAgPGcgY2xhc3M9ImNscy0xIj4KICAgIDxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPgogICAgICA8ZyBpZD0iT2JqZWN0cyI+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0yIiB4MT0iMTcuNDcxIiB5MT0iMTcxLjc1NzMiIHgyPSI3OS4yOTgiIHkyPSIxNzEuNzU3MyIvPgogICAgICAgIDxwb2x5Z29uIGlkPSJfUGF0aF8iIGRhdGEtbmFtZT0iJmx0O1BhdGgmZ3Q7IiBjbGFzcz0iY2xzLTMiIHBvaW50cz0iMTYyLjQ0NSAzOC43MTEgMTYyLjQ0NSAyMTAuMTExIDAgMjEwLjExMSAwIDAgMTIzLjcwNCAwIDE2Mi40MTUgMzguNzExIDE2Mi40NDUgMzguNzExIi8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy00IiB4PSIxOC45MTE3IiB5PSI3OC4xNTQyIiB3aWR0aD0iNDcuODQ4NSIgaGVpZ2h0PSI3OS42NTM3Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy01IiB4PSIxOC45MTE3IiB5PSI1MS42MDMiIHdpZHRoPSIxMjMuNDUyOSIgaGVpZ2h0PSIyNi41NTEyIi8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy02IiB4PSIxOC45MTE3IiB5PSI1MS42MDMiIHdpZHRoPSIxMjMuNDUyOSIgaGVpZ2h0PSIxMDYuMjA0OSIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtNiIgeDE9IjY2Ljc2MDEiIHkxPSI1MS42MDMiIHgyPSI2Ni43NjAxIiB5Mj0iMTU3LjgwNzkiLz4KICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTYiIHgxPSI5MS4zMjg0IiB5MT0iNTEuNjAzIiB4Mj0iOTEuMzI4NCIgeTI9IjE1Ny44MDc5Ii8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTE1Ljg5NjciIHkxPSI1MS42MDMiIHgyPSIxMTUuODk2NyIgeTI9IjE1Ny44MDc5Ii8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTguOTExNyIgeTE9Ijc4LjE1NDIiIHgyPSIxNDIuMzY0NiIgeTI9Ijc4LjE1NDIiLz4KICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTYiIHgxPSIxOC45MTE3IiB5MT0iMTA0LjcwNTUiIHgyPSIxNDIuMzY0NiIgeTI9IjEwNC43MDU1Ii8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTguOTExNyIgeTE9IjEzMS4yNTY3IiB4Mj0iMTQyLjM2NDYiIHkyPSIxMzEuMjU2NyIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtNyIgcG9pbnRzPSIxNjIuNDQ1IDM4LjcxMSAxNjIuNDE1IDM4LjcxMSAxMjMuODcyIDAuMTY5IDEyMy44NzIgNTkuOTIxIDE2Mi40NDUgMzkuMTM3IDE2Mi40NDUgMzguNzExIi8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy04IiB4MT0iMTguMzk3MyIgeTE9IjE4MS4zNDQiIHgyPSI3OS4xMTM1IiB5Mj0iMTgxLjM0NCIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtOCIgeDE9IjE4LjM5NzMiIHkxPSIxOTAuOTMwNiIgeDI9IjUxLjMwNDkiIHkyPSIxOTAuOTMwNiIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtOCIgeDE9IjE4LjM5NzMiIHkxPSIxNzEuNzU3MyIgeDI9Ijc5LjExMzUiIHkyPSIxNzEuNzU3MyIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtOCIgeDE9IjE4LjM5NzMiIHkxPSIzNi4xNzA1IiB4Mj0iNzkuMTEzNSIgeTI9IjM2LjE3MDUiLz4KICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTgiIHgxPSIxOC4zOTczIiB5MT0iMjYuNTgzOCIgeDI9Ijc5LjExMzUiIHkyPSIyNi41ODM4Ii8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy05IiBwb2ludHM9IjE2Mi40NDkgMzguNzQyIDEyMy43MDcgMzguNzQyIDEyMy43MDcgMCAxNjIuNDQ5IDM4Ljc0MiIvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K' body: >2 By default, each endpoint returns the full representation of a resource and in some cases that can be a lot of data. For example, retrieving a list of pull requests can amount to quite a large document. For better performance, you can ask the server to only return the fields you really need and to omit unwanted data. To request a partial response and to add or remove specific fields from a response, use the `fields` query parameter. ### Example Most API resources embed a substantial list of links pointing to related resources. This saves the client from constructing its own URLs, but is somewhat wasteful when the client doesn't need them. To significantly reduce the size of the response, use `?fields=-links`: ```json $ curl https://api.bitbucket.org/2.0/users/evzijst?fields=-links { "nickname": "evzijst", "account_status": "active", "website": "", "display_name": "Erik van Zijst", "uuid": "{a288a0ab-e13b-43f0-a689-c4ef0a249875}", "created_on": "2010-07-07T05:16:36+00:00", "location": null, "type": "user" } ``` ### Fields parameter syntax The `fields` parameter supports 3 modes of operation: 1. Removal of select fields (e.g. `-links`) 2. Pulling in additional fields not normally returned by an endpoint, while still getting all the default fields (e.g. `+reviewers`) 3. Omitting all fields, except those specified (e.g. `owner.display_name`) The fields parameter can contain a list of multiple comma-separated field names (e.g. `fields=owner.display_name,uuid,links.self.href`). The parameter itself is not repeated. As discussed at [Condensed Versus Full Objects](serialization#representations), most objects that are embedded inside other objects (like how `owner` is an embedded `user` object in `repository`) appear in "condensed" form that omits many fields. The `fields` parameter allows us to pull in additional fields in such cases. For example, the embedded repository object in a pull request does not normally contain its `owner`. To add that in we can use: `+values.destination.repository.owner`. ### Wildcards The asterisk can be used to match all fields on a particular level. For example, removing all entries from the `links` element can be done like this: ```json $ curl https://api.bitbucket.org/2.0/users/evzijst?fields=-links.* { "nickname": "evzijst", "account_status": "active", "website": "", "display_name": "Erik van Zijst", "uuid": "{a288a0ab-e13b-43f0-a689-c4ef0a249875}", "links": {}, "created_on": "2010-07-07T05:16:36+00:00", "location": null, "type": "user" } ``` Wildcards can be used in combination with exclusion and inclusion. For instance, `-*,+foo,+bar` will remove all elements from the root level and then add in `foo` and `bar`. ### URL encoding Be aware that when using the `+foo.bar` syntax in the query string, that the "+" must be URL encoded as "%2B" and so the URL will be: ``` https://api.bitbucket.org/2.0/repositories/evzijst/interruptingcow?fields=%2Bowner.created_on ``` Without URL escaping, "+" is interpreted as an encoded space which will not match any fields. ### Field discovery While a resource's `self` URL, as well its "collection" URL typically return the full object with all its fields, there are some exceptions for fields that are overly verbose or costly to generate. For instance, a pull request contains the embedded lists of reviewers and participants. These fields are included from the `self` URL, but not from the `/pullrequests` collections resource, as it would impact performance too much. To discover any additional fields that might not be included by default, `fields=*` can be used. ### More examples If we want to get a list of all reviewer nicknames on pull requests I created, we could combine a [filter](filtering) with a partial response. This will omit all other data from the response: ``` /2.0/repositories/bitbucket/bitbucket/pullrequests?fields=values.id,values.reviewers.nickname,values.state&q=author.uuid%3D%22%7Bd301aafa-d676-4ee0-88be-962be7417567%7D%22 { "values": [ { "reviewers": [ { "nickname": "abhin" }, { "nickname": "dtao" }, { "nickname": "csomme" } ], "state": "OPEN", "id": 11355 }, { "reviewers": [ { "nickname": "csomme" }, { "nickname": "abhin" }, { "nickname": "dstevens" } ], "state": "MERGED", "id": 11347 }, { "reviewers": [ { "nickname": "csomme" }, { "nickname": "jmooring" }, { "nickname": "zdavis" }, { "nickname": "flexbox" } ], "state": "OPEN", "id": 11344 } ] } ``` - anchor: serialization title: Schemas and Serialization description: Learn more about object representations icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyMjAuNzYyNCAyMDUuNTg2Ij4KICA8ZGVmcz4KICAgIDxzdHlsZT4KICAgICAgLmNscy0xIHsKICAgICAgICBpc29sYXRpb246IGlzb2xhdGU7CiAgICAgIH0KCiAgICAgIC5jbHMtMiwgLmNscy02IHsKICAgICAgICBtaXgtYmxlbmQtbW9kZTogbXVsdGlwbHk7CiAgICAgIH0KCiAgICAgIC5jbHMtMTMsIC5jbHMtMywgLmNscy00LCAuY2xzLTYgewogICAgICAgIGZpbGw6IG5vbmU7CiAgICAgICAgc3Ryb2tlOiAjYzFjN2QwOwogICAgICAgIHN0cm9rZS1saW5lY2FwOiByb3VuZDsKICAgICAgICBzdHJva2UtbWl0ZXJsaW1pdDogMTA7CiAgICAgICAgc3Ryb2tlLXdpZHRoOiAycHg7CiAgICAgIH0KCiAgICAgIC5jbHMtNCB7CiAgICAgICAgc3Ryb2tlLWRhc2hhcnJheTogMy43ODE2IDUuMjk0MzsKICAgICAgfQoKICAgICAgLmNscy01IHsKICAgICAgICBmaWxsOiAjMDA2NWZmOwogICAgICB9CgogICAgICAuY2xzLTYgewogICAgICAgIHN0cm9rZS1kYXNoYXJyYXk6IDMuOTIxOSA1LjQ5MDc7CiAgICAgIH0KCiAgICAgIC5jbHMtNyB7CiAgICAgICAgZmlsbDogIzAwNTJjYzsKICAgICAgfQoKICAgICAgLmNscy04IHsKICAgICAgICBmaWxsOiAjNGM5YWZmOwogICAgICB9CgogICAgICAuY2xzLTkgewogICAgICAgIGZpbGw6ICMwMDQ5YjA7CiAgICAgIH0KCiAgICAgIC5jbHMtMTAgewogICAgICAgIGZpbGw6ICM1N2Q5YTM7CiAgICAgIH0KCiAgICAgIC5jbHMtMTEgewogICAgICAgIGZpbGw6ICM3OWYyYzA7CiAgICAgIH0KCiAgICAgIC5jbHMtMTIgewogICAgICAgIGZpbGw6ICMzNmIzN2U7CiAgICAgIH0KCiAgICAgIC5jbHMtMTMgewogICAgICAgIHN0cm9rZS1kYXNoYXJyYXk6IDMuODY4MSA1LjQxNTQ7CiAgICAgIH0KCiAgICAgIC5jbHMtMTQgewogICAgICAgIGZpbGw6ICM0MjUyNmU7CiAgICAgIH0KCiAgICAgIC5jbHMtMTUgewogICAgICAgIGZpbGw6ICMzNDQ1NjM7CiAgICAgIH0KCiAgICAgIC5jbHMtMTYgewogICAgICAgIGZpbGw6ICM1MDVmNzk7CiAgICAgIH0KICAgIDwvc3R5bGU+CiAgPC9kZWZzPgogIDx0aXRsZT5JbnRlZ3JhdGlvbnM8L3RpdGxlPgogIDxnIGNsYXNzPSJjbHMtMSI+CiAgICA8ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIj4KICAgICAgPGcgaWQ9Ik9iamVjdHMiPgogICAgICAgIDxnIGNsYXNzPSJjbHMtMiI+CiAgICAgICAgICA8Zz4KICAgICAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iNzUuMjExNCIgeTE9IjE4Ny44NTczIiB4Mj0iNzcuMDI0OCIgeTI9IjE4Ny4xMTA5Ii8+CiAgICAgICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtNCIgeDE9IjgxLjkyMDUiIHkxPSIxODUuMDk1NiIgeDI9IjEzOC4yMjEyIiB5Mj0iMTYxLjkyMDMiLz4KICAgICAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMTQwLjY2OSIgeTE9IjE2MC45MTI2IiB4Mj0iMTQyLjQ4MjQiIHkyPSIxNjAuMTY2MiIvPgogICAgICAgICAgPC9nPgogICAgICAgIDwvZz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTUiIHBvaW50cz0iMTk0LjUyNiAyNi41NTIgMTc2LjkwMSAzOC4yNDEgMTU5LjI3IDI2LjU1MiAxNzYuOTAxIDE0Ljg3IDE5NC41MjYgMjYuNTUyIi8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMTgzLjcxMzUiIHkxPSI0My4yMTg4IiB4Mj0iMTgzLjcxMzUiIHkyPSI5Ny44ODMyIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy03IiBwb2ludHM9IjE3Ni45MDEgMzguMjQxIDE3Ni45MDEgNTguMTY2IDE1OS4yNyA0Ni40NzcgMTU5LjI3IDI2LjU1MiAxNzYuOTAxIDM4LjI0MSIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtOCIgcG9pbnRzPSIxOTQuNTI2IDI2LjU1MiAxOTQuNTI2IDQ2LjQ3NyAxNzYuOTAxIDU4LjE2NiAxNzYuOTAxIDM4LjI0MSAxOTQuNTI2IDI2LjU1MiIvPgogICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtNiIgeDE9IjQ3Ljk0ODgiIHkxPSI0Mi4yMTg4IiB4Mj0iMTU5LjExNzIiIHkyPSI0Mi4yMTg4Ii8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy01IiBwb2ludHM9IjIyMC43NjIgOTkuNzUyIDE2Ny44MTcgMTM0Ljg2NCAxMTQuODU0IDk5Ljc1MiAxNjcuODE3IDY0LjY1NyAyMjAuNzYyIDk5Ljc1MiIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtOSIgcG9pbnRzPSIxNjcuODE3IDEzNC44NjQgMTY3LjgxNyAxOTQuNzE4IDExNC44NTQgMTU5LjYwNiAxMTQuODU0IDk5Ljc1MiAxNjcuODE3IDEzNC44NjQiLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTgiIHBvaW50cz0iMjIwLjc2MiA5OS43NTIgMjIwLjc2MiAxNTkuNjA2IDE2Ny44MTcgMTk0LjcxOCAxNjcuODE3IDEzNC44NjQgMjIwLjc2MiA5OS43NTIiLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTEwIiBwb2ludHM9IjExMC41NDEgMjEuNjA0IDc3Ljk0OSA0My4yMTkgNDUuMzQ1IDIxLjYwNCA3Ny45NDkgMCAxMTAuNTQxIDIxLjYwNCIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtMTEiIHBvaW50cz0iMTEwLjU0MSAyMS42MDQgMTEwLjU0MSA1OC40NDkgNzcuOTQ5IDgwLjA2NCA3Ny45NDkgNDMuMjE5IDExMC41NDEgMjEuNjA0Ii8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy01IiBwb2ludHM9IjE0MS4xOSAxNDguMDczIDE2Ny44MTMgMTMwLjQxNyAxOTQuNDQ0IDE0OC4wNzMgMTY3LjgxMyAxNjUuNzE5IDE0MS4xOSAxNDguMDczIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy05IiBwb2ludHM9IjE2Ny44MTMgMTMwLjQxNyAxNjcuODEzIDEwMC4zMjEgMTk0LjQ0NCAxMTcuOTc2IDE5NC40NDQgMTQ4LjA3MyAxNjcuODEzIDEzMC40MTciLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTgiIHBvaW50cz0iMTQxLjE5IDE0OC4wNzMgMTQxLjE5IDExNy45NzYgMTY3LjgxMyAxMDAuMzIxIDE2Ny44MTMgMTMwLjQxNyAxNDEuMTkgMTQ4LjA3MyIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtMTIiIHBvaW50cz0iNDUuMzQ1IDIxLjYwNCA0NS4zNDUgNDQuOTg0IDU3LjIzMSA1Mi44NjQgNTcuMjMxIDY2LjI5NiA3Ny45NDkgODAuMDY0IDc3Ljk0OSA0My4yMTkgNDUuMzQ1IDIxLjYwNCIvPgogICAgICAgIDxnIGNsYXNzPSJjbHMtMiI+CiAgICAgICAgICA8Zz4KICAgICAgICAgICAgPGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjQuNjQzOCIgeTE9Ijg2Ljk1NDQiIHgyPSIyNi4wMTU3IiB5Mj0iODUuNTUzMSIvPgogICAgICAgICAgICA8bGluZSBjbGFzcz0iY2xzLTEzIiB4MT0iMjkuODA0IiB5MT0iODEuNjgzNCIgeDI9IjYwLjM4MTEiIHkyPSI1MC40NDkyIi8+CiAgICAgICAgICAgIDxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjYyLjI3NTIiIHkxPSI0OC41MTQzIiB4Mj0iNjMuNjQ3IiB5Mj0iNDcuMTEzIi8+CiAgICAgICAgICA8L2c+CiAgICAgICAgPC9nPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtNSIgcG9pbnRzPSIzNS4yNTUgODkuNjQ1IDE3LjczNiAxMDEuNDkyIDAgODkuOTYyIDE3LjUyNSA3OC4xMjEgMzUuMjU1IDg5LjY0NSIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtNyIgcG9pbnRzPSIxNy43MzYgMTAxLjQ5MiAxNy45MTUgMTIxLjQxNiAwLjE3OSAxMDkuODg3IDAgODkuOTYyIDE3LjczNiAxMDEuNDkyIi8+CiAgICAgICAgPGxpbmUgY2xhc3M9ImNscy02IiB4MT0iMjAuNTg0OSIgeTE9IjEwNS41MzA1IiB4Mj0iNjUuODc0OSIgeTI9IjE3MS4zNjgxIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy04IiBwb2ludHM9IjM1LjI1NSA4OS42NDUgMzUuNDM0IDEwOS41NjkgMTcuOTE1IDEyMS40MTYgMTcuNzM2IDEwMS40OTIgMzUuMjU1IDg5LjY0NSIvPgogICAgICAgIDxwb2x5Z29uIGNsYXNzPSJjbHMtMTQiIHBvaW50cz0iOTIuMzk0IDE3My44MTUgNzQuODc1IDE4NS42NjIgNTcuMTM5IDE3NC4xMzIgNzQuNjY0IDE2Mi4yOTEgOTIuMzk0IDE3My44MTUiLz4KICAgICAgICA8cG9seWdvbiBjbGFzcz0iY2xzLTE1IiBwb2ludHM9Ijc0Ljg3NSAxODUuNjYyIDc1LjA1NCAyMDUuNTg2IDU3LjMxOSAxOTQuMDU3IDU3LjEzOSAxNzQuMTMyIDc0Ljg3NSAxODUuNjYyIi8+CiAgICAgICAgPHBvbHlnb24gY2xhc3M9ImNscy0xNiIgcG9pbnRzPSI5Mi4zOTQgMTczLjgxNSA5Mi41NzQgMTkzLjczOSA3NS4wNTQgMjA1LjU4NiA3NC44NzUgMTg1LjY2MiA5Mi4zOTQgMTczLjgxNSIvPgogICAgICA8L2c+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4K' body: >2 - * [Open API Specification](#open-api-specification) * [JSON Schema](#json-schema) * [Condensed Versus Full Objects](#condensed-versus-full-objects) ____ ### Open API Specification Bitbucket uses the [Open API Specification](https://openapis.org) (OAI, formerly known as Swagger) to describe its APIs. Our OAI specification schema is hosted at [https://api.bitbucket.org/swagger.json](https://api.bitbucket.org/swagger.json) and serves as the canonical definition and comprehensive declaration of all available endpoints. The OAI specification makes writing client applications easier by: auto-generating boilerplate code (like data object classes) and dealing with authentication and error handling. You can find a comprehensive set of open tools for the OAI specification at: [https://github.com/swagger-api](https://github.com/swagger-api). ### JSON Schema Bitbucket uses JSON Schema to describe the layout of every type of object consumed or produced by the API. These schemas are collected under the `#definitions` element of our swagger.json file. When an endpoint expects an object as part of a POST or PUT, it also expects the object to validate against the JSON schemas. The same applies to objects returned by an endpoint. ### Condensed Versus Full Objects Most objects in Bitbucket come both in "full" and "partial" representation. The full representation is when all elements are included. This is the layout returned by a resource's `self` location (e.g. `/2.0/repositories/foo/bar`), as well as resource collection endpoints (e.g. `/2.0/repositories`). However, Bitbucket objects often embed other objects. For example, a `repository` object embeds a `user` object for its owner. Likewise, a `pullrequest` object embeds its `repository` object. These related objects are embedded, or inlined, to reduce the "chatter" when clients make frequent followup API calls to collect information on common, related information. Embedded related objects are typically limited in their fields to avoid such object graphs from becoming too deep and noisy. They often exclude their own nested objects in an attempt to strike a balance between performance and utility. An object's embedded or condensed representation tends to be standardized, meaning the fields included is the same set, regardless of where the object was embedded. - anchor: uri-uuid title: URI, UUID, and structures description: URL's, UUID's, errors, and timestamps icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMTc5LjI2IDE3Ny42NSI+PGRlZnM+PHN0eWxlPi5jbHMtMXtmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50KTt9LmNscy0ye2ZpbGw6IzA5MWU0Mjt9LmNscy0xMCwuY2xzLTExLC5jbHMtMywuY2xzLTQsLmNscy05e2ZpbGw6bm9uZTt9LmNscy0ze3N0cm9rZTojOTljMWZmO30uY2xzLTMsLmNscy00e3N0cm9rZS1saW5lY2FwOnJvdW5kO3N0cm9rZS1saW5lam9pbjpyb3VuZDtzdHJva2Utd2lkdGg6MDt9LmNscy0xMiwuY2xzLTQsLmNscy05e3N0cm9rZTojZTVlOGVjO30uY2xzLTV7ZmlsbDojMzQ0NTYzO30uY2xzLTZ7ZmlsbDojZmY4YjAwO30uY2xzLTd7ZmlsbDojZmZjNDAwO30uY2xzLTh7ZmlsbDojMDA2NWZmO30uY2xzLTEwLC5jbHMtMTEsLmNscy0xMiwuY2xzLTEzLC5jbHMtOXtzdHJva2UtbWl0ZXJsaW1pdDoxMDtzdHJva2Utd2lkdGg6MnB4O30uY2xzLTEwe3N0cm9rZTojZmZhYjAwO30uY2xzLTExLC5jbHMtMTN7c3Ryb2tlOiMwMDY1ZmY7fS5jbHMtMTJ7ZmlsbDojOTljMWZmO30uY2xzLTEze2ZpbGw6I2U1ZThlYzt9PC9zdHlsZT48bGluZWFyR3JhZGllbnQgaWQ9ImxpbmVhci1ncmFkaWVudCIgeDE9IjAuNCIgeTE9IjE3OC4wNSIgeDI9IjE3OC44NSIgeTI9Ii0wLjQiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiMwOTFlNDIiLz48c3RvcCBvZmZzZXQ9IjAuMDciIHN0b3AtY29sb3I9IiMwZDIyNDUiLz48c3RvcCBvZmZzZXQ9IjAuNDkiIHN0b3AtY29sb3I9IiMxZjMyNTMiLz48c3RvcCBvZmZzZXQ9IjAuNzkiIHN0b3AtY29sb3I9IiMyNTM4NTgiLz48L2xpbmVhckdyYWRpZW50PjwvZGVmcz48dGl0bGU+Q29kZTwvdGl0bGU+PGcgaWQ9IkxheWVyXzIiIGRhdGEtbmFtZT0iTGF5ZXIgMiI+PGcgaWQ9IlNvZnR3YXJlIj48cmVjdCBpZD0iX1JlY3RhbmdsZV8iIGRhdGEtbmFtZT0iJmx0O1JlY3RhbmdsZSZndDsiIGNsYXNzPSJjbHMtMSIgd2lkdGg9IjE3OS4yNiIgaGVpZ2h0PSIxNzcuNjUiLz48cGF0aCBjbGFzcz0iY2xzLTIiIGQ9Ik0xNzkuMjYsMjYuNjRIMFY3MS43NUExNjYuNDEsMTY2LjQxLDAsMCwwLDYzLjI0LDU5LjUxYTE4OC40MSwxODguNDEsMCwwLDAsMTcuMzktOC4zNmMxOC40NC05LjQzLDQ4LjM3LTE3LjksOTguNjItMTNabS0xNTkuNDQsMzRoMFptMC0xNC4wOGgwWiIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjE5LjgxIiB5MT0iNDYuNTgiIHgyPSIyNS4wNyIgeTI9IjQ2LjU4Ii8+PGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjUuMDciIHkxPSI2MC42NiIgeDI9IjE5LjgxIiB5Mj0iNjAuNjYiLz48bGluZSBjbGFzcz0iY2xzLTMiIHgxPSIxOS44MSIgeTE9Ijc0Ljc0IiB4Mj0iMjUuMDciIHkyPSI3NC43NCIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjI1LjA3IiB5MT0iODguODIiIHgyPSIxOS44MSIgeTI9Ijg4LjgyIi8+PGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjUuMDciIHkxPSIxMDIuODkiIHgyPSIxOS44MSIgeTI9IjEwMi44OSIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjI1LjA3IiB5MT0iMTE2Ljk3IiB4Mj0iMTkuODEiIHkyPSIxMTYuOTciLz48bGluZSBjbGFzcz0iY2xzLTMiIHgxPSIyNS4wNyIgeTE9IjEzMS4wNSIgeDI9IjE5LjgxIiB5Mj0iMTMxLjA1Ii8+PGxpbmUgY2xhc3M9ImNscy0zIiB4MT0iMjUuMDciIHkxPSIxNDUuMTMiIHgyPSIxOS44MSIgeTI9IjE0NS4xMyIvPjxsaW5lIGNsYXNzPSJjbHMtMyIgeDE9IjI1LjA3IiB5MT0iMTU5LjIxIiB4Mj0iMTkuODEiIHkyPSIxNTkuMjEiLz48bGluZSBjbGFzcz0iY2xzLTQiIHgxPSI1NS44OSIgeTE9IjEzMS4wNSIgeDI9IjkzLjk5IiB5Mj0iMTMxLjA1Ii8+PGxpbmUgY2xhc3M9ImNscy00IiB4MT0iNTUuODkiIHkxPSIxNDUuMTMiIHgyPSIxMzkuNjciIHkyPSIxNDUuMTMiLz48cmVjdCBjbGFzcz0iY2xzLTUiIHdpZHRoPSIxNzkuMjYiIGhlaWdodD0iMjYuNjQiLz48Y2lyY2xlIGNsYXNzPSJjbHMtNiIgY3g9IjEzLjUiIGN5PSIxMi4wOCIgcj0iNS4xMSIvPjxjaXJjbGUgY2xhc3M9ImNscy03IiBjeD0iMzAuMTgiIGN5PSIxMi4wOCIgcj0iNS4xMSIvPjxjaXJjbGUgY2xhc3M9ImNscy04IiBjeD0iNDYuODYiIGN5PSIxMi4wOCIgcj0iNS4xMSIvPjxwYXRoIGNsYXNzPSJjbHMtOSIgZD0iTTc1LjQxLDg4LjgyIi8+PHBhdGggY2xhc3M9ImNscy05IiBkPSJNMzIuODksODguODIiLz48bGluZSBjbGFzcz0iY2xzLTEwIiB4MT0iMzIuODkiIHkxPSI3NC43NCIgeDI9Ijc1LjQxIiB5Mj0iNzQuNzQiLz48bGluZSBjbGFzcz0iY2xzLTExIiB4MT0iMzIuODkiIHkxPSI2MC42NiIgeDI9Ijc1LjQxIiB5Mj0iNjAuNjYiLz48bGluZSBjbGFzcz0iY2xzLTkiIHgxPSIzMi44OSIgeTE9IjQ2LjU4IiB4Mj0iNTUuODkiIHkyPSI0Ni41OCIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjQ2LjU4IiB4Mj0iMjUuMDciIHkyPSI0Ni41OCIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjYwLjY2IiB4Mj0iMjUuMDciIHkyPSI2MC42NiIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9Ijc0Ljc0IiB4Mj0iMjUuMDciIHkyPSI3NC43NCIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9Ijg4LjgyIiB4Mj0iMjUuMDciIHkyPSI4OC44MiIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjEwMi44OSIgeDI9IjI1LjA3IiB5Mj0iMTAyLjg5Ii8+PGxpbmUgY2xhc3M9ImNscy0xMiIgeDE9IjE5LjgxIiB5MT0iMTE2Ljk3IiB4Mj0iMjUuMDciIHkyPSIxMTYuOTciLz48bGluZSBjbGFzcz0iY2xzLTEyIiB4MT0iMTkuODEiIHkxPSIxMzEuMDUiIHgyPSIyNS4wNyIgeTI9IjEzMS4wNSIvPjxsaW5lIGNsYXNzPSJjbHMtMTIiIHgxPSIxOS44MSIgeTE9IjE0NS4xMyIgeDI9IjI1LjA3IiB5Mj0iMTQ1LjEzIi8+PGxpbmUgY2xhc3M9ImNscy0xMiIgeDE9IjE5LjgxIiB5MT0iMTU5LjIxIiB4Mj0iMjUuMDciIHkyPSIxNTkuMjEiLz48bGluZSBpZD0iX0xpbmVfIiBkYXRhLW5hbWU9IiZsdDtMaW5lJmd0OyIgY2xhc3M9ImNscy0xMCIgeDE9Ijg0LjI0IiB5MT0iMTE2Ljk3IiB4Mj0iMTU2LjY1IiB5Mj0iMTE2Ljk3Ii8+PHBhdGggY2xhc3M9ImNscy05IiBkPSJNMzIuODksMTE3aDBaIi8+PGxpbmUgY2xhc3M9ImNscy0xMCIgeDE9IjEwMiIgeTE9IjEzMS4wNSIgeDI9IjE2My42MiIgeTI9IjEzMS4wNSIvPjxsaW5lIGNsYXNzPSJjbHMtMTMiIHgxPSI1NS44OSIgeTE9IjEzMS4wNSIgeDI9IjkzLjk5IiB5Mj0iMTMxLjA1Ii8+PGxpbmUgY2xhc3M9ImNscy0xMyIgeDE9IjU1Ljg5IiB5MT0iMTQ1LjEzIiB4Mj0iMTM5LjY3IiB5Mj0iMTQ1LjEzIi8+PGxpbmUgY2xhc3M9ImNscy05IiB4MT0iNzguOSIgeTE9IjE1OS4yMSIgeDI9IjExMy41MSIgeTI9IjE1OS4yMSIvPjxsaW5lIGNsYXNzPSJjbHMtOSIgeDE9IjU5LjYxIiB5MT0iODguODIiIHgyPSI5OS4zMyIgeTI9Ijg4LjgyIi8+PGxpbmUgY2xhc3M9ImNscy05IiB4MT0iNTkuNjEiIHkxPSIxMDIuODkiIHgyPSI5OS4zMyIgeTI9IjEwMi44OSIvPjxjaXJjbGUgY2xhc3M9ImNscy02IiBjeD0iMTMuNSIgY3k9IjEyLjA4IiByPSI1LjExIi8+PGNpcmNsZSBjbGFzcz0iY2xzLTciIGN4PSIzMC4xOCIgY3k9IjEyLjA4IiByPSI1LjExIi8+PGNpcmNsZSBjbGFzcz0iY2xzLTgiIGN4PSI0Ni44NiIgY3k9IjEyLjA4IiByPSI1LjExIi8+PC9nPjwvZz48L3N2Zz4=' body: >2 You should be familiar with REST architecture before writing an integration. Read this overview page to gain a good understanding of Bitbucket's REST implementation. - * [URI structure](#uri-structure) * [HTTP methods](#http-methods) * [UUID](#universally-unique-identifier) * [User object and UUID](#user-object-and-uuid) * [Repository object and UUID](#repository-object-and-uuid) * [Team object and UUID](#team-object-and-uuid) * [Standard error responses](#standardized-error-responses) * [Standard ISO-8601 timestamps](#standard-iso-8601-timestamps) - ### URI structure All Bitbucket Cloud requests start with the `https://api.bitbucket.org/2.0` prefix (for the 2.0 API) and `https://api.bitbucket.org/1.0` prefix (1.0 API). The next segment of the URI path depends on the endpoint of the request. For example, using the curl command and the repositories endpoint you can list all the issues on Bitbucket's tutorial repository: ``` curl https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org ``` Given a specific endpoint, you can then drill down to a particular aspect or resource of that endpoint. The issues resource on a repository is an example: ``` curl https://api.bitbucket.org/1.0/repositories/tutorials/tutorials.bitbucket.org/issues ``` #### HTTP methods A given endpoint or resource has a series of actions (or methods) associated with it. The Bitbucket service supports these standard HTTP methods: | Call | Description | ||-| | GET | Retrieves information. | | PUT | Updates existing information. | | POST | Creates new information. | | DELETE | Removes existing information. | For example, you can call use the POST action on the issues resource and create an issue on the issue tracker. **Specifying content length** You can get a `411 Length Required` response. If this happens, the API requires a Content-Length header but the client is not sending it. You should add the header yourself, for example using the curl client: ``` curl -r PUT --header "Content-Length: 0" -u user:app_password https://api.bitbucket.org/1.0/emails/rap@atlassian.com ``` ### Universally Unique Identifier UUID's provide a single point of recognition for users, teams, and repositories. The UUID is distinct from the username, team name, and repository name fields and remains the same even when those fields change. For example when a user changes their username or moves a repository you will need to modify calls which use those identifiers but not if you are pointing to the UUID. #### UUID examples and structure UUID's work with both the 1.0 and 2.0 APIs for the user, team, and repository objects. The following examples the following characters are replacements for curly brackets: `%7B` replaces `{` and `%7D` replaces `}`. You will see this structure in the following example sections. #### User object and UUID When you make a call using either the username or the UUID for that user the response is the same. **Call with username**: ``` curl https://api.bitbucket.org/2.0/users/tutorials ``` ***Call with UUID for the user**: ``` curl https://api.bitbucket.org/2.0/users/%7Bc788b2da-b7a2-404c-9e26-d3f077557007%7D ``` **Response** ```JSON { "username": "tutorials", "nickname": "tutorials", "account_status": "active", "website": "https://tutorials.bitbucket.org/", "display_name": "tutorials account", "uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}", "links": { "self": { "href": "https://api.bitbucket.org/2.0/users/tutorials" }, "repositories": { "href": "https://api.bitbucket.org/2.0/repositories/tutorials" }, "html": { "href": "https://bitbucket.org/tutorials" }, "followers": { "href": "https://api.bitbucket.org/2.0/users/tutorials/followers" }, "avatar": { "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png" }, "following": { "href": "https://api.bitbucket.org/2.0/users/tutorials/following" } }, "created_on": "2011-12-20T16:34:07.132459+00:00", "location": "Santa Monica, CA", "type": "user" } ``` #### Repository object and UUID Once you have the UUID for a repository you no longer need a username or team name to make the API call so long as you use an empty field. This helps you resolve repositories no matter if the username or team name changes. **Call with team name (1team) and repository name (moxie)**: ``` curl https://api.bitbucket.org/2.0/repositories/1team/moxie ``` **Call with UUID and empty field**: ``` curl https://api.bitbucket.org/2.0/repositories/%7B%7D/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D ``` **Call with UUID and teamname**: ``` curl https://api.bitbucket.org/2.0/repositories/1team/%7B21fa9bf8-b5b2-4891-97ed-d590bad0f871%7D ``` **Response** ```JSON { "created_on": "2013-11-08T01:11:03.222520+00:00", "description": "", "fork_policy": "allow_forks", "full_name": "1team/moxie", "has_issues": false, "has_wiki": false, "is_private": false, "language": "", "links": { "avatar": { "href": "https://bitbucket.org/1team/moxie/avatar/32/" }, "branches": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/refs/branches" }, "clone": [ { "href": "https://bitbucket.org/1team/moxie.git", "name": "https" }, { "href": "ssh://git@bitbucket.org/1team/moxie.git", "name": "ssh" } ], "commits": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/commits" }, "downloads": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/downloads" }, "forks": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/forks" }, "hooks": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/hooks" }, "html": { "href": "https://bitbucket.org/1team/moxie" }, "pullrequests": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/pullrequests" }, "self": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie" }, "tags": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/refs/tags" }, "watchers": { "href": "https://api.bitbucket.org/2.0/repositories/1team/moxie/watchers" } }, "name": "moxie", "owner": { "display_name": "the team", "links": { "avatar": { "href": "https://bitbucket.org/account/1team/avatar/32/" }, "html": { "href": "https://bitbucket.org/1team/" }, "self": { "href": "https://api.bitbucket.org/2.0/teams/1team" } }, "type": "team", "username": "1team", "uuid": "{aa559944-83c9-4963-a9a8-69ac8d9cf5d2}" }, "project": { "key": "PROJ", "links": { "avatar": { "href": "https://bitbucket.org/account/user/1team/projects/PROJ/avatar/32" }, "html": { "href": "https://bitbucket.org/account/user/1team/projects/PROJ" } }, "name": "Untitled project", "type": "project", "uuid": "{ab52aaeb-16ad-4fb0-bb1d-47e4f00367ff}" }, "scm": "git", "size": 33348, "type": "repository", "updated_on": "2013-11-08T01:11:03.263237+00:00", "uuid": "{21fa9bf8-b5b2-4891-97ed-d590bad0f871}", "website": "" } ``` #### Team object and UUID This example shows a call for a list of team members using both the team name and with the UUID for the team object. As the call is unauthenticated in the following example the response object will only show members with public profiles. The response is the same in either case. **Call with teamname** ``` curl https://api.bitbucket.org/2.0/teams/1team/members ``` **Call with UUID for team object** ``` curl https://api.bitbucket.org/2.0/teams/%7Baa559944-83c9-4963-a9a8-69ac8d9cf5d2%7D/members ``` **Response** ```JSON { "page": 1, "pagelen": 50, "size": 2, "values": [ { "created_on": "2011-12-20T16:34:07.132459+00:00", "display_name": "tutorials account", "links": { "avatar": { "href": "https://bitbucket.org/account/tutorials/avatar/32/" }, "followers": { "href": "https://api.bitbucket.org/2.0/users/tutorials/followers" }, "following": { "href": "https://api.bitbucket.org/2.0/users/tutorials/following" }, "hooks": { "href": "https://api.bitbucket.org/2.0/users/tutorials/hooks" }, "html": { "href": "https://bitbucket.org/tutorials/" }, "repositories": { "href": "https://api.bitbucket.org/2.0/repositories/tutorials" }, "self": { "href": "https://api.bitbucket.org/2.0/users/tutorials" }, "snippets": { "href": "https://api.bitbucket.org/2.0/snippets/tutorials" } }, "location": null, "type": "user", "username": "tutorials", "nickname": "tutorials", "account_status": "active", "uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}", "website": "https://tutorials.bitbucket.org/" }, { "created_on": "2013-12-10T14:44:13+00:00", "display_name": "Dan Stevens [Atlassian]", "links": { "avatar": { "href": "https://bitbucket.org/account/dans9190/avatar/32/" }, "followers": { "href": "https://api.bitbucket.org/2.0/users/dans9190/followers" }, "following": { "href": "https://api.bitbucket.org/2.0/users/dans9190/following" }, "hooks": { "href": "https://api.bitbucket.org/2.0/users/dans9190/hooks" }, "html": { "href": "https://bitbucket.org/dans9190/" }, "repositories": { "href": "https://api.bitbucket.org/2.0/repositories/dans9190" }, "self": { "href": "https://api.bitbucket.org/2.0/users/dans9190" }, "snippets": { "href": "https://api.bitbucket.org/2.0/snippets/dans9190" } }, "location": null, "type": "user", "username": "dans9190", "nickname": "dans9190", "account_status": "active", "uuid": "{1cd06601-cd0e-4fce-be03-e9ac226978b7}", "website": "" } ] } ``` ### Standardized error responses The 2.0 API standardizes the error response layout. The 2.0 API serves a JSON object along with the appropriate HTTP status code. The JSON object provides a detailed problem description. ```json { "type": "error", "error": { "message": "Bad request", "fields": { "src": [ "This field is required." ] }, "detail": "You must specify a valid source branch when creating a pull request.", "id": "d23a1cc5178f7637f3d9bf2d13824258", "data": { "extra": "Optional, endpoint-specific data to further augment the error." } } } ``` This object contains an error element which contains the following nested elements: | Element | Description | ||-| | message | A short description of the problem. This element is always present. Its value may be localized. | | fields | This optional element is used in response to POST or PUT operations in which clients have provided invalid input. It contains a list of one or more client-provided fields that failed validation. The values may be localized. | | detail | An optional detailed explanation of the failure. Its value may be localized. | id | An optional unique error identifier that identifies the error in Bitbucket's logging system. If you feel you hit a bug in an API and this field is provided, please mention it if you decide to contact support as it will greatly help us narrow down the problem. | ### Standard ISO-8601 timestamps All 2.0 APIs use standardized ISO-8601 timestamps. In most cases, our APIs return UTC timestamps and for these, the timezone offset part will be 00:00. In rare cases where the original localized timestamp has significance, the timezone offset may identify the event's original timezone. - anchor: cors-hypermedia title: Cors and hypermedia description: Learn about resources and linking icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMjM2LjYgMjE4LjQzIj48ZGVmcz48c3R5bGU+LmNscy0xe2lzb2xhdGlvbjppc29sYXRlO30uY2xzLTIsLmNscy0zLC5jbHMtNHtmaWxsOm5vbmU7c3Ryb2tlLWxpbmVjYXA6cm91bmQ7c3Ryb2tlLW1pdGVybGltaXQ6MTA7c3Ryb2tlLXdpZHRoOjExcHg7fS5jbHMtMntzdHJva2U6dXJsKCNsaW5lYXItZ3JhZGllbnQpO30uY2xzLTN7c3Ryb2tlOnVybCgjTmV3X0dyYWRpZW50X1N3YXRjaF8xNCk7fS5jbHMtNHtzdHJva2U6dXJsKCNOZXdfR3JhZGllbnRfU3dhdGNoXzEpO30uY2xzLTV7ZmlsbDojNDI1MjZlO30uY2xzLTZ7ZmlsbDojZmY1NjMwO30uY2xzLTEwLC5jbHMtNywuY2xzLTh7bWl4LWJsZW5kLW1vZGU6bXVsdGlwbHk7fS5jbHMtN3tmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTIpO30uY2xzLTh7ZmlsbDp1cmwoI2xpbmVhci1ncmFkaWVudC0zKTt9LmNscy05e2ZpbGw6IzAwNjVmZjt9LmNscy0xMHtmaWxsOnVybCgjbGluZWFyLWdyYWRpZW50LTQpO308L3N0eWxlPjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50IiB5MT0iMTY3Ljg3IiB4Mj0iMTkxLjU2IiB5Mj0iMTY3Ljg3IiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+PHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjNTA1Zjc5Ii8+PHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjMzQ0NTYzIi8+PC9saW5lYXJHcmFkaWVudD48bGluZWFyR3JhZGllbnQgaWQ9Ik5ld19HcmFkaWVudF9Td2F0Y2hfMTQiIHgxPSIxMTIuODMiIHkxPSIxMzEuNzIiIHgyPSIyMzYuNiIgeTI9IjEzMS43MiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzAwNTJjYyIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzI2ODRmZiIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJOZXdfR3JhZGllbnRfU3dhdGNoXzEiIHgxPSI0NS4wNiIgeTE9Ijg2LjY5IiB4Mj0iMTY4Ljg4IiB5Mj0iODYuNjkiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNkZTM1MGIiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNmZjc0NTIiLz48L2xpbmVhckdyYWRpZW50PjxsaW5lYXJHcmFkaWVudCBpZD0ibGluZWFyLWdyYWRpZW50LTIiIHgxPSIzNDQ3LjkzIiB5MT0iLTkxOC43OSIgeDI9IjM0NTEuNCIgeTI9Ii0xMDMyLjc2IiBncmFkaWVudFRyYW5zZm9ybT0idHJhbnNsYXRlKC01NzIuMzggMzcwNC4yOSkgcm90YXRlKC02NC4zNCkiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAuMzEiIHN0b3AtY29sb3I9IiNjMWM3ZDAiIHN0b3Atb3BhY2l0eT0iMCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iI2MxYzdkMCIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQtMyIgeDE9IjM1MDYuNiIgeTE9Ii03OTYuNjYiIHgyPSIzNTEwLjA3IiB5Mj0iLTkxMC42MyIgeGxpbms6aHJlZj0iI2xpbmVhci1ncmFkaWVudC0yIi8+PGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQtNCIgeDE9IjM1ODEuNjgiIHkxPSItOTA2LjgyIiB4Mj0iMzU4NS4xNiIgeTI9Ii0xMDIwLjc5IiB4bGluazpocmVmPSIjbGluZWFyLWdyYWRpZW50LTIiLz48L2RlZnM+PHRpdGxlPldlYmhvb2tzPC90aXRsZT48ZyBjbGFzcz0iY2xzLTEiPjxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPjxnIGlkPSJTb2Z0d2FyZSI+PHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMTg2LjA2LDE2Ny44N0gxMTcuNzJBMjcuNTgsMjcuNTgsMCwwLDAsOTIuMjQsMTg1YTQ1LjA2LDQ1LjA2LDAsMSwxLTQxLjY4LTYyLjE5Ii8+PHBhdGggY2xhc3M9ImNscy0zIiBkPSJNMTE4LjMzLDUwLjUybDM0LjE1LDU5LjE4YTI3LjU5LDI3LjU5LDAsMCwwLDI3LjU4LDEzLjUxLDQ1LjA2LDQ1LjA2LDAsMSwxLTMzLDY3LjE5Ii8+PHBhdGggY2xhc3M9ImNscy00IiBkPSJNNTAuNTYsMTY3Ljg3bDM0LjE4LTU5LjE2YTI3LjU5LDI3LjU5LDAsMCwwLTIuMDktMzAuNjQsNDUuMDYsNDUuMDYsMCwxLDEsNzQuNy01Ii8+PHBhdGggY2xhc3M9ImNscy01IiBkPSJNMTg2LjA2LDE5OS42NmEzMS43OSwzMS43OSwwLDEsMSwzMS43OS0zMS43OUEzMS44MiwzMS44MiwwLDAsMSwxODYuMDYsMTk5LjY2WiIvPjxnIGlkPSJfR3JvdXBfIiBkYXRhLW5hbWU9IiZsdDtHcm91cCZndDsiPjxwYXRoIGNsYXNzPSJjbHMtNiIgZD0iTTQ5LjU2LDE5OS42NGEzMS43OSwzMS43OSwwLDEsMSwzMi43Ny0zMC43N0EzMS44MiwzMS44MiwwLDAsMSw0OS41NiwxOTkuNjRaIi8+PC9nPjxwYXRoIGNsYXNzPSJjbHMtNyIgZD0iTTU0LjEyLDE4MC4zNmE1OC45LDU4LjksMCwwLDAtMS41OS0xMS4yN3MtMi4zNS05LjQ0LTcuMzMtMTYuODNhNDMuODksNDMuODksMCwwLDAtMTEuNzMtMTEuMTcsMzEuNzcsMzEuNzcsMCwwLDAsMjkuMjgsNTYuMTNDNTguMjksMTkyLjQ0LDU0LjY4LDE4Ni45LDU0LjEyLDE4MC4zNloiLz48cGF0aCBjbGFzcz0iY2xzLTgiIGQ9Ik0xODkuNjIsMTgwLjM2QTU4LjksNTguOSwwLDAsMCwxODgsMTY5LjA4cy0yLjM1LTkuNDQtNy4zMy0xNi44M0E0My44OSw0My44OSwwLDAsMCwxNjksMTQxLjA4YTMxLjc3LDMxLjc3LDAsMCwwLDI5LjI4LDU2LjEzQzE5My43OSwxOTIuNDQsMTkwLjE4LDE4Ni45LDE4OS42MiwxODAuMzZaIi8+PGcgaWQ9Il9Hcm91cF8yIiBkYXRhLW5hbWU9IiZsdDtHcm91cCZndDsiPjxwYXRoIGNsYXNzPSJjbHMtOSIgZD0iTTg5LjksMzMuNzhhMzIuNDYsMzIuNDYsMCwxLDEsMTEuODgsNDQuMzRBMzIuNDksMzIuNDksMCwwLDEsODkuOSwzMy43OFoiLz48L2c+PHBhdGggY2xhc3M9ImNscy0xMCIgZD0iTTEyMi4yMyw2Ni4xM2E1OC45LDU4LjksMCwwLDAtMS41OS0xMS4yN3MtMi4zNS05LjQ0LTcuMzMtMTYuODNjLTMuMzctNS05LjA2LTkuNzktMTUuNDMtMTMuNDhBMzIuNDQsMzIuNDQsMCwwLDAsMTI4Ljc3LDgwLjZDMTI1LjMxLDc2LjM5LDEyMi43LDcxLjYxLDEyMi4yMyw2Ni4xM1oiLz48L2c+PC9nPjwvZz48L3N2Zz4=' body: >2 This section describes [Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) (CORS), what content types we support in requests and responses, and hyperlinking resources in each json responses. - * [CORS](#cors) * [Supported content types](#supported-content-types) * [Resource links](#resource-links) - ### Cors The Bitbucket API supports Cross-origin resource sharing to allow requests for restricted resources across domains. For more information you can refer to: * [Wikipedia article on CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) * [W3C CORS recommendation](https://www.w3.org/TR/cors/) Sending a general request from the api to bitbucket.com: `curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com"` Gives this result: HTTP/1.1 302 FOUND Server: nginx/1.6.2 Vary: Cookie Cache-Control: max-age=900 Content-Type: text/html; charset=utf-8 Strict-Transport-Security: max-age=31536000 Date: Tue, 21 Jun 2016 17:54:37 GMT Location: http://confluence.atlassian.com/x/IYBGDQ X-Served-By: app-110 X-Static-Version: 2c820eb0d2b3 ETag: "d41d8cd98f00b204e9800998ecf8427e" X-Content-Type-Options: nosniff X-Render-Time: 0.00379920005798 Connection: Keep-Alive X-Version: 2c820eb0d2b3 X-Frame-Options: SAMEORIGIN X-Request-Count: 383 X-Cache-Info: cached Content-Length: 0 Sending the same request with the CORS check -X OPTIONS in the call: `curl -i https://api.bitbucket.org -H "origin: http://bitbucket.com" -X OPTIONS` Gives this result: HTTP/1.1 302 FOUND Server: nginx/1.6.2 Vary: Cookie Cache-Control: max-age=900 Content-Type: text/html; charset=utf-8 Access-Control-Expose-Headers: Accept-Ranges, Content-Encoding, Content-Length, Content-Type, ETag, Last-Modified Strict-Transport-Security: max-age=31536000 Date: Tue, 21 Jun 2016 18:04:30 GMT Access-Control-Max-Age: 86400 Location: http://confluence.atlassian.com/x/IYBGDQ X-Served-By: app-111 Access-Control-Allow-Origin: * X-Static-Version: 2c820eb0d2b3 ETag: "d41d8cd98f00b204e9800998ecf8427e" X-Content-Type-Options: nosniff X-Render-Time: 0.00371098518372 Connection: keep-alive X-Version: 2c820eb0d2b3 X-Frame-Options: SAMEORIGIN X-Request-Count: 357 Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE, OPTIONS Access-Control-Allow-Headers: Accept, Authorization, Content-Type, If-Match, If-Modified-Since, If-None-Match, If-Unmodified-Since, Origin, Range, X-CsrftokenX-Requested-With X-Cache-Info: not cacheable; request wasn't a GET or HEAD Content-Length: 0 ### Supported content types The default and primary content type for 2.0 APIs is JSON. This applies both to responses from the server and to the request bodies provided by the client. Unless documented otherwise, whenever creating a new (POST) or modifying an existing (PUT) object, your client must provide the object's normal representation. Not every object element can be mutated. For example, a repository's created_on date is an auto-generated, immutable field. Your client can omit immutable fields from a request body. In some cases, a resource might also accept regular application/x-www-url-form-encoded POST and PUT bodies. Such bodies can be more convenient in scripts and command line usage. Requests bodies can contain contain nested elements or they can be flat (without nested elements). Clients can send flat request bodies as either as application/json or as application/x-www-url-form-encoded. Nested objects always require JSON. ### Resource links Every 2.0 object contains a links element that points to related resources or alternate representations. Use links to quickly discover and traverse to related objects. Links serve a "self-documenting" function for each endpoint. For example, the following request for a specific user: `$ curl https://api.bitbucket.org/2.0/users/tutorials` ```json { "username": "tutorials", "nickname": "tutorials", "account_status": "active", "website": "https://tutorials.bitbucket.org/", "display_name": "tutorials account", "uuid": "{c788b2da-b7a2-404c-9e26-d3f077557007}", "links": { "self": { "href": "https://api.bitbucket.org/2.0/users/tutorials" }, "repositories": { "href": "https://api.bitbucket.org/2.0/repositories/tutorials" }, "html": { "href": "https://bitbucket.org/tutorials" }, "followers": { "href": "https://api.bitbucket.org/2.0/users/tutorials/followers" }, "avatar": { "href": "https://bitbucket-assetroot.s3.amazonaws.com/c/photos/2013/Nov/25/tutorials-avatar-1563784409-6_avatar.png" }, "following": { "href": "https://api.bitbucket.org/2.0/users/tutorials/following" } }, "created_on": "2011-12-20T16:34:07.132459+00:00", "location": "Santa Monica, CA", "type": "user" } ``` Links can be actual REST API resources or they can be informational. In this example, informative resources include the user's avatar and the HTML URL for the user's Bitbucket account. Your client should avoid hardcoding an API's URL and instead use the URLs returned in API responses. A link's key is its `rel` (relationship) attribute and it contains a mandatory href element. For example, the following link: ```json "self": { "href": "https://api.bitbucket.org/api/2.0/users/tutorials" } ``` The rel for this link is self and the href is https://api.bitbucket.org/api/2.0/users/tutorials. A single rel key can contain an list (array) of href objects. Your client should anticipate that any rel key can contain one or more href objects. Finally, links can also contain optional elements. Two common optional elements are the name element and the title element. They are often used to disambiguate links that share the same rel key. In the example below, the repository object that contains a clone link with two href objects. Each object contains the optional name element to clarify its use. ```json "links": { "self": { "href": "https://api.bitbucket.org/2.0/repositories/evzijst/bitbucket" }, "clone": [ { "href": "https://api.bitbucket.org/evzijst/bitbucket.git", "name": "https" }, { "href": "ssh://git@bitbucket.org/erik/bitbucket.git", "name": "ssh" } ], ... } ``` Links can support [URI Templates](https://tools.ietf.org/html/rfc6570); Those that do contain a `"templated": "true"` element. - anchor: bb-connect title: Atlassian Connect description: Build Bitbucket add-ons with Connect icon: >- data:image/svg+xml;base64,b'PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHhtbG5zOnhsaW5rPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5L3hsaW5rIiB2aWV3Qm94PSIwIDAgMjU3LjMxNjMgMTYyLjU5OTQiPgogIDxkZWZzPgogICAgPHN0eWxlPgogICAgICAuY2xzLTEgewogICAgICAgIGlzb2xhdGlvbjogaXNvbGF0ZTsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBmaWxsOiAjMzQ0NTYzOwogICAgICB9CgogICAgICAuY2xzLTMgewogICAgICAgIGZpbGw6ICMxZGI5ZDQ7CiAgICAgIH0KCiAgICAgIC5jbHMtNCB7CiAgICAgICAgZmlsbDogIzAwNTdkODsKICAgICAgfQoKICAgICAgLmNscy01LCAuY2xzLTcsIC5jbHMtOSB7CiAgICAgICAgbWl4LWJsZW5kLW1vZGU6IG11bHRpcGx5OwogICAgICB9CgogICAgICAuY2xzLTUgewogICAgICAgIGZpbGw6IHVybCgjTjc1KTsKICAgICAgfQoKICAgICAgLmNscy02IHsKICAgICAgICBmaWxsOiAjMDA2NWZmOwogICAgICB9CgogICAgICAuY2xzLTcgewogICAgICAgIGZpbGw6IHVybCgjTjc1LTIpOwogICAgICB9CgogICAgICAuY2xzLTggewogICAgICAgIGZpbGw6IHVybCgjbGluZWFyLWdyYWRpZW50KTsKICAgICAgfQoKICAgICAgLmNscy05IHsKICAgICAgICBmaWxsOiB1cmwoI043NS0zKTsKICAgICAgfQoKICAgICAgLmNscy0xMCB7CiAgICAgICAgZmlsbDogdXJsKCNUMjAwLVQ3NSk7CiAgICAgIH0KICAgIDwvc3R5bGU+CiAgICA8bGluZWFyR3JhZGllbnQgaWQ9Ik43NSIgeDE9Ii0yMTg5LjU1NiIgeTE9IjI4MDguMjI4NCIgeDI9Ii0yMDkxLjE1NTEiIHkyPSIyODA4LjIyODQiIGdyYWRpZW50VHJhbnNmb3JtPSJtYXRyaXgoMC4xNjgxLCAwLjk4NTgsIDAuOTg1OCwgLTAuMTY4MSwgLTIzNzMuNzM2LCAyNzIyLjEyNzgpIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSI+CiAgICAgIDxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iI2U1ZThlYyIvPgogICAgICA8c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNlNWU4ZWMiIHN0b3Atb3BhY2l0eT0iMC4xIi8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJONzUtMiIgZGF0YS1uYW1lPSJONzUiIHgxPSItMjE2OC41OTQ3IiB5MT0iMjkzNS4wNTU2IiB4Mj0iLTIwNzAuMTkzNyIgeTI9IjI5MzUuMDU1NiIgeGxpbms6aHJlZj0iI043NSIvPgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJsaW5lYXItZ3JhZGllbnQiIHgxPSIxOTAuMzU0NyIgeTE9IjE1OS45NjciIHgyPSIyNTkuOTQ4NyIgeTI9IjkwLjM3MyIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiPgogICAgICA8c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiMzNDQ1NjMiLz4KICAgICAgPHN0b3Agb2Zmc2V0PSIxIiBzdG9wLWNvbG9yPSIjNWU2Yzg0Ii8+CiAgICA8L2xpbmVhckdyYWRpZW50PgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJONzUtMyIgZGF0YS1uYW1lPSJONzUiIHgxPSItMjI1Ny4zOTc3IiB5MT0iMjg4NC4yMjYzIiB4Mj0iLTIxNTguOTk2NyIgeTI9IjI4ODQuMjI2MyIgeGxpbms6aHJlZj0iI043NSIvPgogICAgPGxpbmVhckdyYWRpZW50IGlkPSJUMjAwLVQ3NSIgeDE9IjEyNi4wMjU3IiB5MT0iODUuMTA4IiB4Mj0iMTk1LjYxOTciIHkyPSIxNS41MTQiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj4KICAgICAgPHN0b3Agb2Zmc2V0PSIwIiBzdG9wLWNvbG9yPSIjM2RjN2RjIi8+CiAgICAgIDxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzljZTNlZSIvPgogICAgPC9saW5lYXJHcmFkaWVudD4KICA8L2RlZnM+CiAgPHRpdGxlPkFkZCBPbiBCbG9ja3MgMjwvdGl0bGU+CiAgPGcgY2xhc3M9ImNscy0xIj4KICAgIDxnIGlkPSJMYXllcl8yIiBkYXRhLW5hbWU9IkxheWVyIDIiPgogICAgICA8ZyBpZD0iT2JqZWN0cyI+CiAgICAgICAgPHJlY3QgaWQ9Il9SZWN0YW5nbGVfIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTIiIHg9IjEyOC42NTgxIiB5PSI4Ny43NDA1IiB3aWR0aD0iNjQuMzI5MSIgaGVpZ2h0PSI3NC44NTkiLz4KICAgICAgICA8cmVjdCBpZD0iX1JlY3RhbmdsZV8yIiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTMiIHg9IjY0LjMyOTEiIHk9IjEyLjg4MTUiIHdpZHRoPSI2NC4zMjkxIiBoZWlnaHQ9Ijc0Ljg1OSIvPgogICAgICAgIDxyZWN0IGlkPSJfUmVjdGFuZ2xlXzMiIGRhdGEtbmFtZT0iJmx0O1JlY3RhbmdsZSZndDsiIGNsYXNzPSJjbHMtNCIgeT0iODcuNzQwNSIgd2lkdGg9IjY0LjMyOTEiIGhlaWdodD0iNzQuODU5Ii8+CiAgICAgICAgPHBhdGggY2xhc3M9ImNscy01IiBkPSJNNjQuMzI5MSw4Ny43NEg1OC42NTIzYTYyLjc4NzcsNjIuNzg3NywwLDAsMC0yNC41Njg0LDIwLjc2MjFjLTguMjYwNywxMi4xOTYtNC4zNDM3LDE4LjI0MTUtMTEuNjYzNywzMS42Mzk1QzE2LjUxLDE1MC45Niw4LjA1MSwxNTcuODIsMCwxNjIuNTU2di4wNDM1aDY0LjMyOVoiLz4KICAgICAgICA8cmVjdCBpZD0iX1JlY3RhbmdsZV80IiBkYXRhLW5hbWU9IiZsdDtSZWN0YW5nbGUmZ3Q7IiBjbGFzcz0iY2xzLTYiIHg9IjY0LjMyOTEiIHk9Ijg3Ljc0MDUiIHdpZHRoPSI2NC4zMjkxIiBoZWlnaHQ9Ijc0Ljg1OSIvPgogICAgICAgIDxwYXRoIGNsYXNzPSJjbHMtNyIgZD0iTTE5Mi45ODcyLDg3Ljc0SDE4My4zNDNhNjIuNzg3Nyw2Mi43ODc3LDAsMCwwLTI0LjU2ODQsMjAuNzYyMWMtOC4yNjA3LDEyLjE5Ni00LjM0MzgsMTguMjQxNS0xMS42NjM3LDMxLjYzOTVhNTYuNzI0Niw1Ni43MjQ2LDAsMCwxLTE4LjQ1MjcsMTkuOTF2Mi41NDc0aDY0LjMyOVoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTgiIHg9IjE5Mi45ODcyIiB5PSI4Ny43NDA1IiB3aWR0aD0iNjQuMzI5MSIgaGVpZ2h0PSI3NC44NTkiLz4KICAgICAgICA8cGF0aCBjbGFzcz0iY2xzLTkiIGQ9Ik0xMjguNjU4MiwxMi44ODE1SDExNi41OUE2MS45NjQ2LDYxLjk2NDYsMCwwLDAsMTAxLjMyMzMsMjguMjE1QzkzLjA2MjUsNDAuNDEwOSw5Ni45Nzk0LDQ2LjQ1NjUsODkuNjYsNTkuODU0NCw4My4wMzE2LDcxLjk4NTcsNzMuMTk3LDc5LjE1MTQsNjQuMzI5MSw4My45MTA4djMuODNoNjQuMzI5MVoiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTEwIiB4PSIxMjguNjU4MSIgeT0iMTIuODgxNSIgd2lkdGg9IjY0LjMyOTEiIGhlaWdodD0iNzQuODU5Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy00IiB4PSIxMC4xNjA1IiB5PSI3NC44NTkiIHdpZHRoPSIyNC43NTM2IiBoZWlnaHQ9IjEyLjg4MTUiLz4KICAgICAgICA8cmVjdCBjbGFzcz0iY2xzLTQiIHg9IjUxLjk1MjMiIHk9Ijc0Ljg1OSIgd2lkdGg9IjI0Ljc1MzYiIGhlaWdodD0iMTIuODgxNSIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtNCIgeD0iOTMuNzQ0MSIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxMzguODE4NiIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIxODAuNjEwNCIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0yIiB4PSIyMjIuNDAyMiIgeT0iNzQuODU5IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0zIiB4PSI3NC40ODk1IiB3aWR0aD0iMjQuNzUzNiIgaGVpZ2h0PSIxMi44ODE1Ii8+CiAgICAgICAgPHJlY3QgY2xhc3M9ImNscy0zIiB4PSIxMTYuMjgxNCIgd2lkdGg9IjI0Ljc1MzYiIGhlaWdodD0iMTIuODgxNSIvPgogICAgICAgIDxyZWN0IGNsYXNzPSJjbHMtMyIgeD0iMTU4LjA3MzIiIHdpZHRoPSIyNC43NTM2IiBoZWlnaHQ9IjEyLjg4MTUiLz4KICAgICAgPC9nPgogICAgPC9nPgogIDwvZz4KPC9zdmc+Cg==' body: >2 You can use the Atlassian Connect for Bitbucket Cloud to build add-ons which can connect with the Bitbucket UI and your own application set. An add-on could be an integration with another existing service, new features for the Atlassian application, or even a new product that runs within the Atlassian application. For complete information see: [Atlassian Connect for Bitbucket Cloud](https://developer.atlassian.com/bitbucket/index.html) servers: - url: https://api.bitbucket.org/2.0 components: schemas: workspace: allOf: - $ref: '#/components/schemas/object' - type: object title: Workspace description: |- A Bitbucket workspace. Workspaces are used to organize repositories. properties: links: type: object properties: 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 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 members: 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 owners: 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 projects: 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 repositories: 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 snippets: 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 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 additionalProperties: false uuid: type: string description: The workspace's immutable id. name: type: string description: The name of the workspace. slug: type: string description: The short label that identifies this workspace. is_private: type: boolean description: >- Indicates whether the workspace is publicly accessible, or whether it is private to the members and consequently only visible to members. created_on: type: string format: date-time updated_on: type: string format: date-time additionalProperties: true paginated_webhook_subscriptions: type: object title: Paginated Webhook Subscriptions description: A paginated list of webhook subscriptions properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/webhook_subscription' minItems: 0 uniqueItems: true additionalProperties: false webhook_subscription: allOf: - $ref: '#/components/schemas/object' - type: object title: Webhook Subscription description: A Webhook subscription. properties: uuid: type: string description: The webhook's id url: type: string description: The URL events get delivered to. format: uri description: type: string description: A user-defined description of the webhook. subject_type: type: string description: >- The type of entity. Set to either `repository` or `workspace` based on where the subscription is defined. enum: - repository - workspace subject: $ref: '#/components/schemas/object' active: type: boolean created_at: type: string format: date-time events: type: array description: The events this webhook is subscribed to. items: type: string enum: - pullrequest:comment_reopened - pullrequest:approved - issue:comment_created - repo:push - pullrequest:comment_deleted - pullrequest:fulfilled - pullrequest:comment_created - pullrequest:comment_updated - pullrequest:updated - repo:commit_status_created - pullrequest:unapproved - repo:updated - pullrequest:comment_resolved - repo:transfer - repo:commit_status_updated - pullrequest:changes_request_created - issue:updated - repo:created - pullrequest:changes_request_removed - pullrequest:rejected - pullrequest:created - issue:created - repo:imported - repo:commit_comment_created - project:updated - repo:fork - repo:deleted minItems: 1 uniqueItems: true secret_set: type: boolean description: >- Indicates whether or not the hook has an associated secret. It is not possible to see the hook's secret. This field is ignored during updates. secret: type: string description: >- The secret to associate with the hook. The secret is never returned via the API. As such, this field is only used during updates. The secret can be set to `null` or "" to remove the secret (or create a hook with no secret). Leaving out the secret field during updates will leave the secret unchanged. Leaving out the secret during creation will create a hook with no secret. minLength: 0 maxLength: 128 additionalProperties: true paginated_workspace_memberships: type: object title: Paginated Workspace Memberships description: A paginated list of workspace memberships. properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/workspace_membership' minItems: 0 uniqueItems: true additionalProperties: false workspace_membership: allOf: - $ref: '#/components/schemas/object' - type: object title: Workspace Membership description: |- A Bitbucket workspace membership. Links a user to a workspace. 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 additionalProperties: false user: $ref: '#/components/schemas/account' workspace: $ref: '#/components/schemas/workspace' additionalProperties: true paginated_repository_permissions: type: object title: Paginated Repository Permissions description: A paginated list of repository permissions. properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/repository_permission' minItems: 0 uniqueItems: true additionalProperties: false paginated_pipeline_variables: type: object title: Paginated Pipeline Variables description: A paged list of variables. properties: page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. values: type: array minItems: 0 items: $ref: '#/components/schemas/pipeline_variable' description: The values of the current page. size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. next: type: string format: uri description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. previous: type: string format: uri description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. pipeline_variable: allOf: - $ref: '#/components/schemas/object' - additionalProperties: true type: object title: Pipeline Variable description: A Pipelines variable. properties: uuid: type: string description: The UUID identifying the variable. key: type: string description: The unique name of the variable. value: type: string description: >- The value of the variable. If the variable is secured, this will be empty. secured: type: boolean description: >- If true, this variable will be treated as secured. The value will never be exposed in the logs or the REST API. paginated_projects: type: object title: Paginated Projects description: A paginated list of projects properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/project' minItems: 0 uniqueItems: true additionalProperties: false project: allOf: - $ref: '#/components/schemas/object' - type: object title: Project description: |- A Bitbucket project. 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: >2- 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: >2- Indicates whether the project contains publicly visible repositories. Note that private projects cannot contain public repositories. additionalProperties: true project_branching_model: allOf: - $ref: '#/components/schemas/object' - type: object title: Project Branching Model description: A project's branching model properties: branch_types: type: array description: The active branch types. items: type: object properties: kind: type: string description: The kind of branch. enum: - feature - bugfix - release - hotfix prefix: type: string description: >- The prefix for this branch type. A branch with this prefix will be classified as per `kind`. The prefix must be a valid prefix for a branch and must always exist. It cannot be blank, empty or `null`. required: - kind - prefix additionalProperties: false minItems: 0 maxItems: 4 uniqueItems: true development: type: object properties: name: type: string description: >- Name of the target branch. If inherited by a repository, it will default to the main branch if the specified branch does not exist. use_mainbranch: type: boolean description: >- Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`). required: - name - use_mainbranch additionalProperties: false production: type: object properties: name: type: string description: >- Name of the target branch. If inherited by a repository, it will default to the main branch if the specified branch does not exist. use_mainbranch: type: boolean description: >- Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`). required: - name - use_mainbranch additionalProperties: false additionalProperties: true branching_model_settings: allOf: - $ref: '#/components/schemas/object' - type: object title: Branching Model Settings description: A repository's branching model settings 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 additionalProperties: false branch_types: type: array items: type: object properties: enabled: type: boolean description: >- Whether the branch type is enabled or not. A disabled branch type may contain an invalid `prefix`. kind: type: string description: The kind of the branch type. enum: - feature - bugfix - release - hotfix prefix: type: string description: >- The prefix for this branch type. A branch with this prefix will be classified as per `kind`. The `prefix` of an enabled branch type must be a valid branch prefix.Additionally, it cannot be blank, empty or `null`. The `prefix` for a disabled branch type can be empty or invalid. required: - kind additionalProperties: false minItems: 0 maxItems: 4 uniqueItems: true development: type: object properties: is_valid: type: boolean description: >- Indicates if the configured branch is valid, that is, if the configured branch actually exists currently. Is always `true` when `use_mainbranch` is `true` (even if the main branch does not exist). This field is read-only. This field is ignored when updating/creating settings. name: type: string description: >- The configured branch. It must be `null` when `use_mainbranch` is `true`. Otherwise it must be a non-empty value. It is possible for the configured branch to not exist (e.g. it was deleted after the settings are set). In this case `is_valid` will be `false`. The branch must exist when updating/setting the `name` or an error will occur. use_mainbranch: type: boolean description: >- Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`). When `true` the `name` must be `null` or not provided. When `false` the `name` must contain a non-empty branch name. additionalProperties: false production: type: object properties: is_valid: type: boolean description: >- Indicates if the configured branch is valid, that is, if the configured branch actually exists currently. Is always `true` when `use_mainbranch` is `true` (even if the main branch does not exist). This field is read-only. This field is ignored when updating/creating settings. name: type: string description: >- The configured branch. It must be `null` when `use_mainbranch` is `true`. Otherwise it must be a non-empty value. It is possible for the configured branch to not exist (e.g. it was deleted after the settings are set). In this case `is_valid` will be `false`. The branch must exist when updating/setting the `name` or an error will occur. use_mainbranch: type: boolean description: >- Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`). When `true` the `name` must be `null` or not provided. When `false` the `name` must contain a non-empty branch name. enabled: type: boolean description: Indicates if branch is enabled or not. additionalProperties: false additionalProperties: true paginated_default_reviewer_and_type: type: object title: Paginated Default Reviewer and Type description: A paginated list of default reviewers with reviewer type. properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/default_reviewer_and_type' minItems: 0 uniqueItems: true additionalProperties: false user: allOf: - $ref: '#/components/schemas/account' - type: object title: User description: A user object. properties: links: $ref: '#/components/schemas/user_links' account_id: type: string description: The user's Atlassian account ID. account_status: type: string description: >- The status of the account. Currently the only possible value is "active", but more values may be added in the future. has_2fa_enabled: type: boolean nickname: type: string description: >- Account name defined by the owner. Should be used instead of the "username" field. Note that "nickname" cannot be used in place of "username" in URLs and queries, as "nickname" is not guaranteed to be unique. is_staff: type: boolean website: type: string additionalProperties: true paginated_project_deploy_keys: type: object title: Paginated Project Deploy Keys description: A paginated list of project deploy keys. properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/project_deploy_key' minItems: 0 uniqueItems: true additionalProperties: false project_deploy_key: allOf: - $ref: '#/components/schemas/object' - type: object title: Project Deploy Key description: Represents deploy key for a project. properties: key: type: string description: The deploy key value. project: $ref: '#/components/schemas/project' comment: type: string description: The comment parsed from the deploy key (if present) label: type: string description: The user-defined label for the deploy key added_on: type: string format: date-time last_used: type: string format: date-time 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 additionalProperties: false created_by: $ref: '#/components/schemas/account' additionalProperties: true paginated_project_group_permissions: type: object title: Paginated Project Group Permissions description: A paginated list of project group permissions. properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/project_group_permission' minItems: 0 uniqueItems: true additionalProperties: false project_group_permission: type: object title: Project Group Permission description: A group's permission for a given project. 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 additionalProperties: false permission: type: string enum: - read - write - create-repo - admin - none group: $ref: '#/components/schemas/group' project: $ref: '#/components/schemas/project' required: - type additionalProperties: true paginated_project_user_permissions: type: object title: Paginated Project User Permissions description: A paginated list of project user permissions. properties: size: type: integer description: >- Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute. minimum: 0 page: type: integer description: >- Page number of the current results. This is an optional element that is not provided in all responses. minimum: 1 pagelen: type: integer description: >- Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values. minimum: 1 next: type: string description: >- Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri previous: type: string description: >- Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs. format: uri values: type: array items: $ref: '#/components/schemas/project_user_permission' minItems: 0 uniqueItems: true additionalProperties: false project_user_permission: type: object title: Project User Permission description: A user's direct permission for a given project. 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 additionalProperties: false permission: type: string enum: - read - write - create-repo - admin - none user: $ref: '#/components/schemas/user' project: $ref: '#/components/schemas/project' 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: '#/components/schemas/search_code_search_result' repository_permission: type: object title: Repository Permission description: A user's permission for a given repository. properties: type: type: string permission: type: string enum: - read - write - admin - none user: $ref: '#/components/schemas/user' repository: $ref: '#/components/schemas/repository' required: - type additionalProperties: true default_reviewer_and_type: type: object title: Default Reviewer and Type description: >- Object containing a user that is a default reviewer and the type of reviewer properties: type: type: string reviewer_type: type: string user: $ref: '#/components/schemas/user' required: - type additionalProperties: true group: allOf: - $ref: '#/components/schemas/object' - type: object title: Group description: A group object properties: links: type: object properties: self: type: object title: Link description: A link to a resource related to this object. properties: href: type: string format: uri name: type: string additionalProperties: false 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 owner: $ref: '#/components/schemas/account' workspace: $ref: '#/components/schemas/workspace' name: type: string slug: type: string description: >- The "sluggified" version of the group's name. This contains only ASCII characters and can therefore be slightly different than the name full_slug: type: string description: | The concatenation of the workspace's slug and the group's slug, separated with a colon (e.g. `acme:developers`) 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: '#/components/schemas/search_content_match' path_matches: type: array readOnly: true items: $ref: '#/components/schemas/search_segment' file: $ref: '#/components/schemas/commit_file' 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 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 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 team: allOf: - $ref: '#/components/schemas/account' - type: object title: Team description: A team object. properties: links: $ref: '#/components/schemas/team_links' additionalProperties: true user_links: allOf: - $ref: '#/components/schemas/account_links' - type: object title: User Links description: Links related to a User. properties: self: $ref: '#/components/schemas/link' html: $ref: '#/components/schemas/link' repositories: $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: |2 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: |2 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: >2 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 enum: - allow_forks - no_public_forks - no_forks project: $ref: '#/components/schemas/project' mainbranch: $ref: '#/components/schemas/branch' additionalProperties: true search_content_match: type: object properties: lines: type: array readOnly: true items: $ref: '#/components/schemas/search_line' search_segment: type: object properties: text: type: string readOnly: true match: type: boolean readOnly: true 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_line: type: object properties: line: type: integer format: int32 readOnly: true segments: type: array readOnly: true items: $ref: '#/components/schemas/search_segment' 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 account_links: type: object title: Account Links description: Links related to an Account. properties: avatar: $ref: '#/components/schemas/link' 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 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 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. items: type: string enum: - merge_commit - squash - fast_forward default_merge_strategy: type: string description: >- The default merge strategy for pull requests targeting this branch. additionalProperties: true 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' 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 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 - 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 examples: workspace: links: avatar: href: https://bitbucket.org/workspaces/example-workspace/avatar name: Avatar html: href: https://bitbucket.org/example-workspace name: HTML members: href: https://api.bitbucket.org/2.0/workspaces/example-workspace/members name: Members owners: href: https://api.bitbucket.org/2.0/workspaces/example-workspace/owners name: Owners projects: href: https://api.bitbucket.org/2.0/workspaces/example-workspace/projects name: Projects repositories: href: https://api.bitbucket.org/2.0/repositories/example-workspace name: Repositories snippets: href: https://api.bitbucket.org/2.0/snippets/example-workspace name: Snippets self: href: https://api.bitbucket.org/2.0/workspaces/example-workspace name: Self uuid: '{1234abcd-12ab-34cd-56ef-1234567890ab}' name: Example Workspace slug: example-workspace is_private: false created_on: '2023-01-15T10:30:00Z' updated_on: '2024-01-20T14:45:30Z' paginated-webhook-subscriptions: size: 42 page: 1 pagelen: 10 next: https://api.example.com/webhooks?page=2 previous: https://api.example.com/webhooks?page=0 values: uuid: 550e8400-e29b-41d4-a716-446655440000 url: https://example.com/webhook/endpoint description: Webhook for monitoring pull request events subject_type: repository subject: {} active: true created_at: '2024-01-15T10:30:00Z' events: - pullrequest:created - pullrequest:approved - repo:push secret_set: true secret: my-webhook-secret-key webhook-subscription: uuid: '{d7bb1ebe-7e0c-4a2f-9b4a-1c8e9f0a2b3c}' url: https://example.com/webhooks/bitbucket description: Webhook for monitoring pull request activities subject_type: repository subject: type: repository name: my-repo active: true created_at: '2024-01-15T10:30:00Z' events: - pullrequest:created - pullrequest:updated - pullrequest:approved - pullrequest:fulfilled - repo:push secret_set: true secret: my-webhook-secret-key-123 webhook-subscription_2: uuid: '{d6a8e1a7-8b5c-4f3e-9d2a-1b3c4d5e6f7a}' url: https://example.com/webhook description: Webhook for pull request events subject_type: repository subject: {} active: true created_at: '2024-01-15T10:30:00Z' events: - pullrequest:created - pullrequest:updated - pullrequest:approved - repo:push secret_set: true secret: my-webhook-secret-key-123 paginated-workspace-memberships: size: 50 page: 1 pagelen: 10 next: https://api.bitbucket.org/2.0/workspaces/my-workspace/members?page=2 previous: https://api.bitbucket.org/2.0/workspaces/my-workspace/members?page=0 values: links: self: href: >- https://api.bitbucket.org/2.0/workspaces/my-workspace/members/john-doe name: workspace-membership user: type: user uuid: '{12345678-1234-1234-1234-123456789abc}' username: john-doe display_name: John Doe workspace: type: workspace uuid: '{87654321-4321-4321-4321-cba987654321}' slug: my-workspace name: My Workspace workspace-membership: links: self: href: >- https://api.bitbucket.org/2.0/workspaces/my-workspace/members/john-doe name: self user: type: user uuid: '{a1b2c3d4-e5f6-7890-abcd-ef1234567890}' display_name: John Doe username: john-doe workspace: type: workspace uuid: '{b2c3d4e5-f6a7-8901-bcde-f12345678901}' name: My Workspace slug: my-workspace paginated-workspace-memberships_2: size: 50 page: 1 pagelen: 10 next: https://api.bitbucket.org/2.0/workspaces/my-workspace/members?page=2 previous: https://api.bitbucket.org/2.0/workspaces/my-workspace/members?page=0 values: links: self: href: >- https://api.bitbucket.org/2.0/workspaces/my-workspace/members/john-doe name: John Doe Membership user: type: user uuid: '{123e4567-e89b-12d3-a456-426614174000}' username: john-doe display_name: John Doe workspace: type: workspace uuid: '{987fcdeb-51a2-43f7-b890-123456789abc}' slug: my-workspace name: My Workspace paginated-repository-permissions: size: 42 page: 1 pagelen: 10 next: https://api.example.com/repositories/permissions?page=2 previous: https://api.example.com/repositories/permissions?page=0 values: {} paginated-repository-permissions_2: size: 42 page: 1 pagelen: 10 next: https://api.example.com/repositories/permissions?page=2 previous: https://api.example.com/repositories/permissions?page=0 values: {} paginated-pipeline-variables: page: 1 values: uuid: 550e8400-e29b-41d4-a716-446655440000 key: DATABASE_URL value: postgresql://localhost:5432/mydb secured: false size: 50 pagelen: 10 next: >- https://api.bitbucket.org/2.0/repositories/myworkspace/myrepo/pipelines_config/variables?page=2 previous: >- https://api.bitbucket.org/2.0/repositories/myworkspace/myrepo/pipelines_config/variables?page=0 pipeline-variable: uuid: 123e4567-e89b-12d3-a456-426614174000 key: DATABASE_URL value: postgresql://localhost:5432/mydb secured: false pipeline-variable_2: uuid: 3c7f0a9e-5b2d-4e8f-9a1c-6d4e2f8b3a7e key: DATABASE_URL value: https://example.com/db secured: false undefined: {} paginated-projects: size: 42 page: 1 pagelen: 10 next: https://api.bitbucket.org/2.0/workspaces/myworkspace/projects?page=2 previous: https://api.bitbucket.org/2.0/workspaces/myworkspace/projects?page=0 values: links: html: href: https://bitbucket.org/myworkspace/myproject name: Project Home avatar: href: https://bitbucket.org/account/myworkspace/projects/PROJ/avatar/32 name: Avatar uuid: '{a1b2c3d4-e5f6-7890-abcd-ef1234567890}' key: PROJ owner: {} name: My Project description: This is an example project for organizing repositories is_private: true created_on: '2023-01-15T10:30:00Z' updated_on: '2024-01-10T14:45:00Z' has_publicly_visible_repos: false project: links: html: href: https://bitbucket.org/projects/example-project name: Example Project avatar: href: https://bitbucket.org/account/example-project/avatar/32 name: Avatar uuid: '{a1b2c3d4-e5f6-7890-abcd-ef1234567890}' key: PROJ owner: type: team uuid: '{12345678-90ab-cdef-1234-567890abcdef}' username: example-team display_name: Example Team name: Example Project description: This is an example project for organizing repositories is_private: true created_on: '2023-01-15T10:30:00Z' updated_on: '2024-01-20T14:45:00Z' has_publicly_visible_repos: false project_2: links: html: href: https://bitbucket.org/projects/example-project name: Example Project avatar: href: https://bitbucket.org/projects/example-project/avatar.png name: Project Avatar uuid: '{a1b2c3d4-e5f6-7890-abcd-ef1234567890}' key: PROJ owner: type: team uuid: '{b2c3d4e5-f6a7-8901-bcde-f12345678901}' username: example-team display_name: Example Team name: Example Project description: This is an example Bitbucket project for organizing repositories is_private: true created_on: '2024-01-15T10:30:00.000Z' updated_on: '2024-01-20T14:45:00.000Z' has_publicly_visible_repos: false project-branching-model: branch_types: - kind: feature prefix: feature/ - kind: bugfix prefix: bugfix/ - kind: release prefix: release/ - kind: hotfix prefix: hotfix/ development: name: develop use_mainbranch: false production: name: main use_mainbranch: true branching-model-settings: links: self: href: >- https://api.bitbucket.org/2.0/repositories/myworkspace/myrepo/branching-model/settings name: Branching Model Settings branch_types: - enabled: true kind: feature prefix: feature/ - enabled: true kind: bugfix prefix: bugfix/ - enabled: true kind: release prefix: release/ - enabled: false kind: hotfix prefix: hotfix/ development: is_valid: true name: develop use_mainbranch: false production: is_valid: true name: main use_mainbranch: false enabled: true branching-model-settings_2: links: self: href: >- https://api.bitbucket.org/2.0/repositories/myworkspace/myrepo/branching-model/settings name: Branching Model Settings branch_types: - enabled: true kind: feature prefix: feature/ - enabled: true kind: bugfix prefix: bugfix/ - enabled: true kind: release prefix: release/ - enabled: false kind: hotfix prefix: hotfix/ development: is_valid: true name: develop use_mainbranch: false production: is_valid: true name: main use_mainbranch: true enabled: true paginated-default-reviewer-and-type: size: 42 page: 1 pagelen: 10 next: https://api.example.com/repositories/default-reviewers?page=2 previous: https://api.example.com/repositories/default-reviewers?page=0 values: {} user: links: self: href: https://api.bitbucket.org/2.0/users/example_user html: href: https://bitbucket.org/example_user avatar: href: https://avatar-management.services.atlassian.com/default/48 account_id: 5d2a8f5c9e8e4b0d8f6a3c1b account_status: active has_2fa_enabled: true nickname: johndoe is_staff: false website: https://example.com user_2: links: self: href: https://api.bitbucket.org/2.0/users/example-user html: href: https://bitbucket.org/example-user avatar: href: https://avatar-management.example.com/avatar/123 account_id: 5d5355e8c6b9320d9ea5b28d account_status: active has_2fa_enabled: true nickname: john_doe is_staff: false website: https://johndoe.example.com paginated-project-deploy-keys: size: 42 page: 1 pagelen: 10 next: https://api.bitbucket.org/2.0/projects/PROJ/deploy-keys?page=2 previous: https://api.bitbucket.org/2.0/projects/PROJ/deploy-keys?page=0 values: key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDak... comment: Deploy key for production server label: Production Deploy Key added_on: '2023-11-15T10:30:00Z' last_used: '2024-01-20T14:45:30Z' links: self: href: https://api.bitbucket.org/2.0/projects/PROJ/deploy-keys/123 name: Production Deploy Key project-deploy-key: key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... project: key: PROJ name: My Project comment: deploy@server label: Production Server Deploy Key added_on: '2024-01-15T10:30:00Z' last_used: '2024-01-20T14:45:30Z' links: self: href: https://api.bitbucket.org/2.0/projects/PROJ/deploy-keys/123 name: Production Deploy Key created_by: uuid: '{a1b2c3d4-e5f6-7890-abcd-ef1234567890}' username: john_doe display_name: John Doe project-deploy-key_2: key: ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... project: key: PROJ name: My Project comment: deploy@example.com label: Production Deploy Key added_on: '2023-11-15T10:30:00Z' last_used: '2024-01-20T14:45:30Z' links: self: href: https://api.bitbucket.org/2.0/projects/PROJ/deploy-keys/123 name: Production Deploy Key created_by: username: johndoe display_name: John Doe uuid: '{a1b2c3d4-e5f6-7890-abcd-ef1234567890}' paginated-project-group-permissions: size: 42 page: 1 pagelen: 10 next: https://api.example.com/project-groups/permissions?page=2 previous: https://api.example.com/project-groups/permissions?page=0 values: [] project-group-permission: type: project-group-permission links: self: href: https://api.example.com/projects/123/permissions/groups/456 name: Project Group Permission permission: admin group: name: developers id: 456 project: key: PROJ name: Example Project id: 123 project-group-permission_2: type: project-group-permission links: self: href: https://api.example.com/projects/123/permissions/groups/456 name: Project Group Permission permission: write group: name: developers id: 456 project: key: PROJ id: 123 name: Example Project paginated-project-user-permissions: size: 50 page: 1 pagelen: 10 next: https://api.example.com/projects/permissions?page=2 previous: https://api.example.com/projects/permissions?page=0 values: [] undefined_2: size: 100 page: 1 pagelen: 10 query_substituted: false next: https://api.example.com/resource?page=2 previous: https://api.example.com/resource?page=0 values: {} project-user-permission: type: PROJECT_USER_PERMISSION links: self: href: https://api.example.com/projects/123/permissions/456 name: project-permission permission: admin user: name: john.doe emailAddress: john.doe@example.com id: 456 displayName: John Doe active: true project: key: PROJ id: 123 name: Example Project description: An example project public: false type: NORMAL project-user-permission_2: type: project-user-permission links: self: href: https://api.example.com/projects/123/permissions/456 name: Project Permission permission: admin user: id: 456 name: john.doe displayName: John Doe emailAddress: john.doe@example.com project: id: 123 key: PROJ name: Example Project description: An example project reponses: {} parameters: {} headers: {} requestBodies: pipeline_variable2: content: application/json: schema: $ref: '#/components/schemas/pipeline_variable' description: The variable to create. pipeline_variable: content: application/json: schema: $ref: '#/components/schemas/pipeline_variable' description: The updated variable. required: true project: content: application/json: schema: $ref: '#/components/schemas/project' required: true responses: {}