Support for Server products ended Feb. 15, 2024. Learn what this means for you.

Server

Bitbucket Data Center / Reference / REST API

Project

Operations

GET

Get a page of default tasks

Retrieves the default tasks for the supplied project.

The authenticated user must have PROJECT_VIEW permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Query parameters

markup

string

start

number

limit

number

Responses

A page of default tasks

application/json

object

GET/default-tasks/latest/projects/{projectKey}/tasks

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/default-tasks/latest/projects/{projectKey}/tasks' \
  --header 'Accept: application/json'

200Response

{
  "isLastPage": true,
  "limit": 25,
  "nextPageStart": 2154,
  "size": 1,
  "start": 2154,
  "values": [
    {
      "description": "Default task description",
      "id": 1
    }
  ]
}

POST

Add a default task

Creates a default task for the project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/json

The task to be added

description

string

sourceMatcher

object

targetMatcher

object

Responses

The default task

application/json

RestDefaultTask

POST/default-tasks/latest/projects/{projectKey}/tasks

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/default-tasks/latest/projects/{projectKey}/tasks' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "Default task description",
  "sourceMatcher": {
    "displayId": "main",
    "id": "refs/heads/main",
    "type": {
      "id": "ANY_REF",
      "name": "Branch"
    }
  },
  "targetMatcher": {
    "displayId": "main",
    "id": "refs/heads/main",
    "type": {
      "id": "ANY_REF",
      "name": "Branch"
    }
  }
}'

200Response

{
  "description": "Default task description",
  "id": 1
}

DEL

Deletes all default tasks for the project

Delete all the default tasks for the supplied project

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Responses

The default tasks have been deleted successfully.

DEL/default-tasks/latest/projects/{projectKey}/tasks

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/default-tasks/latest/projects/{projectKey}/tasks'

PUT

Update a default task

Updates a default task for the supplied project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

taskId

string

Required

Request bodyapplication/json

The task to be updated

description

string

sourceMatcher

object

targetMatcher

object

Responses

The default task

application/json

RestDefaultTask

PUT/default-tasks/latest/projects/{projectKey}/tasks/{taskId}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/default-tasks/latest/projects/{projectKey}/tasks/{taskId}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "description": "Default task description",
  "sourceMatcher": {
    "displayId": "main",
    "id": "refs/heads/main",
    "type": {
      "id": "ANY_REF",
      "name": "Branch"
    }
  },
  "targetMatcher": {
    "displayId": "main",
    "id": "refs/heads/main",
    "type": {
      "id": "ANY_REF",
      "name": "Branch"
    }
  }
}'

200Response

{
  "description": "Default task description",
  "id": 1
}

DEL

Delete a specific default task

Delete a specific default task for a project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

taskId

string

Required

Responses

The default task has been deleted successfully.

DEL/default-tasks/latest/projects/{projectKey}/tasks/{taskId}

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/default-tasks/latest/projects/{projectKey}/tasks/{taskId}'

GET

Search for ref restrictions

Search for restrictions using the supplied parameters.

The authenticated user must have PROJECT_ADMIN permission or higher to call this resource. Only authenticated users may call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

matcherType

string

matcherId

string

type

string

start

number

limit

number

Responses

A response containing a page of restrictions.

application/json;charset=UTF-8

object

GET/branch-permissions/latest/projects/{projectKey}/restrictions

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/branch-permissions/latest/projects/{projectKey}/restrictions' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Create multiple ref restrictions

Allows creating multiple restrictions at once.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/vnd.atl.bitbucket.bulk+json

The request containing a list of the details of the restrictions to create.

array<RestRestrictionRequest>

accessKeyIds

array<integer>

accessKeys

array<RestSshAccessKey>

groupNames

array<string>

groups

array<string>

matcher

object

type

string

userSlugs

array<string>

users

array<RestApplicationUser>

Responses

Response contains the ref restriction that was just created.

application/json;charset=UTF-8

RestRefRestriction

POST/branch-permissions/latest/projects/{projectKey}/restrictions

curl

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'http://{baseurl}/rest/branch-permissions/latest/projects/{projectKey}/restrictions' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get a ref restriction

Returns a restriction as specified by a restriction id.

The authenticated user must have PROJECT_ADMIN permission or higher to call this resource. Only authenticated users may call this resource.

Request

Path parameters

projectKey

string

Required

string

Required

Responses

A response containing the restriction.

application/json;charset=UTF-8

RestRefRestriction

GET/branch-permissions/latest/projects/{projectKey}/restrictions/{id}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/branch-permissions/latest/projects/{projectKey}/restrictions/{id}' \
  --header 'Accept: application/json;charset=UTF-8'

DEL

Delete a ref restriction

Deletes a restriction as specified by a restriction id.

The authenticated user must have PROJECT_ADMIN permission or higher to call this resource. Only authenticated users may call this resource.

Request

Path parameters

projectKey

string

Required

string

Required

Responses

An empty response indicating that the operation was successful

DEL/branch-permissions/latest/projects/{projectKey}/restrictions/{id}

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/branch-permissions/latest/projects/{projectKey}/restrictions/{id}'

GET

Get project avatar

Retrieve the avatar for the project matching the supplied moduleKey.

Request

Path parameters

hookKey

string

Required

Query parameters

version

string

Responses

The avatar of the project matching the supplied moduleKey.

application/json

any

GET/api/latest/hooks/{hookKey}/avatar

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/hooks/{hookKey}/avatar' \
  --header 'Accept: application/json'

GET

Get projects

Retrieve a page of projects.

Only projects for which the authenticated user has the PROJECT_VIEW permission will be returned.

Request

Query parameters

name

string

permission

string

start

number

limit

number

Responses

A page of projects.

application/json;charset=UTF-8

object

GET/api/latest/projects

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Create a new project

Create a new project.

To include a custom avatar for the project, the project definition should contain an additional attribute with the key avatar and the value a data URI containing Base64-encoded image data. The URI should be in the following format:

    data:(content type, e.g. image/png);base64,(data)

If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.

The authenticated user must have PROJECT_CREATE permission to call this resource.

Request

Request bodyapplication/json

The project.

avatar

string

avatarUrl

string

key

string

links

object

Responses

The newly created project.

application/json;charset=UTF-8

RestProject

POST/api/latest/projects

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "avatar": "<string>",
  "avatarUrl": "<string>",
  "key": "PRJ",
  "links": {}
}'

GET

Get a project

Retrieve the project matching the supplied projectKey.

The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Responses

The project matching the supplied projectKey.

application/json;charset=UTF-8

RestProject

GET/api/latest/projects/{projectKey}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update project

Update the project matching the projectKey supplied in the resource path.

To include a custom avatar for the updated project, the project definition should contain an additional attribute with the key avatar and the value a data URI containing Base64-encoded image data. The URI should be in the following format: data:(content type, e.g. image/png);base64,(data)

If the data is not Base64-encoded, or if a character set is defined in the URI, or the URI is otherwise invalid, project creation will fail.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/json

Project parameters to update.

avatar

string

avatarUrl

string

key

string

links

object

Responses

The updated project. The project's key was not updated.

application/json;charset=UTF-8

RestProject

PUT/api/latest/projects/{projectKey}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "avatar": "<string>",
  "avatarUrl": "<string>",
  "key": "PRJ",
  "links": {}
}'

DEL

Delete project

Delete the project matching the supplied projectKey.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Responses

The project matching the supplied projectKey was deleted.

DEL/api/latest/projects/{projectKey}

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}'

GET

Get avatar for project

Retrieve the avatar for the project matching the supplied projectKey.

The authenticated user must have PROJECT_VIEW permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

string

Responses

The avatar of the project matching the supplied projectKey.

image/png

any

GET/api/latest/projects/{projectKey}/avatar.png

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/avatar.png' \
  --header 'Accept: image/png'

POST

Update project avatar

Update the avatar for the project matching the supplied projectKey.

This resource accepts POST multipart form data, containing a single image in a form-field named 'avatar'.

There are configurable server limits on both the dimensions (1024x1024 pixels by default) and uploaded file size (1MB by default). Several different image formats are supported, but PNG and JPEG are preferred due to the file size limit.

This resource has Cross-Site Request Forgery (XSRF) protection. To allow the request to pass the XSRF check the caller needs to send an X-Atlassian-Token HTTP header with the value no-check.

An example curl request to upload an image name 'avatar.png' would be: curl -X POST -u username:password -H "X-Atlassian-Token: no-check" http://example.com/rest/api/1.0/projects/STASH/avatar.png -F avatar=@avatar.png

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Request bodymultipart/form-data

The mutlipart form data containing the file.

avatar

string

Responses

The avatar was uploaded successfully.

application/json;charset=UTF-8

any

POST/api/latest/projects/{projectKey}/avatar.png

curl

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/avatar.png' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get configured hook scripts

Return a page of hook scripts configured for the specified project.

This endpoint requires PROJECT_ADMIN permission.

Request

Path parameters

projectKey

string

Required

Query parameters

start

number

limit

number

Responses

A page of hook scripts.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/hook-scripts

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/hook-scripts' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Create/update a hook script

Creates/updates the hook script configuration for the provided hook script and project.

This endpoint requires PROJECT_ADMIN permission.

Request

Path parameters

projectKey

string

Required

scriptId

string

Required

Request bodyapplication/json

The hook triggers for which the hook script should be run

triggerIds

array<string>

Responses

The updated hook script.

application/json;charset=UTF-8

RestHookScriptConfig

PUT/api/latest/projects/{projectKey}/hook-scripts/{scriptId}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/hook-scripts/{scriptId}' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "triggerIds": [
    "<string>"
  ]
}'

DEL

Remove a hook script

Removes the hook script from the set of hook scripts configured to run in all repositories under the project.

This endpoint requires PROJECT_ADMIN permission.

Request

Path parameters

projectKey

string

Required

scriptId

string

Required

Responses

The hook script was successfully deleted.

DEL/api/latest/projects/{projectKey}/hook-scripts/{scriptId}

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/hook-scripts/{scriptId}'

DEL

Revoke project permissions

Revoke all permissions for the specified project for the given groups and users.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

In addition, a user may not revoke a group's permission if their own permission would be revoked as a result, nor may they revoke their own permission unless they have a global permission that already implies that permission.

Request

Path parameters

projectKey

string

Required

Query parameters

user

string

group

string

Responses

All project permissions were revoked from the users and groups for the specified project.

DEL/api/latest/projects/{projectKey}/permissions

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions'

GET

Get groups with permission to project

Retrieve a page of groups that have been granted at least one permission for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

filter

string

start

number

limit

number

Responses

A page of groups and their highest permissions for the specified project.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/permissions/groups

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update group project permission

Promote or demote a group's permission level for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not demote a group's permission level if theirown permission level would be reduced as a result.

Request

Path parameters

projectKey

string

Required

Query parameters

name

string

permission

string

Responses

The requested permission was granted.

PUT/api/latest/projects/{projectKey}/permissions/groups

curl

Node.js

Java

Python

PHP

1
2

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups'

DEL

Revoke group project permission

Revoke all permissions for the specified project for a group.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

In addition, a user may not revoke a group's permissions if it will reduce their own permission level.

Request

Path parameters

projectKey

string

Required

Query parameters

name

string

Responses

All project permissions were revoked from the group for the specified project.

DEL/api/latest/projects/{projectKey}/permissions/groups

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups'

GET

Get groups without project permission

Retrieve a page of groups that have no granted permissions for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher

Request

Path parameters

projectKey

string

Required

Query parameters

filter

string

start

number

limit

number

Responses

A page of groups that have not been granted any permissions for the specifiedproject.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/permissions/groups/none

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/groups/none' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Search project permissions

Search direct and implied permissions of principals (users and groups). This endpoint returns a superset of the results returned by the /users and /groups endpoints because it allows filtering by global permissions too.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

permission

string

filterText

string

type

string

Responses

default response

application/json;charset=UTF-8

any

GET/api/latest/projects/{projectKey}/permissions/search

curl

Node.js

Java

Python

PHP

1
2

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/search'

GET

Get users with permission to project

Retrieve a page of users that have been granted at least one permission for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

filter

string

start

number

limit

number

Responses

A page of users and their highest permissions for the specified project.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/permissions/users

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update user project permission

Promote or demote a user's permission level for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource. In addition, a user may not reduce their own permission level unless they have a global permission that already implies that permission.

Request

Path parameters

projectKey

string

Required

Query parameters

name

string

permission

string

Responses

The requested permission was granted.

PUT/api/latest/projects/{projectKey}/permissions/users

curl

Node.js

Java

Python

PHP

1
2

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users'

DEL

Revoke user project permission

Revoke all permissions for the specified project for a user.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

In addition, a user may not revoke their own project permissions if they do not have a higher global permission.

Request

Path parameters

projectKey

string

Required

Query parameters

name

string

Responses

All project permissions were revoked from the user for the specified project.

DEL/api/latest/projects/{projectKey}/permissions/users

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users'

GET

Get users without project permission

Retrieve a page of licensed users that have no granted permissions for the specified project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

filter

string

start

number

limit

number

Responses

A page of users that have not been granted any permissions for the specified project

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/permissions/users/none

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/users/none' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Check default project permission

Check whether the specified permission is the default permission (granted to all users) for a project.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

Request

Path parameters

projectKey

string

Required

permission

string

Required

Responses

A simple entity indicating whether the specified permission is the defaultpermission for this project.

application/json;charset=UTF-8

RestPermitted

GET/api/latest/projects/{projectKey}/permissions/{permission}/all

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/{permission}/all' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Grant project permission

Grant or revoke a project permission to all users, i.e. set the default permission.

The authenticated user must have PROJECT_ADMIN permission for the specified project or a higher global permission to call this resource.

Request

Path parameters

projectKey

string

Required

permission

string

Required

Query parameters

allow

string

Responses

The requested permission was successfully granted or revoked.

POST/api/latest/projects/{projectKey}/permissions/{permission}/all

curl

Node.js

Java

Python

PHP

1
2

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/permissions/{permission}/all'

GET

Get repositories for project

Retrieve repositories from the project corresponding to the supplied projectKey.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

start

number

limit

number

Responses

The repositories matching the supplied projectKey.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/repos

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Create repository

Create a new repository. Requires an existing project in which this repository will be created. The only parameters which will be used are name and scmId.

The authenticated user must have REPO_CREATE permission or higher, for the context project to call this resource.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/json

The repository

defaultBranch

string

links

object

name

string

project

object

scmId

string

slug

string

Responses

The newly created repository.

application/json;charset=UTF-8

RestRepository

POST/api/latest/projects/{projectKey}/repos

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "defaultBranch": "main",
  "links": {},
  "name": "My repo",
  "project": {
    "avatar": "<string>",
    "avatarUrl": "<string>",
    "key": "PRJ",
    "links": {}
  },
  "scmId": "git",
  "slug": "my-repo"
}'

GET

Get repository

Retrieve the repository matching the supplied projectKey and repositorySlug.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Responses

The repository which matches the supplied projectKey and repositorySlug.

application/json;charset=UTF-8

RestRepository

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update repository

Update the repository matching the repositorySlug supplied in the resource path.

The repository's slug is derived from its name. If the name changes the slug may also change.

This resource can be used to change the repository's default branch by specifying a new default branch in the request. For example: "defaultBranch":"main"

This resource can be used to move the repository to a different project by specifying a new project in the request. For example: "project":{"key":"NEW_KEY"}

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Request bodyapplication/json

The updated repository.

defaultBranch

string

links

object

name

string

project

object

scmId

string

slug

string

Responses

The updated repository.

application/json;charset=UTF-8

RestRepository

PUT/api/latest/projects/{projectKey}/repos/{repositorySlug}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "defaultBranch": "main",
  "links": {},
  "name": "My repo",
  "project": {
    "avatar": "<string>",
    "avatarUrl": "<string>",
    "key": "PRJ",
    "links": {}
  },
  "scmId": "git",
  "slug": "my-repo"
}'

POST

Fork repository

Create a new repository forked from an existing repository.

The JSON body for this POST is not required to contain any properties. Even the name may be omitted. The following properties will be used, if provided:

"name":"Fork name" - Specifies the forked repository's name
- Defaults to the name of the origin repository if not specified
"defaultBranch":"main" - Specifies the forked repository's default branch
- Defaults to the origin repository's default branch if not specified
"project":{"key":"TARGET_KEY"} - Specifies the forked repository's target project by key
- Defaults to the current user's personal project if not specified

The authenticated user must have REPO_READ permission for the specified repository and PROJECT_ADMIN on the target project to call this resource. Note that users always have PROJECT_ADMIN permission on their personal projects.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Request bodyapplication/json

The rest fork.

defaultBranch

string

links

object

name

string

project

object

scmId

string

slug

string

Responses

The newly created fork.

application/json;charset=UTF-8

RestRepository

POST/api/latest/projects/{projectKey}/repos/{repositorySlug}

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "defaultBranch": "main",
  "links": {},
  "name": "My repo",
  "project": {
    "avatar": "<string>",
    "avatarUrl": "<string>",
    "key": "PRJ",
    "links": {}
  },
  "scmId": "git",
  "slug": "my-repo"
}'

DEL

Delete repository

Schedule the repository matching the supplied projectKey and repositorySlug to be deleted.

The authenticated user must have sufficient permissions specified by the repository delete policy to call this resource. The default permission required is REPO_ADMIN permission.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Responses

The repository has been scheduled for deletion.

application/json;charset=UTF-8

any

DEL/api/latest/projects/{projectKey}/repos/{repositorySlug}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get repository contributing guidelines

Retrieves the contributing guidelines for the repository, if they've been defined.

This checks the repository for a CONTRIBUTING file, optionally with an md or txt extension, and, if found, streams it. By default, the raw content of the file is streamed. Appending ?markup to the URL will stream an HTML-rendered version instead.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Query parameters

string

markup

string

htmlEscape

string

includeHeadingId

string

hardwrap

string

Responses

The contributing guidelines for the repository.

/

any

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/contributing

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/contributing' \
  --header 'Accept: */*'

GET

Get repository default branch

Retrieves the repository's configured default branch.

Every repository has a configured default branch, but that branch may not actually exist in the repository. For example, a newly-created repository will have a configured default branch even though no branches have been pushed yet.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Responses

The configured default branch for the repository.

application/json;charset=UTF-8

RestMinimalRef

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/default-branch

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/default-branch' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update default branch for repository

Update the default branch of a repository.

The authenticated user must have REPO_ADMIN permission for the specified repository to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Request bodyapplication/json

The branch to set as default

string

type

RefType

Responses

The default branch was updated.

PUT/api/latest/projects/{projectKey}/repos/{repositorySlug}/default-branch

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/default-branch' \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "refs/heads/master"
}'

GET

Get repository forks

Retrieve repositories which have been forked from this one. Unlike #getRelatedRepositories(Repository, PageRequest) related repositories, this only looks at a given repository's direct forks. If those forks have themselves been the origin of more forks, such "grandchildren" repositories will not be retrieved.

Only repositories to which the authenticated user has REPO_READ permission will be included, even if other repositories have been forked from this one.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Query parameters

start

number

limit

number

Responses

A page of repositories related to the request repository.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/forks

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/forks' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get repository license

Retrieves the license for the repository, if it's been defined.

This checks the repository for a

LICENSE

file, optionally with an

md

txt

extension, and, if found, streams it. By default, the raw content of the file is streamed. Appending

?markup

to the URL will stream an HTML-rendered version instead.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Query parameters

string

markup

string

htmlEscape

string

includeHeadingId

string

hardwrap

string

Responses

The license for the repository.

/

any

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/license

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/license' \
  --header 'Accept: */*'

GET

Get repository readme

Retrieves the README for the repository, if it's been defined.

This checks the repository for a

README

file, optionally with an

md

txt

extension, and, if found, streams it. By default, the raw content of the file is streamed. Appending

?markup

to the URL will stream an HTML-rendered version instead. Note that, when streaming HTML, relative URLs in the README will not work if applied relative to this URL.

The authenticated user must have REPO_READ permission for the specified repository to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Query parameters

string

markup

string

htmlEscape

string

includeHeadingId

string

hardwrap

string

Responses

The README for the repository.

/

any

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/readme

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/readme' \
  --header 'Accept: */*'

POST

Retry repository creation

If a create or fork operation fails, calling this method will clean up the broken repository and try again. The repository must be in an INITIALISATION_FAILED state.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

repositorySlug

string

Required

Responses

The newly created repository.

application/json;charset=UTF-8

RestRepository

POST/api/latest/projects/{projectKey}/repos/{repositorySlug}/recreate

curl

Node.js

Java

Python

PHP

1
2
3

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/recreate' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Retrieve repositories which are related to this one. Related repositories are from the same Repository#getHierarchyId() hierarchy as this repository.

Only repositories to which the authenticated user has REPO_READ permission will be included, even if more repositories are part of this repository's hierarchy.

projectKey

string

Required

repositorySlug

string

Required

start

number

limit

number

A page of repositories related to the request repository.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/repos/{repositorySlug}/related

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/repos/{repositorySlug}/related' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get enforcing project setting

Get a specified project settings restriction for the given namespace, feature key and component key. Note that not providing the component key will not return restrictions for the namespace and feature key with a component key set.

The authenticated user must have PROJECT_VIEW permission for the target project to retrieve a settings restriction.

Request

Path parameters

projectKey

string

Required

Query parameters

namespace

string

Required

componentKey

string

featureKey

string

Required

Responses

The settings restriction associated with the provided namespace and feature key

application/json;charset=UTF-8

RestProjectSettingsRestriction

GET/api/latest/projects/{projectKey}/settings-restriction

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings-restriction?namespace={namespace}&featureKey={featureKey}' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Enforce project restriction

Create a new project settings restriction for the given project.

The authenticated user must have PROJECT_ADMIN permission for the target project to create a settings restriction.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/json

The project settings restriction to create

componentKey

string

featureKey

string

Required

namespace

string

Required

Responses

The settings restriction was successfully created

application/json;charset=UTF-8

RestProjectSettingsRestriction

POST/api/latest/projects/{projectKey}/settings-restriction

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings-restriction' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "componentKey": "my-admin-component",
  "featureKey": "my-admin-feature",
  "namespace": "org.featuredeveloper"
}'

DEL

Stop enforcing project restriction

Delete a specified project settings restriction.

If a restriction does not exist for the specified project, namespace, featureKey, and componentKey, the request will be ignored and a 204 response will be returned.

The authenticated user must have PROJECT_ADMIN permission for the target project to delete a settings restriction.

Request

Path parameters

projectKey

string

Required

Query parameters

namespace

string

Required

componentKey

string

featureKey

string

Required

Responses

The specified settings restriction was successfully deleted or there were no existing restrictions that match the specified criteria.

DEL/api/latest/projects/{projectKey}/settings-restriction

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings-restriction?namespace={namespace}&featureKey={featureKey}'

GET

Get all enforcing project settings

Get all project settings restrictions for the given namespace and feature key, including those with a component key set.

The authenticated user must have PROJECT_VIEW permission for the target project to retrieve a settings restrictions.

Request

Path parameters

projectKey

string

Required

Query parameters

namespace

string

Required

featureKey

string

Required

start

number

limit

number

Responses

A page of settings restrictions associated with the provided namespace and feature key

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/settings-restriction/all

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings-restriction/all?namespace={namespace}&featureKey={featureKey}' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get auto decline settings

Retrieves the auto decline settings for the supplied project. Default settings are returned if no explicit settings have been set for the project.

Request

Path parameters

projectKey

string

Required

Responses

The auto decline settings

application/json;charset=UTF-8

RestAutoDeclineSettings

GET/api/latest/projects/{projectKey}/settings/auto-decline

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/auto-decline' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Create/Update auto decline settings

Creates or updates the auto decline settings for the supplied project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/json

The settings to create or update

enabled

boolean

inactivityWeeks

integer

Responses

The auto decline settings

application/json;charset=UTF-8

RestAutoDeclineSettings

PUT/api/latest/projects/{projectKey}/settings/auto-decline

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/auto-decline' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "enabled": true,
  "inactivityWeeks": 4
}'

DEL

Delete auto decline settings

Delete auto decline settings for the supplied project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Responses

The auto decline settings have been deleted successfully.

DEL/api/latest/projects/{projectKey}/settings/auto-decline

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/auto-decline'

GET

Get pull request auto-merge settings

Retrieves the pull request auto-merge settings for the supplied project. Default settings will be returned if no explicit settings have been set for the project

The authenticated user must have PROJECT_VIEW permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Responses

The pull request auto-merge settings

application/json;charset=UTF-8

RestAutoMergeRestrictedSettings

GET/api/latest/projects/{projectKey}/settings/auto-merge

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/auto-merge' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Create or update the pull request auto-merge settings

Creates or updates the pull request auto-merge settings for the supplied project, and applies the restriction action specified in the request.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/json

The settings to create or update

enabled

boolean

restrictionAction

string

Responses

The pull request auto-merge settings

application/json;charset=UTF-8

RestAutoMergeRestrictedSettings

PUT/api/latest/projects/{projectKey}/settings/auto-merge

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/auto-merge' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "enabled": false,
  "restrictionAction": "CREATE"
}'

DEL

Delete pull request auto-merge settings

Deletes pull request auto-merge settings for the supplied project.

The authenticated user must have PROJECT_ADMIN permission for this project to call the resource.

Request

Path parameters

projectKey

string

Required

Responses

The pull request auto-merge settings

DEL/api/latest/projects/{projectKey}/settings/auto-merge

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/auto-merge'

GET

Get repository hooks

Retrieve a page of repository hooks for this project.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

type

string

start

number

limit

number

Responses

A page of repository hooks with their associated enabled state.

application/json;charset=UTF-8

object

GET/api/latest/projects/{projectKey}/settings/hooks

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/hooks' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get a repository hook

Retrieve a repository hook for this project.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

hookKey

string

Required

Responses

Returns the repository hooks with their associated enabled state for the supplied hookKey.

application/json;charset=UTF-8

RestRepositoryHook

GET/api/latest/projects/{projectKey}/settings/hooks/{hookKey}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/hooks/{hookKey}' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Enable repository hook

Enable a repository hook for this project and optionally apply new configuration.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

A JSON document may be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.

Request

Path parameters

projectKey

string

Required

hookKey

string

Required

Header parameters

Content-Length

integer

Responses

The repository hooks with their associated enabled state for the supplied hookKey.

application/json;charset=UTF-8

RestRepositoryHook

PUT/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/enabled

curl

Node.js

Java

Python

PHP

1
2
3

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/enabled' \
  --header 'Accept: application/json;charset=UTF-8'

DEL

Disable repository hook

Disable a repository hook for this project.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

hookKey

string

Required

Responses

The repository hooks with their associated enabled state for the supplied hookKey.

application/json;charset=UTF-8

RestRepositoryHook

DEL/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/enabled

curl

Node.js

Java

Python

PHP

1
2
3

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/enabled' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get repository hook settings

Retrieve the settings for a repository hook for this project.

The authenticated user must have PROJECT_READ permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

hookKey

string

Required

Responses

The settings for the hook.

application/json;charset=UTF-8

ExampleSettings

GET/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/settings

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/settings' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update repository hook settings

Modify the settings for a repository hook for this project.

The service will reject any settings which are too large, the current limit is 32KB once serialized.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

A JSON document can be provided to use as the settings for the hook. These structure and validity of the document is decided by the plugin providing the hook.

Request

Path parameters

projectKey

string

Required

hookKey

string

Required

Request bodyapplication/json

The raw settings.

booleanValue

boolean

doubleValue

number

integerValue

integer

longValue

integer

stringValue

string

Responses

The settings for the hook.

application/json;charset=UTF-8

ExampleSettings

PUT/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/settings

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/hooks/{hookKey}/settings' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "booleanValue": true,
  "doubleValue": 1.1,
  "integerValue": 1,
  "longValue": -2147483648,
  "stringValue": "This is an arbitrary string"
}'

GET

Get merge strategy

Retrieve the merge strategy configuration for this project and SCM.

The authenticated user must have PROJECT_READ permission for the context repository to call this resource.

Request

Path parameters

projectKey

string

Required

scmId

string

Required

Responses

The merge configuration of the request project.

application/json;charset=UTF-8

RestPullRequestSettings

GET/api/latest/projects/{projectKey}/settings/pull-requests/{scmId}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/pull-requests/{scmId}' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Update merge strategy

Update the pull request merge strategy configuration for this project and SCM.

The authenticated user must have PROJECT_ADMIN permission for the context repository to call this resource.

Only the strategies provided will be enabled, the default must be set and included in the set of strategies.

An explicitly set pull request merge strategy configuration can be deleted by POSTing a document with an empty "mergeConfig" attribute. i.e:

{ 
    "mergeConfig": {} 
}

Upon completion of this request, the effective configuration will be the configuration explicitly set for the SCM, or if no such explicit configuration is set then the default configuration will be used.

Request

Path parameters

projectKey

string

Required

scmId

string

Required

Request bodyapplication/json

The settings.

mergeConfig

object

Responses

The merge configuration of the request project.

application/json;charset=UTF-8

RestPullRequestSettings

POST/api/latest/projects/{projectKey}/settings/pull-requests/{scmId}

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/settings/pull-requests/{scmId}' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "mergeConfig": {
    "commitMessageTemplate": {
      "body": "Merge in ${toProjectKey}/${toRepoSlug} from ${crossRepoProjectRepo}${fromRefName} to ${toRefName}",
      "title": "Pull request #${id}: ${title}"
    },
    "commitSummaries": 2154,
    "defaultStrategy": {
      "id": "no-ff",
      "links": {}
    },
    "strategies": [
      {
        "id": "no-ff",
        "links": {}
      }
    ]
  }
}'

GET

Find webhooks

Find webhooks in this project.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

event

string

statistics

boolean

Responses

A page of webhooks.

application/json;charset=UTF-8

any

GET/api/latest/projects/{projectKey}/webhooks

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks' \
  --header 'Accept: application/json;charset=UTF-8'

POST

Create webhook

Create a webhook for the project specified via the URL.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Request bodyapplication/json

The webhook to be created for this project.

active

boolean

configuration

object

credentials

RestWebhookCredentials

events

array<string>

name

string

scopeType

string

sslVerificationRequired

boolean

statistics

object

url

string

Responses

A created webhook.

application/json;charset=UTF-8

RestWebhook

POST/api/latest/projects/{projectKey}/webhooks

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "active": true,
  "configuration": {},
  "credentials": {
    "password": "<string>",
    "username": "<string>"
  },
  "events": [
    "<string>"
  ],
  "name": "<string>",
  "scopeType": "<string>",
  "sslVerificationRequired": true,
  "statistics": {},
  "url": "<string>"
}'

POST

Test webhook

Test connectivity to a specific endpoint.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

Query parameters

webhookId

integer

sslVerificationRequired

boolean

url

string

Request bodyapplication/json

Basic authentication credentials, if required.

password

string

username

string

Responses

A webhook.

application/json;charset=UTF-8

RestWebhookRequestResponse

POST/api/latest/projects/{projectKey}/webhooks/test

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks/test' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "password": "<string>",
  "username": "<string>"
}'

GET

Get webhook

Get a webhook by ID.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

webhookId

string

Required

Query parameters

statistics

string

Responses

A webhook.

application/json;charset=UTF-8

RestWebhook

GET/api/latest/projects/{projectKey}/webhooks/{webhookId}

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks/{webhookId}' \
  --header 'Accept: application/json;charset=UTF-8'

PUT

Update webhook

Update an existing webhook.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

webhookId

string

Required

Request bodyapplication/json

The representation of the updated values for the webhook

active

boolean

configuration

object

credentials

RestWebhookCredentials

events

array<string>

name

string

scopeType

string

sslVerificationRequired

boolean

statistics

object

url

string

Responses

A webhook.

application/json;charset=UTF-8

RestWebhook

PUT/api/latest/projects/{projectKey}/webhooks/{webhookId}

curl

Node.js

Java

Python

PHP

curl --request PUT \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks/{webhookId}' \
  --header 'Accept: application/json;charset=UTF-8' \
  --header 'Content-Type: application/json' \
  --data '{
  "active": true,
  "configuration": {},
  "credentials": {
    "password": "<string>",
    "username": "<string>"
  },
  "events": [
    "<string>"
  ],
  "name": "<string>",
  "scopeType": "<string>",
  "sslVerificationRequired": true,
  "statistics": {},
  "url": "<string>"
}'

DEL

Delete webhook

Delete a webhook for the project specified via the URL.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

webhookId

string

Required

Responses

The webhook for the project has been deleted.

DEL/api/latest/projects/{projectKey}/webhooks/{webhookId}

curl

Node.js

Java

Python

PHP

1
2

curl --request DELETE \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks/{webhookId}'

GET

Get last webhook invocation details

Get the latest invocations for a specific webhook.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

webhookId

string

Required

Query parameters

event

string

outcome

string

Responses

A webhook invocation dataset.

application/json;charset=UTF-8

RestDetailedInvocation

GET/api/latest/projects/{projectKey}/webhooks/{webhookId}/latest

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks/{webhookId}/latest' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get webhook statistics

Get the statistics for a specific webhook.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

webhookId

string

Required

Query parameters

event

string

Responses

A webhook invocation dataset.

application/json;charset=UTF-8

RestInvocationHistory

GET/api/latest/projects/{projectKey}/webhooks/{webhookId}/statistics

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks/{webhookId}/statistics' \
  --header 'Accept: application/json;charset=UTF-8'

GET

Get webhook statistics summary

Get the statistics summary for a specific webhook.

The authenticated user must have PROJECT_ADMIN permission for the specified project to call this resource.

Request

Path parameters

projectKey

string

Required

webhookId

string

Required

Responses

A webhook invocation dataset.

application/json;charset=UTF-8

RestInvocationHistory

GET/api/latest/projects/{projectKey}/webhooks/{webhookId}/statistics/summary

curl

Node.js

Java

Python

PHP

1
2
3

curl --request GET \
  --url 'http://{baseurl}/rest/api/latest/projects/{projectKey}/webhooks/{webhookId}/statistics/summary' \
  --header 'Accept: application/json;charset=UTF-8'