dario_swain/stash-api

REST-ish endpoint for interacting with Stash

Maintainers

Details

github.com/DarioSwain/StashApi

Source

Issues

Installs: 5

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 2

Forks: 0

Open Issues: 0

dev-master 2017-04-22 18:13 UTC

Requires

Requires (Dev)

MIT d5c4c6a6eb5bd711ab59719e682672bd57696efe

apisdkStash API

This package is not auto-updated.

Last update: 2024-04-19 16:50:20 UTC

README

UNSTABLE - under heavy development.

About

Auto-generated PHP client for Stash API. Was generated using APIMATIC, based on Stash official WADL definition.

Getting started

How to Build

The generated code has dependencies over external libraries like UniRest. These dependencies are defined in the composer.json file that comes with the SDK. To resolve these dependencies, we use the Composer package manager which requires PHP greater than 5.3.2 installed in your system. Visit https://getcomposer.org/download/ to download the installer file for Composer and run it in your system. Open command prompt and type composer --version. This should display the current version of the Composer installed if the installation was successful.

  • Using command line, navigate to the directory containing the generated files (including composer.json) for the SDK.
  • Run the command composer install. This should install all the required dependencies and create the vendor directory in your project directory.

Building SDK - Step 1

[For Windows Users Only] Configuring CURL Certificate Path in php.ini

CURL used to include a list of accepted CAs, but no longer bundles ANY CA certs. So by default it will reject all SSL certificates as unverifiable. You will have to get your CA's cert and point curl at it. The steps are as follows:

  1. Download the certificate bundle (.pem file) from https://curl.haxx.se/docs/caextract.html on to your system.
  2. Add curl.cainfo = "PATH_TO/cacert.pem" to your php.ini file located in your php installation. “PATH_TO” must be an absolute path containing the .pem file.
[curl]
; A default value for the CURLOPT_CAINFO option. This is required to be an
; absolute path.
;curl.cainfo =

How to Use

The following section explains how to use the StashAPILib library in a new project.

1. Open Project in an IDE

Open an IDE for PHP like PhpStorm. The basic workflow presented here is also applicable if you prefer using a different editor or IDE.

Open project in PHPStorm - Step 1

Click on Open in PhpStorm to browse to your generated SDK directory and then click OK.

Open project in PHPStorm - Step 2

2. Add a new Test Project

Create a new directory by right clicking on the solution name as shown below:

Add a new project in PHPStorm - Step 1

Name the directory as "test"

Add a new project in PHPStorm - Step 2

Add a PHP file to this project

Add a new project in PHPStorm - Step 3

Name it "testSDK"

Add a new project in PHPStorm - Step 4

Depending on your project setup, you might need to include composer's autoloader in your PHP code to enable auto loading of classes.

require_once "../vendor/autoload.php";

It is important that the path inside require_once correctly points to the file autoload.php inside the vendor directory created during dependency installations.

Add a new project in PHPStorm - Step 4

After this you can add code to initialize the client library and acquire the instance of a Controller class. Sample code to initialize the client library and using controller methods is given in the subsequent sections.

3. Run the Test Project

To run your project you must set the Interpreter for your project. Interpreter is the PHP engine installed on your computer.

Open Settings from File menu.

Run Test Project - Step 1

Select PHP from within Languages & Frameworks

Run Test Project - Step 2

Browse for Interpreters near the Interpreter option and choose your interpreter.

Run Test Project - Step 3

Once the interpreter is selected, click OK

Run Test Project - Step 4

To run your project, right click on your PHP file inside your Test project and click on Run

Run Test Project - Step 5

How to Test

Unit tests in this SDK can be run using PHPUnit.

  1. First install the dependencies using composer including the require-dev dependencies.
  2. Run vendor\bin\phpunit --verbose from commandline to execute tests. If you have installed PHPUnit globally, run tests using phpunit --verbose instead.

You can change the PHPUnit test configuration in the phpunit.xml file.

Initialization

Authentication

In order to setup authentication and initialization of the API client, you need the following information.

Parameter Description
stashDomain TODO: add a description
basicAuthUserName The username to use with basic authentication
basicAuthPassword The password to use with basic authentication

API client can be initialized as following.

// Configuration parameters and credentials
$stashDomain = "stashDomain";
$basicAuthUserName = "basicAuthUserName"; // The username to use with basic authentication
$basicAuthPassword = "basicAuthPassword"; // The password to use with basic authentication

$client = new StashAPILib\StashAPILibClient($stashDomain, $basicAuthUserName, $basicAuthPassword);

Class Reference

List of Controllers

Class: RepositoryController

Get singleton instance

The singleton instance of the RepositoryController class can be accessed from the API Client.

$repository = $client->getRepository();

Method: getRepositoryCommitChanges

Retrieve a page of changes made in a specified commit.

Note: The implementation will apply a hard cap ({@code page.max.changes}) and it is not possible to request subsequent content when that cap is exceeded.

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

function getRepositoryCommitChanges(
        $projectKey,
        $repositorySlug,
        $commitId,
        $since = null,
        $withComments = true)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required the commit to retrieve changes for
since Optional the commit to which until should be compared to produce a page of changes. 
                 If not specified the commit's first parent is assumed (if one exists) |

| withComments | Optional DefaultValue | {@code true} to apply comment counts in the changes (the default); otherwise, {@code false} to stream changes without comment counts |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$since = 'since';
$withComments = true;

$result = $repository->getRepositoryCommitChanges($projectKey, $repositorySlug, $commitId, $since, $withComments);

Method: getRepositoryCompareDiffByPath

Gets a diff of the changes available in the {@code from} changeset but not in the {@code to} changeset.

If either the {@code from} or {@code to} changeset are not specified, they will be replaced by the default branch of their containing repository. 

function getRepositoryCompareDiffByPath(
        $projectKey,
        $repositorySlug,
        $path,
        $from = null,
        $to = null,
        $fromRepo = null,
        $srcPath = null,
        $contextLines = -1,
        $whitespace = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
path Required the path to the file to diff (optional)
from Optional the source changeset (can be a partial/full changeset id or qualified/unqualified ref name)
to Optional the target changeset (can be a partial/full changeset id or qualified/unqualified ref name)
fromRepo Optional an optional parameter specifying the source repository containing the source changeset 
             if that changeset is not present in the current repository; the repository can be specified
             by either its ID <em>fromRepo=42</em> or by its project key plus its repo slug separated by
             a slash: <em>fromRepo=projectKey/repoSlug</em> |

| srcPath | Optional | TODO: Add a parameter description | | contextLines | Optional DefaultValue | an optional number of context lines to include around each added or removed lines in the diff | | whitespace | Optional | an optional whitespace flag which can be set to ignore-all |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$path = 'path';
$from = 'from';
$to = 'to';
$fromRepo = 'fromRepo';
$srcPath = 'srcPath';
$contextLines = -1;
$whitespace = 'whitespace';

$result = $repository->getRepositoryCompareDiffByPath($projectKey, $repositorySlug, $path, $from, $to, $fromRepo, $srcPath, $contextLines, $whitespace);

Method: getRepositoryCompareChanges

Gets the file changes available in the {@code from} changeset but not in the {@code to} changeset.

If either the {@code from} or {@code to} changeset are not specified, they will be replaced by the default branch of their containing repository. 

function getRepositoryCompareChanges(
        $projectKey,
        $repositorySlug,
        $from = null,
        $to = null,
        $fromRepo = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
from Optional the source changeset (can be a partial/full changeset id or qualified/unqualified ref name)
to Optional the target changeset (can be a partial/full changeset id or qualified/unqualified ref name)
fromRepo Optional an optional parameter specifying the source repository containing the source changeset 
             if that changeset is not present in the current repository; the repository can be specified
             by either its ID <em>fromRepo=42</em> or by its project key plus its repo slug separated by
             a slash: <em>fromRepo=projectKey/repoSlug</em> |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$from = 'from';
$to = 'to';
$fromRepo = 'fromRepo';

$result = $repository->getRepositoryCompareChanges($projectKey, $repositorySlug, $from, $to, $fromRepo);

Method: getRepositoryCompareCommits

Gets the commits accessible from the {@code from} changeset but not in the {@code to} changeset.

If either the {@code from} or {@code to} changeset are not specified, they will be replaced by the default branch of their containing repository. 

function getRepositoryCompareCommits(
        $projectKey,
        $repositorySlug,
        $from = null,
        $to = null,
        $fromRepo = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
from Optional the source changeset (can be a partial/full changeset id or qualified/unqualified ref name)
to Optional the target changeset (can be a partial/full changeset id or qualified/unqualified ref name)
fromRepo Optional an optional parameter specifying the source repository containing the source changeset 
             if that changeset is not present in the current repository; the repository can be specified
             by either its ID <em>fromRepo=42</em> or by its project key plus its repo slug separated by
             a slash: <em>fromRepo=projectKey/repoSlug</em> |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$from = 'from';
$to = 'to';
$fromRepo = 'fromRepo';

$result = $repository->getRepositoryCompareCommits($projectKey, $repositorySlug, $from, $to, $fromRepo);

Method: getRepositoryBranches

Retrieve the branches matching the supplied filterText param.

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

function getRepositoryBranches(
        $projectKey,
        $repositorySlug,
        $base = null,
        $details = null,
        $filterText = null,
        $orderBy = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
base Optional base branch or tag to compare each branch to (for the metadata providers that uses that information)
details Optional whether to retrieve plugin-provided metadata about each branch
filterText Optional the text to match on
orderBy Optional ordering of refs either ALPHABETICAL (by name) or MODIFICATION (last updated)

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$base = 'base';
$details = false;
$filterText = 'filterText';
$orderBy = 'orderBy';

$result = $repository->getRepositoryBranches($projectKey, $repositorySlug, $base, $details, $filterText, $orderBy);

Method: getRepositoryDefaultBranch

Get the default branch of the repository.

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

function getRepositoryDefaultBranch(
        $projectKey,
        $repositorySlug)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';

$result = $repository->getRepositoryDefaultBranch($projectKey, $repositorySlug);

Method: updateSetRepositoryDefaultBranch

Update the default branch of a repository.

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

function updateSetRepositoryDefaultBranch(
        $dynamic,
        $projectKey,
        $repositorySlug)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';

$result = $repository->updateSetRepositoryDefaultBranch($dynamic, $projectKey, $repositorySlug);

Method: updateSetRepositoryPermissionForGroup

Promote or demote a group's permission level for the specified repository. Available repository permissions are:

  • REPO_READ
  • REPO_WRITE
  • REPO_ADMIN
See the Stash documentation for a detailed explanation of what each permission entails.

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

function updateSetRepositoryPermissionForGroup(
        $projectKey,
        $repositorySlug,
        $permission = null,
        $name = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
permission Optional the permission to grant
name Optional the names of the groups

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$permission = 'permission';
$name = 'name';

$result = $repository->updateSetRepositoryPermissionForGroup($projectKey, $repositorySlug, $permission, $name);

Method: getRepositoryGroupsWithAnyPermission

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

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

function getRepositoryGroupsWithAnyPermission(
        $projectKey,
        $repositorySlug,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$filter = 'filter';

$result = $repository->getRepositoryGroupsWithAnyPermission($projectKey, $repositorySlug, $filter);

Method: deleteRevokeRepositoryPermissionsForGroup

Revoke all permissions for the specified repository for a group.

The authenticated user must have REPO_ADMIN permission for the specified repository or a higher project or 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. 

function deleteRevokeRepositoryPermissionsForGroup(
        $projectKey,
        $repositorySlug,
        $name = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
name Optional the name of the group

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$name = 'name';

$result = $repository->deleteRevokeRepositoryPermissionsForGroup($projectKey, $repositorySlug, $name);

Method: updateSetRepositoryPermissionForUser

Promote or demote a user's permission level for the specified repository. Available repository permissions are:

  • REPO_READ
  • REPO_WRITE
  • REPO_ADMIN
See the Stash documentation for a detailed explanation of what each permission entails.

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

function updateSetRepositoryPermissionForUser(
        $projectKey,
        $repositorySlug,
        $name = null,
        $permission = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
name Optional the names of the users
permission Optional the permission to grant

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$name = 'name';
$permission = 'permission';

$result = $repository->updateSetRepositoryPermissionForUser($projectKey, $repositorySlug, $name, $permission);

Method: getRepositoryUsersWithAnyPermission

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

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

function getRepositoryUsersWithAnyPermission(
        $projectKey,
        $repositorySlug,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$filter = 'filter';

$result = $repository->getRepositoryUsersWithAnyPermission($projectKey, $repositorySlug, $filter);

Method: deleteRevokeRepositoryPermissionsForUser

Revoke all permissions for the specified repository for a user.

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

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

function deleteRevokeRepositoryPermissionsForUser(
        $projectKey,
        $repositorySlug,
        $name = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
name Optional the name of the user

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$name = 'name';

$result = $repository->deleteRevokeRepositoryPermissionsForUser($projectKey, $repositorySlug, $name);

Method: getRepositoryGroupsWithoutAnyPermission

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

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

function getRepositoryGroupsWithoutAnyPermission(
        $projectKey,
        $repositorySlug,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$filter = 'filter';

$result = $repository->getRepositoryGroupsWithoutAnyPermission($projectKey, $repositorySlug, $filter);

Method: getRepositoryUsersWithoutPermission

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

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

function getRepositoryUsersWithoutPermission(
        $projectKey,
        $repositorySlug,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$filter = 'filter';

$result = $repository->getRepositoryUsersWithoutPermission($projectKey, $repositorySlug, $filter);

Method: getRepositoryCommits

Retrieve a page of commits from a given starting commit or "between" two commits. If no explicit commit is specified, the tip of the repository's default branch is assumed. commits may be identified by branch or tag name or by ID. A path may be supplied to restrict the returned commits to only those which affect that path.

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

function getRepositoryCommits(
        $projectKey,
        $repositorySlug,
        $path = null,
        $since = null,
        $until = null,
        $withCounts = false)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
path Optional an optional path to filter commits by
since Optional the commit ID or ref (exclusively) to retrieve commits after
until Optional the commit ID (SHA1) or ref (inclusively) to retrieve commits before
withCounts Optional DefaultValue optionally include the total number of commits and total number of unique authors

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$path = 'path';
$since = 'since';
$until = 'until';
$withCounts = false;

$result = $repository->getRepositoryCommits($projectKey, $repositorySlug, $path, $since, $until, $withCounts);

Method: getRepositoryCommit

Retrieve a single commit identified by its ID>. In general, that ID is a SHA1. From 2.11, ref names like "refs/heads/master" are no longer accepted by this resource.

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

function getRepositoryCommit(
        $projectKey,
        $repositorySlug,
        $commitId,
        $path = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required the commit ID to retrieve
path Optional an optional path to filter the commit by. If supplied the details returned may not 
         be for the specified commit. Instead, starting from the specified commit, they will be the
         details for the first commit affecting the specified path. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$path = 'path';

$result = $repository->getRepositoryCommit($projectKey, $repositorySlug, $commitId, $path);

Method: getRepositoryTags

Retrieve the tags matching the supplied filterText param.

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

function getRepositoryTags(
        $projectKey,
        $repositorySlug,
        $filterText = null,
        $orderBy = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
filterText Optional the text to match on
orderBy Optional ordering of refs either ALPHABETICAL (by name) or MODIFICATION (last updated)

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$filterText = 'filterText';
$orderBy = 'orderBy';

$result = $repository->getRepositoryTags($projectKey, $repositorySlug, $filterText, $orderBy);

Method: getRepositories

Retrieve a page of repositories based on query parameters that control the search. See the documentation of the parameters for more details.

This resource is anonymously accessible.

Note on permissions. In absence of the {@code permission} query parameter the implicit 'read' permission is assumed. Please note that this permission is lower than the REPO_READ permission rather than being equal to it. The implicit 'read' permission for a given repository is assigned to any user that has any of the higher permissions, such as REPO_READ, as well as to anonymous users if the repository is marked as public. The important implication of the above is that an anonymous request to this resource with a permission level REPO_READ is guaranteed to receive an empty list of repositories as a result. For anonymous requests it is therefore recommended to not specify the permission parameter at all. 

function getRepositories(
        $name = null,
        $projectname = null,
        $permission = null,
        $visibility = null)

Parameters

Parameter Tags Description
name Optional (optional) if specified, this will limit the resulting repository list to ones whose name 
                matches this parameter's value. The match will be done case-insensitive and any leading
                and/or trailing whitespace characters on the <code>name</code> parameter will be stripped. |

| projectname | Optional | (optional) if specified, this will limit the resulting repository list to ones whose project's name matches this parameter's value. The match will be done case-insensitive and any leading and/or trailing whitespace characters on the projectname parameter will be stripped. | | permission | Optional | (optional) if specified, it must be a valid repository permission level name and will limit the resulting repository list to ones that the requesting user has the specified permission level to. If not specified, the default implicit 'read' permission level will be assumed. The currently supported explicit permission values are REPO_READ, REPO_WRITE and REPO_ADMIN. | | visibility | Optional | (optional) if specified, this will limit the resulting repository list based on the repositories visibility. Valid values are public or private. |

Example Usage

$name = 'name';
$projectname = 'projectname';
$permission = 'permission';
$visibility = 'visibility';

$result = $repository->getRepositories($name, $projectname, $permission, $visibility);

Method: listRepositoryFiles

Retrieve a page of files from particular directory of a repository. The search is done recursively, so all files from any sub-directory of the specified directory will be returned.

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

function listRepositoryFiles(
        $projectKey,
        $repositorySlug,
        $at = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
at Optional the changeset id or ref (e.g. a branch or tag) to list the files at. 
         If not specified the default branch will be used instead. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$at = 'at';

$result = $repository->listRepositoryFiles($projectKey, $repositorySlug, $at);

Method: listRepositoryFilesByPath

Retrieve a page of files from particular directory of a repository. The search is done recursively, so all files from any sub-directory of the specified directory will be returned.

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

function listRepositoryFilesByPath(
        $projectKey,
        $repositorySlug,
        $path,
        $at = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
path Required the directory to list files for.
at Optional the changeset id or ref (e.g. a branch or tag) to list the files at. 
         If not specified the default branch will be used instead. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$path = 'path';
$at = 'at';

$result = $repository->listRepositoryFilesByPath($projectKey, $repositorySlug, $path, $at);

Method: createRepository

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 PROJECT_ADMIN permission for the context project to call this resource. 

function createRepository(
        $dynamic,
        $projectKey)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required the parent project key

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';

$result = $repository->createRepository($dynamic, $projectKey);

Method: deleteRepository

Schedule the repository matching the supplied projectKey and repositorySlug to be deleted. If the request repository is not present

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

function deleteRepository(
        $repositorySlug,
        $projectKey)

Parameters

Parameter Tags Description
repositorySlug Required the repository slug
projectKey Required the parent project key

Example Usage

$repositorySlug = 'repositorySlug';
$projectKey = 'projectKey';

$result = $repository->deleteRepository($repositorySlug, $projectKey);

Method: createForkRepository

Create a new repository forked from an existing repository.

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

  • {@code "name":"Fork name"} - Specifies the forked repository's name
    • Defaults to the name of the origin repository if not specified
  • {@code "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. 

function createForkRepository(
        $dynamic,
        $repositorySlug,
        $projectKey)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
repositorySlug Required the repository slug
projectKey Required the parent project key

Example Usage

$dynamic = array('key' => 'value');
$repositorySlug = 'repositorySlug';
$projectKey = 'projectKey';

$result = $repository->createForkRepository($dynamic, $repositorySlug, $projectKey);

Method: getRepository

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. 

function getRepository(
        $repositorySlug,
        $projectKey)

Parameters

Parameter Tags Description
repositorySlug Required the repository slug
projectKey Required the parent project key

Example Usage

$repositorySlug = 'repositorySlug';
$projectKey = 'projectKey';

$result = $repository->getRepository($repositorySlug, $projectKey);

Method: updateRepository

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 API can be used to move the repository to a different project by setting the new project in the request, example: {@code {"project":{"key":"NEW_KEY"}}} .

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

function updateRepository(
        $dynamic,
        $repositorySlug,
        $projectKey)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
repositorySlug Required the repository slug
projectKey Required the parent project key

Example Usage

$dynamic = array('key' => 'value');
$repositorySlug = 'repositorySlug';
$projectKey = 'projectKey';

$result = $repository->updateRepository($dynamic, $repositorySlug, $projectKey);

Method: getForkedRepositories

Retrieve repositories which have been forked from this one. Unlike {@link #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. 

function getForkedRepositories(
        $projectKey,
        $repositorySlug)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';

$result = $repository->getForkedRepositories($projectKey, $repositorySlug);

Method: getRelatedRepositories

Retrieve repositories which are related to this one. Related repositories are from the same {@link 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. 

function getRelatedRepositories(
        $projectKey,
        $repositorySlug)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';

$result = $repository->getRelatedRepositories($projectKey, $repositorySlug);

Method: createRetryCreateRepository

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. 

function createRetryCreateRepository(
        $projectKey,
        $repositorySlug)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';

$result = $repository->createRetryCreateRepository($projectKey, $repositorySlug);

Method: getRepositoryShowDiff

Retrieve the diff for a specified file path between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the segments, hunks and diffs substructures in the returned JSON response.

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

function getRepositoryShowDiff(
        $projectKey,
        $repositorySlug,
        $contextLines = -1,
        $since = null,
        $srcPath = null,
        $until = null,
        $whitespace = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
contextLines Optional DefaultValue the number of context lines to include around added/removed lines in the diff
since Optional the base revision to diff from. If omitted the parent revision of the until revision is used
srcPath Optional the source path for the file, if it was copied, moved or renamed
until Optional the target revision to diff to (required)
whitespace Optional optional whitespace flag which can be set to ignore-all

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$contextLines = -1;
$since = 'since';
$srcPath = 'srcPath';
$until = 'until';
$whitespace = 'whitespace';

$result = $repository->getRepositoryShowDiff($projectKey, $repositorySlug, $contextLines, $since, $srcPath, $until, $whitespace);

Method: getRepositoryShowDiffByPath

Retrieve the diff for a specified file path between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the segments, hunks and diffs substructures in the returned JSON response.

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

function getRepositoryShowDiffByPath(
        $projectKey,
        $repositorySlug,
        $path,
        $contextLines = -1,
        $since = null,
        $srcPath = null,
        $until = null,
        $whitespace = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
path Required the path to the file which should be diffed (required)
contextLines Optional DefaultValue the number of context lines to include around added/removed lines in the diff
since Optional the base revision to diff from. If omitted the parent revision of the until revision is used
srcPath Optional the source path for the file, if it was copied, moved or renamed
until Optional the target revision to diff to (required)
whitespace Optional optional whitespace flag which can be set to ignore-all

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$path = 'path';
$contextLines = -1;
$since = 'since';
$srcPath = 'srcPath';
$until = 'until';
$whitespace = 'whitespace';

$result = $repository->getRepositoryShowDiffByPath($projectKey, $repositorySlug, $path, $contextLines, $since, $srcPath, $until, $whitespace);

Method: getRepositoryContent

Retrieve a page of content for a file path at a specified revision.

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

function getRepositoryContent(
        $projectKey,
        $repositorySlug,
        $at = null,
        $type = false,
        $blame = null,
        $noContent = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
at Optional the changeset id or ref to retrieve the content for.
type Optional DefaultValue if true only the type will be returned for the file path instead of the contents.
blame Optional if present the blame will be returned for the file as well.
noContent Optional if present and used with blame only the blame is retrieved instead of the contents.

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$at = 'at';
$type = false;
$blame = 'blame';
$noContent = 'noContent';

$result = $repository->getRepositoryContent($projectKey, $repositorySlug, $at, $type, $blame, $noContent);

Method: getRepositoryContentByPath

Retrieve a page of content for a file path at a specified revision.

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

function getRepositoryContentByPath(
        $projectKey,
        $repositorySlug,
        $path,
        $at = null,
        $type = false,
        $blame = null,
        $noContent = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
path Required the file path to retrieve content from
at Optional the changeset id or ref to retrieve the content for.
type Optional DefaultValue if true only the type will be returned for the file path instead of the contents.
blame Optional if present the blame will be returned for the file as well.
noContent Optional if present and used with blame only the blame is retrieved instead of the contents.

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$path = 'path';
$at = 'at';
$type = false;
$blame = 'blame';
$noContent = 'noContent';

$result = $repository->getRepositoryContentByPath($projectKey, $repositorySlug, $path, $at, $type, $blame, $noContent);

Method: createRepositoryCommitComment

Add a new comment.

Comments can be added in a few places by setting different attributes:

General commit comment: 

     {
         "text": "An insightful general comment on a commit."
     }

Reply to a comment:

     {
         "text": "A measured reply.",
         "parent": {
             "id": 1
         }
     }

General file comment:

     {
         "text": "An insightful general comment on a file.",
         "anchor": {
             "path": "path/to/file",
             "srcPath": "path/to/file"
         }
     }

File line comment:

     {
         "text": "A pithy comment on a particular line within a file.",
         "anchor": {
             "line": 1,
             "lineType": "CONTEXT",
             "fileType": "FROM"
             "path": "path/to/file",
             "srcPath": "path/to/file"
     }
     }

Note: general file comments are an experimental feature and may change in the near future!

For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves).

For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:

  • 'ADDED' - for an added line;
  • 'REMOVED' - for a removed line; or
  • 'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
  • 'FROM' - the source file of the diff
  • 'TO' - the destination file of the diff
If the current user is not a participant the user is added as one and updated to watch the commit.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource. 

function createRepositoryCommitComment(
        $dynamic,
        $projectKey,
        $repositorySlug,
        $commitId,
        $since = null)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required TODO: Add a parameter description
since Optional TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$since = 'since';

$result = $repository->createRepositoryCommitComment($dynamic, $projectKey, $repositorySlug, $commitId, $since);

Method: getRepositoryCommitComments

TODO: Add a method description

function getRepositoryCommitComments(
        $projectKey,
        $repositorySlug,
        $commitId,
        $path = null,
        $since = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required TODO: Add a parameter description
path Optional TODO: Add a parameter description
since Optional TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$path = 'path';
$since = 'since';

$result = $repository->getRepositoryCommitComments($projectKey, $repositorySlug, $commitId, $path, $since);

Method: updateRepositoryCommitComment

Update the text of a comment. Only the user who created a comment may update it.

Note: the supplied supplied JSON object must contain a version that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource. 

function updateRepositoryCommitComment(
        $dynamic,
        $projectKey,
        $repositorySlug,
        $commitId,
        $commentId)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required the full {@link Changeset#getId() ID} of the commit within the repository
commentId Required the ID of the comment to retrieve

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$commentId = 51;

$result = $repository->updateRepositoryCommitComment($dynamic, $projectKey, $repositorySlug, $commitId, $commentId);

Method: deleteRepositoryCommitComment

Delete a commit comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users. Comments which have replies may not be deleted, regardless of the user's granted permissions.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource. 

function deleteRepositoryCommitComment(
        $projectKey,
        $repositorySlug,
        $commitId,
        $commentId,
        $version = -1)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required the full {@link Changeset#getId() ID} of the commit within the repository
commentId Required the ID of the comment to retrieve
version Optional DefaultValue The expected version of the comment. This must match the server's version of the comment or 
              the delete will fail. To determine the current version of the comment, the comment should be
              fetched from the server prior to the delete. Look for the 'version' attribute in the returned
              JSON structure. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$commentId = 51;
$version = -1;

$result = $repository->deleteRepositoryCommitComment($projectKey, $repositorySlug, $commitId, $commentId, $version);

Method: getRepositoryCommitComment

Retrieves a commit discussion comment.

The authenticated user must have REPO_READ permission for the repository that the commit is in to call this resource. 

function getRepositoryCommitComment(
        $projectKey,
        $repositorySlug,
        $commitId,
        $commentId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required the full {@link Changeset#getId() ID} of the commit within the repository
commentId Required the ID of the comment to retrieve

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$commentId = 51;

$result = $repository->getRepositoryCommitComment($projectKey, $repositorySlug, $commitId, $commentId);

Method: getRepositoryHooks

Retrieve a page of repository hooks for this repository.

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

function getRepositoryHooks(
        $projectKey,
        $repositorySlug,
        $type = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
type Optional the optional type to filter by. Valid values are PRE_RECEIVE or POST_RECEIVE

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$type = 'type';

$result = $repository->getRepositoryHooks($projectKey, $repositorySlug, $type);

Method: updateSetRepositoryHookSettings

Modify the settings for a repository hook for this repositories.

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

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

function updateSetRepositoryHookSettings(
        $dynamic,
        $projectKey,
        $repositorySlug,
        $hookKey)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
hookKey Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$hookKey = 'hookKey';

$result = $repository->updateSetRepositoryHookSettings($dynamic, $projectKey, $repositorySlug, $hookKey);

Method: getRepositoryHookSettings

Retrieve the settings for a repository hook for this repositories.

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

function getRepositoryHookSettings(
        $projectKey,
        $repositorySlug,
        $hookKey)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
hookKey Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$hookKey = 'hookKey';

$result = $repository->getRepositoryHookSettings($projectKey, $repositorySlug, $hookKey);

Method: getRepositoryHook

Retrieve a repository hook for this repositories.

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

function getRepositoryHook(
        $projectKey,
        $repositorySlug,
        $hookKey)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
hookKey Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$hookKey = 'hookKey';

$result = $repository->getRepositoryHook($projectKey, $repositorySlug, $hookKey);

Method: updateEnableRepositoryHook

Enable a repository hook for this repositories and optionally applying new configuration.

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

function updateEnableRepositoryHook(
        $projectKey,
        $repositorySlug,
        $hookKey,
        $contentLength = 0)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
hookKey Required TODO: Add a parameter description
contentLength Optional DefaultValue TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$hookKey = 'hookKey';
$contentLength = 0;

$result = $repository->updateEnableRepositoryHook($projectKey, $repositorySlug, $hookKey, $contentLength);

Method: deleteDisableRepositoryHook

Disable a repository hook for this repositories.

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

function deleteDisableRepositoryHook(
        $projectKey,
        $repositorySlug,
        $hookKey)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
hookKey Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$hookKey = 'hookKey';

$result = $repository->deleteDisableRepositoryHook($projectKey, $repositorySlug, $hookKey);

Method: getRepositoryChanges

Retrieve a page of changes made in a specified commit.

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

function getRepositoryChanges(
        $projectKey,
        $repositorySlug,
        $since = null,
        $until = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
since Optional the commit to which until should be compared to produce a page of changes. 
                 If not specified the commit's first parent is assumed (if one exists) |

| until | Optional | the commit to retrieve changes for |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$since = 'since';
$until = 'until';

$result = $repository->getRepositoryChanges($projectKey, $repositorySlug, $since, $until);

Method: deleteUnwatchRepositoryCommit

Removes the authenticated user as a watcher for the specified commit.

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

function deleteUnwatchRepositoryCommit(
        $projectKey,
        $repositorySlug,
        $commitId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required the full {@link Changeset#getId() ID} of the commit within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';

$result = $repository->deleteUnwatchRepositoryCommit($projectKey, $repositorySlug, $commitId);

Method: createWatchRepositoryCommit

Adds the authenticated user as a watcher for the specified commit.

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

function createWatchRepositoryCommit(
        $projectKey,
        $repositorySlug,
        $commitId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required the full {@link Changeset#getId() ID} of the commit within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';

$result = $repository->createWatchRepositoryCommit($projectKey, $repositorySlug, $commitId);

Method: getRepositoryCommitDiff

Retrieve the diff between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the segments, hunks and diffs substructures in the returned JSON response.

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

function getRepositoryCommitDiff(
        $projectKey,
        $repositorySlug,
        $commitId,
        $contextLines = -1,
        $since = null,
        $srcPath = null,
        $whitespace = null,
        $withComments = true)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
commitId Required TODO: Add a parameter description
contextLines Optional DefaultValue the number of context lines to include around added/removed lines in the diff
since Optional the base revision to diff from. If omitted the parent revision of the until revision is used
srcPath Optional the source path for the file, if it was copied, moved or renamed
whitespace Optional optional whitespace flag which can be set to ignore-all
withComments Optional DefaultValue true to embed comments in the diff (the default); otherwise false 
                 to stream the diff without comments |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$commitId = 'commitId';
$contextLines = -1;
$since = 'since';
$srcPath = 'srcPath';
$whitespace = 'whitespace';
$withComments = true;

$result = $repository->getRepositoryCommitDiff($projectKey, $repositorySlug, $commitId, $contextLines, $since, $srcPath, $whitespace, $withComments);

Method: getRepositoryCommitDiffByPath

Retrieve the diff between two provided revisions.

Note: This resource is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded. In the event that the cap is reached, the diff will be cut short and one or more truncated flags will be set to true on the segments, hunks and diffs substructures in the returned JSON response.

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

function getRepositoryCommitDiffByPath(
        $projectKey,
        $repositorySlug,
        $path,
        $commitId,
        $contextLines = -1,
        $since = null,
        $srcPath = null,
        $whitespace = null,
        $withComments = true)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
path Required the path to the file which should be diffed (optional)
commitId Required TODO: Add a parameter description
contextLines Optional DefaultValue the number of context lines to include around added/removed lines in the diff
since Optional the base revision to diff from. If omitted the parent revision of the until revision is used
srcPath Optional the source path for the file, if it was copied, moved or renamed
whitespace Optional optional whitespace flag which can be set to ignore-all
withComments Optional DefaultValue true to embed comments in the diff (the default); otherwise false 
                 to stream the diff without comments |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$path = 'path';
$commitId = 'commitId';
$contextLines = -1;
$since = 'since';
$srcPath = 'srcPath';
$whitespace = 'whitespace';
$withComments = true;

$result = $repository->getRepositoryCommitDiffByPath($projectKey, $repositorySlug, $path, $commitId, $contextLines, $since, $srcPath, $whitespace, $withComments);

Method: getRepositories1

Retrieve repositories from the project corresponding to the supplied projectKey.

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

function getRepositories1($projectKey)

Parameters

Parameter Tags Description
projectKey Required the parent project key

Example Usage

$projectKey = 'projectKey';

$result = $repository->getRepositories1($projectKey);

Back to List of Controllers

Class: AdminController

Get singleton instance

The singleton instance of the AdminController class can be accessed from the API Client.

$admin = $client->getAdmin();

Method: getClusterInformation

Gets information about the nodes that currently make up the stash cluster.

The authenticated user must have the SYS_ADMIN permission to call this resource. 

function getClusterInformation()

Example Usage

$result = $admin->getClusterInformation();

Method: updateLicense

Decodes the provided encoded license and sets it as the active license. If no license was provided, a 400 is returned. If the license cannot be decoded, or cannot be applied, a 409 is returned. Some possible reasons a license may not be applied include:

  • It is for a different product
  • It is already expired
Otherwise, if the license is updated successfully, details for the new license are returned with a 200 response.

Warning: It is possible to downgrade the license during update, applying a license with a lower number of permitted users. If the number of currently-licensed users exceeds the limits of the new license, pushing will be disabled until the licensed user count is brought into compliance with the new license.

The authenticated user must have SYS_ADMIN permission. ADMIN users may view the current license details, but they may not update the license. 

function updateLicense($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->updateLicense($dynamic);

Method: deleteMailConfig

Deletes the current mail configuration.

The authenticated user must have the SYS_ADMIN permission to call this resource. 

function deleteMailConfig()

Example Usage

$result = $admin->deleteMailConfig();

Method: getMailConfig

Retrieves the current mail configuration.

The authenticated user must have the SYS_ADMIN permission to call this resource.

function getMailConfig()

Example Usage

$result = $admin->getMailConfig();

Method: updateSetMailConfig

Updates the mail configuration

The authenticated user must have the SYS_ADMIN permission to call this resource.

function updateSetMailConfig($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->updateSetMailConfig($dynamic);

Method: deleteClearSenderAddress

Clears the server email address.

The authenticated user must have the ADMIN permission to call this resource. 

function deleteClearSenderAddress()

Example Usage

$result = $admin->deleteClearSenderAddress();

Method: getSenderAddress

Retrieves the server email address

function getSenderAddress()

Example Usage

$result = $admin->getSenderAddress();

Method: updateSetSenderAddress

Updates the server email address

The authenticated user must have the ADMIN permission to call this resource.

function updateSetSenderAddress($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->updateSetSenderAddress($dynamic);

Method: getUsersWithoutAnyPermission

Retrieve a page of users that have no granted global permissions.

The authenticated user must have ADMIN permission or higher to call this resource. 

function getUsersWithoutAnyPermission($filter = null)

Parameters

Parameter Tags Description
filter Optional if specified only user names containing the supplied string will be returned

Example Usage

$filter = 'filter';

$result = $admin->getUsersWithoutAnyPermission($filter);

Method: getGroupsWithAnyPermission

Retrieve a page of groups that have been granted at least one global permission.

The authenticated user must have ADMIN permission or higher to call this resource. 

function getGroupsWithAnyPermission($filter = null)

Parameters

Parameter Tags Description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$filter = 'filter';

$result = $admin->getGroupsWithAnyPermission($filter);

Method: updateSetPermissionForGroups

Promote or demote a user's global permission level. Available global permissions are:

  • LICENSED_USER
  • PROJECT_CREATE
  • ADMIN
  • SYS_ADMIN
See the Stash documentation for a detailed explanation of what each permission entails.

The authenticated user must have:

  • ADMIN permission or higher; and
  • the permission they are attempting to grant or higher; and
  • greater or equal permissions than the current permission level of the group (a user may not demote the permission level of a group with higher permissions than them)
to call this resource. In addition, a user may not demote a group's permission level if their own permission level would be reduced as a result. 
function updateSetPermissionForGroups(
        $permission = null,
        $name = null)

Parameters

Parameter Tags Description
permission Optional the permission to grant
name Optional the names of the groups

Example Usage

$permission = 'permission';
$name = 'name';

$result = $admin->updateSetPermissionForGroups($permission, $name);

Method: deleteRevokePermissionsForGroup

Revoke all global permissions for a group.

The authenticated user must have:

  • ADMIN permission or higher; and
  • greater or equal permissions than the current permission level of the group (a user may not demote the permission level of a group with higher permissions than them)
to call this resource. In addition, a user may not revoke a group's permissions if their own permission level would be reduced as a result. 
function deleteRevokePermissionsForGroup($name = null)

Parameters

Parameter Tags Description
name Optional the name of the group

Example Usage

$name = 'name';

$result = $admin->deleteRevokePermissionsForGroup($name);

Method: getGroupsWithoutAnyPermission

Retrieve a page of groups that have no granted global permissions.

The authenticated user must have ADMIN permission or higher to call this resource. 

function getGroupsWithoutAnyPermission($filter = null)

Parameters

Parameter Tags Description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$filter = 'filter';

$result = $admin->getGroupsWithoutAnyPermission($filter);

Method: getUsersWithAnyPermission

Retrieve a page of users that have been granted at least one global permission.

The authenticated user must have ADMIN permission or higher to call this resource. 

function getUsersWithAnyPermission($filter = null)

Parameters

Parameter Tags Description
filter Optional if specified only user names containing the supplied string will be returned

Example Usage

$filter = 'filter';

$result = $admin->getUsersWithAnyPermission($filter);

Method: updateSetPermissionForUsers

Promote or demote the global permission level of a user. Available global permissions are:

  • LICENSED_USER
  • PROJECT_CREATE
  • ADMIN
  • SYS_ADMIN
See the Stash documentation for a detailed explanation of what each permission entails.

The authenticated user must have:

  • ADMIN permission or higher; and
  • the permission they are attempting to grant; and
  • greater or equal permissions than the current permission level of the user (a user may not demote the permission level of a user with higher permissions than them)
to call this resource. In addition, a user may not demote their own permission level. 
function updateSetPermissionForUsers(
        $name = null,
        $permission = null)

Parameters

Parameter Tags Description
name Optional the names of the users
permission Optional the permission to grant

Example Usage

$name = 'name';
$permission = 'permission';

$result = $admin->updateSetPermissionForUsers($name, $permission);

Method: deleteRevokePermissionsForUser

Revoke all global permissions for a user.

The authenticated user must have:

  • ADMIN permission or higher; and
  • greater or equal permissions than the current permission level of the user (a user may not demote the permission level of a user with higher permissions than them)
to call this resource. In addition, a user may not demote their own permission level. 
function deleteRevokePermissionsForUser($name = null)

Parameters

Parameter Tags Description
name Optional the name of the user

Example Usage

$name = 'name';

$result = $admin->deleteRevokePermissionsForUser($name);

Method: getUsers

Retrieve a page of users.

The authenticated user must have the LICENSED_USER permission to call this resource. 

function getUsers($filter = null)

Parameters

Parameter Tags Description
filter Optional if specified only users with usernames, display name or email addresses containing the supplied 
           string will be returned |

Example Usage

$filter = 'filter';

$result = $admin->getUsers($filter);

Method: createUser

Creates a new user from the assembled query parameters.

The default group can be used to control initial permissions for new users, such as granting users the ability to login or providing read access to certain projects or repositories. If the user is not added to the default group, they may not be able to login after their account is created until explicit permissions are configured.

The authenticated user must have the ADMIN permission to call this resource. 

function createUser(
        $name = null,
        $password = null,
        $displayName = null,
        $emailAddress = null,
        $addToDefaultGroup = true,
        $notify = null)

Parameters

Parameter Tags Description
name Optional the username for the new user
password Optional the password for the new user
displayName Optional the display name for the new user
emailAddress Optional the e-mail address for the new user
addToDefaultGroup Optional DefaultValue true to add the user to the default group, which can be used to grant them 
                      a set of initial permissions; otherwise, <code>false</code> to not add them to a group |

| notify | Optional | if present and not false instead of requiring a password, the create user will be notified via email their account has been created and requires a password to be reset. This option can only be used if a mail server has been configured |

Example Usage

$name = 'name';
$password = 'password';
$displayName = 'displayName';
$emailAddress = 'emailAddress';
$addToDefaultGroup = true;
$notify = 'notify';

$result = $admin->createUser($name, $password, $displayName, $emailAddress, $addToDefaultGroup, $notify);

Method: deleteUser

Deletes the specified user, removing them from the system. This also removes any permissions that may have been granted to the user.

A user may not delete themselves, and a user with ADMIN permissions may not delete a user with SYS_ADMINpermissions.

The authenticated user must have the ADMIN permission to call this resource. 

function deleteUser($name = null)

Parameters

Parameter Tags Description
name Optional the username identifying the user to delete

Example Usage

$name = 'name';

$result = $admin->deleteUser($name);

Method: updateUserDetails

Update a user's details.

The authenticated user must have the ADMIN permission to call this resource. 

function updateUserDetails($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->updateUserDetails($dynamic);

Method: createRenameUser

Rename a user.

The authenticated user must have the ADMIN permission to call this resource. 

function createRenameUser($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->createRenameUser($dynamic);

Method: deleteClearUserCaptchaChallenge

Clears any CAPTCHA challenge that may constrain the user with the supplied username when they authenticate. Additionally any counter or metric that contributed towards the user being issued the CAPTCHA challenge (for instance too many consecutive failed logins) will also be reset.

The authenticated user must have the ADMIN permission to call this resource, and may not clear the CAPTCHA of a user with greater permissions than themselves. 

function deleteClearUserCaptchaChallenge($name = null)

Parameters

Parameter Tags Description
name Optional TODO: Add a parameter description

Example Usage

$name = 'name';

$result = $admin->deleteClearUserCaptchaChallenge($name);

Method: deleteGroup

Deletes the specified group, removing them from the system. This also removes any permissions that may have been granted to the group.

A user may not delete the last group that is granting them administrative permissions, or a group with greater permissions than themselves.

The authenticated user must have the ADMIN permission to call this resource. 

function deleteGroup($name = null)

Parameters

Parameter Tags Description
name Optional the name identifying the group to delete

Example Usage

$name = 'name';

$result = $admin->deleteGroup($name);

Method: createGroup

Create a new group.

The authenticated user must have ADMIN permission or higher to call this resource. 

function createGroup($name = null)

Parameters

Parameter Tags Description
name Optional Name of the group.

Example Usage

$name = 'name';

$result = $admin->createGroup($name);

Method: getGroups

Retrieve a page of groups.

The authenticated user must have LICENSED_USER permission or higher to call this resource. 

function getGroups($filter = null)

Parameters

Parameter Tags Description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$filter = 'filter';

$result = $admin->getGroups($filter);

Method: addUserToGroup

Deprecated since 2.10 for removal in 4.0. Use {@code /rest/users/add-groups} instead.

Add a user to a group.

In the request entity, the context attribute is the group and the itemName is the user.

The authenticated user must have the ADMIN permission to call this resource. 

function addUserToGroup($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->addUserToGroup($dynamic);

Method: addGroupToUser

Deprecated since 2.10 for removal in 4.0. Use {@code /rest/users/add-groups} instead.

Add a user to a group. This is very similar to groups/add-user, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.

In the request entity, the context attribute is the user and the itemName is the group.

The authenticated user must have the ADMIN permission to call this resource. 

function addGroupToUser($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->addGroupToUser($dynamic);

Method: addUsersToGroup

Add multiple users to a group.

The authenticated user must have the ADMIN permission to call this resource. 

function addUsersToGroup($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->addUsersToGroup($dynamic);

Method: addUserToGroups

Add a user to one or more groups.

The authenticated user must have the ADMIN permission to call this resource. 

function addUserToGroups($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->addUserToGroups($dynamic);

Method: createRemoveUserFromGroup

Deprecated since 2.10 for removal in 3.0. Use {@code /rest/users/remove-groups} instead.

Remove a user from a group.

The authenticated user must have the ADMIN permission to call this resource.

In the request entity, the context attribute is the group and the itemName is the user. 

function createRemoveUserFromGroup($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->createRemoveUserFromGroup($dynamic);

Method: createRemoveGroupFromUser

Remove a user from a group. This is very similar to groups/remove-user, but with the context and itemName attributes of the supplied request entity reversed. On the face of it this may appear redundant, but it facilitates a specific UI component in Stash.

In the request entity, the context attribute is the user and the itemName is the group.

The authenticated user must have the ADMIN permission to call this resource. 

function createRemoveGroupFromUser($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->createRemoveGroupFromUser($dynamic);

Method: findUsersInGroup

Retrieves a list of users that are members of a specified group.

The authenticated user must have the LICENSED_USER permission to call this resource. 

function findUsersInGroup(
        $context = null,
        $filter = null)

Parameters

Parameter Tags Description
context Optional the group which should be used to locate members
filter Optional if specified only users with usernames, display names or email addresses containing the 
              supplied string will be returned |

Example Usage

$context = 'context';
$filter = 'filter';

$result = $admin->findUsersInGroup($context, $filter);

Method: findUsersNotInGroup

Retrieves a list of users that are not members of a specified group.

The authenticated user must have the LICENSED_USER permission to call this resource. 

function findUsersNotInGroup(
        $context = null,
        $filter = null)

Parameters

Parameter Tags Description
context Optional the group which should be used to locate non-members
filter Optional if specified only users with usernames, display names or email addresses containing the 
              supplied string will be returned |

Example Usage

$context = 'context';
$filter = 'filter';

$result = $admin->findUsersNotInGroup($context, $filter);

Method: findGroupsForUser

Retrieves a list of groups the specified user is a member of.

The authenticated user must have the LICENSED_USER permission to call this resource. 

function findGroupsForUser(
        $context = null,
        $filter = null)

Parameters

Parameter Tags Description
context Optional the user which should be used to locate groups
filter Optional if specified only groups with names containing the supplied string will be returned

Example Usage

$context = 'context';
$filter = 'filter';

$result = $admin->findGroupsForUser($context, $filter);

Method: findOtherGroupsForUser

Retrieves a list of groups the specified user is not a member of.

The authenticated user must have the LICENSED_USER permission to call this resource. 

function findOtherGroupsForUser(
        $context = null,
        $filter = null)

Parameters

Parameter Tags Description
context Optional the user which should be used to locate groups
filter Optional if specified only groups with names containing the supplied string will be returned

Example Usage

$context = 'context';
$filter = 'filter';

$result = $admin->findOtherGroupsForUser($context, $filter);

Method: updateUserPassword

Update a user's password.

The authenticated user must have the ADMIN permission to call this resource, and may not update the password of a user with greater permissions than themselves. 

function updateUserPassword($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $admin->updateUserPassword($dynamic);

Method: getLicense

Retrieves details about the current license, as well as the current status of the system with regards to the installed license. The status includes the current number of users applied toward the license limit, as well as any status messages about the license (warnings about expiry or user counts exceeding license limits).

The authenticated user must have ADMIN permission. Unauthenticated users, and non-administrators, are not permitted to access license details. 

function getLicense()

Example Usage

$result = $admin->getLicense();

Back to List of Controllers

Class: PullRequestController

Get singleton instance

The singleton instance of the PullRequestController class can be accessed from the API Client.

$pullRequest = $client->getPullRequest();

Method: deleteUnwatchPullRequest

Make the authenticated user stop watching the specified pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function deleteUnwatchPullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;

$result = $pullRequest->deleteUnwatchPullRequest($projectKey, $repositorySlug, $pullRequestId);

Method: createWatchPullRequest

Make the authenticated user watch the specified pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function createWatchPullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;

$result = $pullRequest->createWatchPullRequest($projectKey, $repositorySlug, $pullRequestId);

Method: getPullRequestDiff

Streams a diff within a pull request.

If the specified file has been copied, moved or renamed, the srcPath must also be specified to produce the correct diff.

Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getPullRequestDiff(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $contextLines = -1,
        $srcPath = null,
        $whitespace = null,
        $withComments = true)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description
contextLines Optional DefaultValue the number of context lines to include around added/removed lines in the diff
srcPath Optional the previous path to the file, if the file has been copied, moved or renamed
whitespace Optional optional whitespace flag which can be set to ignore-all
withComments Optional DefaultValue true to embed comments in the diff (the default); otherwise, false 
                 to stream the diff without comments |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 'pullRequestId';
$contextLines = -1;
$srcPath = 'srcPath';
$whitespace = 'whitespace';
$withComments = true;

$result = $pullRequest->getPullRequestDiff($projectKey, $repositorySlug, $pullRequestId, $contextLines, $srcPath, $whitespace, $withComments);

Method: getPullRequestDiffByPath

Streams a diff within a pull request.

If the specified file has been copied, moved or renamed, the srcPath must also be specified to produce the correct diff.

Note: This RESTful endpoint is currently not paged. The server will internally apply a hard cap to the streamed lines, and it is not possible to request subsequent pages if that cap is exceeded.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getPullRequestDiffByPath(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $path,
        $contextLines = -1,
        $srcPath = null,
        $whitespace = null,
        $withComments = true)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description
path Required the path to the file which should be diffed (optional)
contextLines Optional DefaultValue the number of context lines to include around added/removed lines in the diff
srcPath Optional the previous path to the file, if the file has been copied, moved or renamed
whitespace Optional optional whitespace flag which can be set to ignore-all
withComments Optional DefaultValue true to embed comments in the diff (the default); otherwise, false 
                 to stream the diff without comments |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 'pullRequestId';
$path = 'path';
$contextLines = -1;
$srcPath = 'srcPath';
$whitespace = 'whitespace';
$withComments = true;

$result = $pullRequest->getPullRequestDiffByPath($projectKey, $repositorySlug, $pullRequestId, $path, $contextLines, $srcPath, $whitespace, $withComments);

Method: getPullRequestCommits

Retrieve changesets for the specified pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getPullRequestCommits(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $withCounts = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description
withCounts Optional if set to true, the service will add "authorCount" and "totalCount" at the end of the page. 
                 "authorCount" is the number of different authors and "totalCount" is the total number of changesets. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$withCounts = true;

$result = $pullRequest->getPullRequestCommits($projectKey, $repositorySlug, $pullRequestId, $withCounts);

Method: getPullRequestTasks

Retrieve the tasks associated with a pull request.

function getPullRequestTasks(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 'pullRequestId';

$result = $pullRequest->getPullRequestTasks($projectKey, $repositorySlug, $pullRequestId);

Method: getCountPullRequestTasks

Retrieve the total number of {@link com.atlassian.stash.task.TaskState#OPEN open} and {@link com.atlassian.stash.task.TaskState#RESOLVED resolved} tasks associated with a pull request.

function getCountPullRequestTasks(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 'pullRequestId';

$result = $pullRequest->getCountPullRequestTasks($projectKey, $repositorySlug, $pullRequestId);

Method: createPullRequestComment

Add a new comment.

Comments can be added in a few places by setting different attributes:

General pull request comment: 

     {
         "text": "An insightful general comment on a pull request."
     }

Reply to a comment:

     {
         "text": "A measured reply.",
         "parent": {
             "id": 1
         }
     }

General file comment:

     {
         "text": "An insightful general comment on a file.",
         "anchor": {
             "path": "path/to/file",
             "srcPath": "path/to/file"
         }
     }

File line comment:

     {
         "text": "A pithy comment on a particular line within a file.",
         "anchor": {
             "line": 1,
             "lineType": "CONTEXT",
             "fileType": "FROM"
             "path": "path/to/file",
             "srcPath": "path/to/file"
         }
     }

Note: general file comments are an experimental feature and may change in the near future!

For file and line comments, 'path' refers to the path of the file to which the comment should be applied and 'srcPath' refers to the path the that file used to have (only required for copies and moves).

For line comments, 'line' refers to the line in the diff that the comment should apply to. 'lineType' refers to the type of diff hunk, which can be:

  • 'ADDED' - for an added line;
  • 'REMOVED' - for a removed line; or
  • 'CONTEXT' - for a line that was unmodified but is in the vicinity of the diff.
'fileType' refers to the file of the diff to which the anchor should be attached - which is of relevance when displaying the diff in a side-by-side way. Currently the supported values are:
  • 'FROM' - the source file of the diff
  • 'TO' - the destination file of the diff
If the current user is not a participant the user is added as a watcher of the pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function createPullRequestComment(
        $dynamic,
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;

$result = $pullRequest->createPullRequestComment($dynamic, $projectKey, $repositorySlug, $pullRequestId);

Method: getPullRequestComments

TODO: Add a method description

function getPullRequestComments(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $path = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description
path Optional TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$path = 'path';

$result = $pullRequest->getPullRequestComments($projectKey, $repositorySlug, $pullRequestId, $path);

Method: updatePullRequestComment

Update the text of a comment. Only the user who created a comment may update it.

Note: the supplied supplied JSON object must contain a version that must match the server's version of the comment or the update will fail. To determine the current version of the comment, the comment should be fetched from the server prior to the update. Look for the 'version' attribute in the returned JSON structure.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function updatePullRequestComment(
        $dynamic,
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $commentId)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository
commentId Required the id of the comment to retrieve

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$commentId = 234;

$result = $pullRequest->updatePullRequestComment($dynamic, $projectKey, $repositorySlug, $pullRequestId, $commentId);

Method: deletePullRequestComment

Delete a pull request comment. Anyone can delete their own comment. Only users with REPO_ADMIN and above may delete comments created by other users.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function deletePullRequestComment(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $commentId,
        $version = -1)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository
commentId Required the id of the comment to retrieve
version Optional DefaultValue The expected version of the comment. This must match the server's version of the comment or 
                  the delete will fail. To determine the current version of the comment, the comment should be
                  fetched from the server prior to the delete. Look for the 'version' attribute in the
                  returned JSON structure. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$commentId = 234;
$version = -1;

$result = $pullRequest->deletePullRequestComment($projectKey, $repositorySlug, $pullRequestId, $commentId, $version);

Method: getPullRequestComment

Retrieves a pull request comment.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getPullRequestComment(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $commentId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository
commentId Required the id of the comment to retrieve

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$commentId = 234;

$result = $pullRequest->getPullRequestComment($projectKey, $repositorySlug, $pullRequestId, $commentId);

Method: getPullRequestChanges

Gets changes for the specified PullRequest.

Note: This resource is currently not paged. The server will return at most one page. The server will truncate the number of changes to either the request's page limit or an internal maximum, whichever is smaller. The start parameter of the page request is also ignored.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getPullRequestChanges(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $withComments = true)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description
withComments Optional DefaultValue {@code true} to apply comment counts in the changes (the default); otherwise, {@code false} 
                 to stream changes without comment counts |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 'pullRequestId';
$withComments = true;

$result = $pullRequest->getPullRequestChanges($projectKey, $repositorySlug, $pullRequestId, $withComments);

Method: getPullRequests

Retrieve a page of pull requests to or from the specified repository.

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

Optionally clients can specify PR participant filters. Each filter has a mandatory {@code username.N} parameter, and the optional {@code role.N} and {@code approved.N} parameters.

  • {@code username.N} - the "root" of a single participant filter, where "N" is a natural number starting from 1. This allows clients to specify multiple participant filters, by providing consecutive filters as {@code username.1}, {@code username.2} etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of participant filters is 10 and all filters exceeding that limit will be dropped.
  • {@code role.N}(optional) the role associated with {@code username.N}. This must be one of {@code AUTHOR}, {@code REVIEWER}, or{@code PARTICIPANT}
  • {@code approved.N}(optional) the approved status associated with {@code username.N}. That is whether {@code username.N} has approved the PR. Either {@code true}, or {@code false} 
function getPullRequests(
        $projectKey,
        $repositorySlug,
        $direction = 'incoming',
        $at = null,
        $state = null,
        $order = null,
        $withAttributes = true,
        $withProperties = true)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
direction Optional DefaultValue (optional, defaults to INCOMING) the direction relative to the specified 
              repository. Either <strong>INCOMING</strong> or <strong>OUTGOING</strong>. |

| at | Optional | (optional) a fully-qualified branch ID to find pull requests to or from, such as {@code refs/heads/master} | | state | Optional | (optional, defaults to OPEN). Supply ALL to return pull request in any state. If a state is supplied only pull requests in the specified state will be returned. Either OPEN, DECLINED or MERGED. | | order | Optional | (optional) the order to return pull requests in, either OLDEST (as in: "oldest first") or NEWEST. | | withAttributes | Optional DefaultValue | (optional) defaults to true, whether to return additional pull request attributes | | withProperties | Optional DefaultValue | (optional) defaults to true, whether to return additional pull request properties |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$direction = 'incoming';
$at = 'at';
$state = 'state';
$order = 'order';
$withAttributes = true;
$withProperties = true;

$result = $pullRequest->getPullRequests($projectKey, $repositorySlug, $direction, $at, $state, $order, $withAttributes, $withProperties);

Errors

Error Code Error Description
400 The request was malformed.
401 The currently authenticated user has insufficient permissions to view the specified pull request.
404 The specified repository or pull request does not exist.
0 Something goes wrong.

Method: createDeclinePullRequest

Decline a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function createDeclinePullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $version = -1)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description
version Optional DefaultValue the current version of the pull request. If the server's version isn't the same as the specified 
            version the operation will fail. To determine the current version of the pull request it should be
            fetched from the server prior to this operation. Look for the 'version' attribute in the returned
            JSON structure. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$version = -1;

$result = $pullRequest->createDeclinePullRequest($projectKey, $repositorySlug, $pullRequestId, $version);

Method: getPullRequestActivities

Retrieve a page of activity associated with a pull request.

Activity items include comments, approvals, rescopes (i.e. adding and removing of commits), merges and more.

Different types of activity items may be introduced in newer versions of Stash or by user installed plugins, so clients should be flexible enough to handle unexpected entity shapes in the returned page.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getPullRequestActivities(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $fromId = null,
        $fromType = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository
fromId Optional (optional) the id of the activity item to use as the first item in the returned page
fromType Optional (required if fromId is present) the type of the activity item specified by 
             <strong>fromId</strong> (either <strong>COMMENT</strong> or <strong>ACTIVITY</strong>) |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$fromId = 234;
$fromType = 'fromType';

$result = $pullRequest->getPullRequestActivities($projectKey, $repositorySlug, $pullRequestId, $fromId, $fromType);

Method: createReopenPullRequest

Re-open a declined pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function createReopenPullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $version = -1)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository
version Optional DefaultValue the current version of the pull request. If the server's version isn't the same as the specified 
            version the operation will fail. To determine the current version of the pull request it should be
            fetched from the server prior to this operation. Look for the 'version' attribute in the returned
            JSON structure. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$version = -1;

$result = $pullRequest->createReopenPullRequest($projectKey, $repositorySlug, $pullRequestId, $version);

Method: getCanMergePullRequest

Test whether a pull request can be merged.

A pull request may not be merged if:

  • there are conflicts that need to be manually resolved before merging; and/or
  • one or more merge checks have vetoed the merge.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getCanMergePullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;

$result = $pullRequest->getCanMergePullRequest($projectKey, $repositorySlug, $pullRequestId);

Method: createMergePullRequest

Merge the specified pull request.

The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource. 

function createMergePullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $version = -1)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository
version Optional DefaultValue the current version of the pull request. If the server's version isn't the same as the specified 
            version the operation will fail. To determine the current version of the pull request it should be
            fetched from the server prior to this operation. Look for the 'version' attribute in the returned
            JSON structure. |

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$version = -1;

$result = $pullRequest->createMergePullRequest($projectKey, $repositorySlug, $pullRequestId, $version);

Method: getPullRequest

Retrieve a pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function getPullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 'pullRequestId';

$result = $pullRequest->getPullRequest($projectKey, $repositorySlug, $pullRequestId);

Method: updatePullRequest

Update the title, description, reviewers or destination branch of an existing pull request.

Note: the reviewers list may be updated using this resource. However the author and participants list may not.

The authenticated user must either:

  • be the author of the pull request and have the REPO_READ permission for the repository that this pull request targets; or
  • have the REPO_WRITE permission for the repository that this pull request targets
to call this resource. 
function updatePullRequest(
        $dynamic,
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 'pullRequestId';

$result = $pullRequest->updatePullRequest($dynamic, $projectKey, $repositorySlug, $pullRequestId);

Method: createAssignPullRequestParticipantRole

Assigns a participant to an explicit role in pull request. Currently only the REVIEWER role may be assigned.

If the user is not yet a participant in the pull request, they are made one and assigned the supplied role.

If the user is already a participant in the pull request, their previous role is replaced with the supplied role unless they are already assigned the AUTHOR role which cannot be changed and will result in a Bad Request (400) response code.

The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource. 

function createAssignPullRequestParticipantRole(
        $dynamic,
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;

$result = $pullRequest->createAssignPullRequestParticipantRole($dynamic, $projectKey, $repositorySlug, $pullRequestId);

Method: deleteUnassignPullRequestParticipantRole

Unassigns a participant from the REVIEWER role they may have been given in a pull request.

If the participant has no explicit role this method has no effect.

Afterwards, the user will still remain a participant in the pull request but their role will be reduced to PARTICIPANT. This is because once made a participant of a pull request, a user will forever remain a participant. Only their role may be altered.

The authenticated user must have REPO_WRITE permission for the repository that this pull request targets to call this resource. 

function deleteUnassignPullRequestParticipantRole(
        $projectKey,
        $repositorySlug,
        $pullRequestId,
        $username = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository
username Optional the participant's user name

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;
$username = 'username';

$result = $pullRequest->deleteUnassignPullRequestParticipantRole($projectKey, $repositorySlug, $pullRequestId, $username);

Method: listPullRequestParticipants

Retrieves a page of the participants for a given pull request.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function listPullRequestParticipants(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;

$result = $pullRequest->listPullRequestParticipants($projectKey, $repositorySlug, $pullRequestId);

Method: createApprovePullRequest

Approve a pull request as the current user. Implicitly adds the user as a participant if they are not already.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function createApprovePullRequest(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 234;

$result = $pullRequest->createApprovePullRequest($projectKey, $repositorySlug, $pullRequestId);

Method: deleteWithdrawPullRequestApproval

Remove approval from a pull request as the current user. This does not remove the user as a participant.

The authenticated user must have REPO_READ permission for the repository that this pull request targets to call this resource. 

function deleteWithdrawPullRequestApproval(
        $projectKey,
        $repositorySlug,
        $pullRequestId)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description
pullRequestId Required the id of the pull request within the repository

Example Usage

$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';
$pullRequestId = 192;

$result = $pullRequest->deleteWithdrawPullRequestApproval($projectKey, $repositorySlug, $pullRequestId);

Method: createPullRequest

Create a new pull request between two branches. The branches may be in the same repository, or different ones. When using different repositories, they must still be in the same {@link Repository#getHierarchyId() hierarchy}.

The authenticated user must have REPO_READ permission for the "from" and "to"repositories to call this resource. 

function createPullRequest(
        $pullRequest,
        $projectKey,
        $repositorySlug)

Parameters

Parameter Tags Description
pullRequest Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description
repositorySlug Required TODO: Add a parameter description

Example Usage

$pullRequest = new PullRequest();
$projectKey = 'projectKey';
$repositorySlug = 'repositorySlug';

$result = $pullRequest->createPullRequest($pullRequest, $projectKey, $repositorySlug);

Errors

Error Code Error Description
400 The pull request entity supplied in the request was malformed.
401 The currently authenticated user has insufficient permissions to create a pull request between the two specified repositories.
404 One of the specified repositories or branches does not exist.
409 One of the following error cases occurred (check the error message for more details): There was a problem resolving one or more reviewers. The specified branches were the same. The to branch is already up-to-date with all the commits on the from branch. A pull request between the two branches already exists.
0 Something goes wrong.

Back to List of Controllers

Class: HookController

Get singleton instance

The singleton instance of the HookController class can be accessed from the API Client.

$hook = $client->getHook();

Method: getAvatar

Retrieve the avatar for the project matching the supplied moduleKey.

function getAvatar(
        $hookKey,
        $version = null)

Parameters

Parameter Tags Description
hookKey Required the complete module key of the hook module
version Optional optional version used for HTTP caching only - any non-blank version will result in a large max-age Cache-Control header. 
            Note that this does not affect the Last-Modified header. |

Example Usage

$hookKey = 'hookKey';
$version = 'version';

$result = $hook->getAvatar($hookKey, $version);

Back to List of Controllers

Class: ProjectController

Get singleton instance

The singleton instance of the ProjectController class can be accessed from the API Client.

$project = $client->getProject();

Method: getProjectGroupsWithAnyPermission

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. 

function getProjectGroupsWithAnyPermission(
        $projectKey,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$filter = 'filter';

$result = $project->getProjectGroupsWithAnyPermission($projectKey, $filter);

Method: updateSetProjectPermissionForGroups

Promote or demote a group's permission level for the specified project. Available project permissions are:

  • PROJECT_READ
  • PROJECT_WRITE
  • PROJECT_ADMIN
See the Stash documentation for a detailed explanation of what each permission entails.

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 their own permission level would be reduced as a result. 

function updateSetProjectPermissionForGroups(
        $projectKey,
        $permission = null,
        $name = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
permission Optional the permission to grant
name Optional the names of the groups

Example Usage

$projectKey = 'projectKey';
$permission = 'permission';
$name = 'name';

$result = $project->updateSetProjectPermissionForGroups($projectKey, $permission, $name);

Method: deleteRevokeProjectPermissionsForGroup

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. 

function deleteRevokeProjectPermissionsForGroup(
        $projectKey,
        $name = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
name Optional the name of the group

Example Usage

$projectKey = 'projectKey';
$name = 'name';

$result = $project->deleteRevokeProjectPermissionsForGroup($projectKey, $name);

Method: getProjectGroupsWithoutAnyPermission

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 global permission to call this resource. 

function getProjectGroupsWithoutAnyPermission(
        $projectKey,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$filter = 'filter';

$result = $project->getProjectGroupsWithoutAnyPermission($projectKey, $filter);

Method: getProjectUsersWithAnyPermission

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. 

function getProjectUsersWithAnyPermission(
        $projectKey,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$filter = 'filter';

$result = $project->getProjectUsersWithAnyPermission($projectKey, $filter);

Method: updateSetProjectPermissionForUsers

Promote or demote a user's permission level for the specified project. Available project permissions are:

  • PROJECT_READ
  • PROJECT_WRITE
  • PROJECT_ADMIN
See the Stash documentation for a detailed explanation of what each permission entails.

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. 

function updateSetProjectPermissionForUsers(
        $projectKey,
        $name = null,
        $permission = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
name Optional the names of the users
permission Optional the permission to grant

Example Usage

$projectKey = 'projectKey';
$name = 'name';
$permission = 'permission';

$result = $project->updateSetProjectPermissionForUsers($projectKey, $name, $permission);

Method: deleteRevokeProjectPermissionsForUser

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. 

function deleteRevokeProjectPermissionsForUser(
        $projectKey,
        $name = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
name Optional the name of the user

Example Usage

$projectKey = 'projectKey';
$name = 'name';

$result = $project->deleteRevokeProjectPermissionsForUser($projectKey, $name);

Method: getProjectUsersWithoutPermission

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. 

function getProjectUsersWithoutPermission(
        $projectKey,
        $filter = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$projectKey = 'projectKey';
$filter = 'filter';

$result = $project->getProjectUsersWithoutPermission($projectKey, $filter);

Method: getHasProjectAllUserPermission

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

  • PROJECT_READ
  • PROJECT_WRITE
  • PROJECT_ADMIN

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

function getHasProjectAllUserPermission(
        $projectKey,
        $permission)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
permission Required the permission to grant

Example Usage

$projectKey = 'projectKey';
$permission = 'permission';

$result = $project->getHasProjectAllUserPermission($projectKey, $permission);

Method: modifyProjectAllUserPermission

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

  • PROJECT_READ
  • PROJECT_WRITE
  • PROJECT_ADMIN

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

function modifyProjectAllUserPermission(
        $projectKey,
        $permission,
        $allow = null)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
permission Required the permission to grant
allow Optional true to grant the specified permission to all users, or false to revoke it

Example Usage

$projectKey = 'projectKey';
$permission = 'permission';
$allow = true;

$result = $project->modifyProjectAllUserPermission($projectKey, $permission, $allow);

Method: createProject

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. 

function createProject($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $project->createProject($dynamic);

Method: getProjects

Retrieve a page of projects.

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

function getProjects(
        $name = null,
        $permission = null)

Parameters

Parameter Tags Description
name Optional TODO: Add a parameter description
permission Optional TODO: Add a parameter description

Example Usage

$name = 'name';
$permission = 'permission';

$result = $project->getProjects($name, $permission);

Method: deleteProject

Delete the project matching the supplied projectKey.

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

function deleteProject($projectKey)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';

$result = $project->deleteProject($projectKey);

Method: updateProject

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. 

function updateProject(
        $dynamic,
        $projectKey)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
projectKey Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$projectKey = 'projectKey';

$result = $project->updateProject($dynamic, $projectKey);

Method: getProject

Retrieve the project matching the supplied projectKey.

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

function getProject($projectKey)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';

$result = $project->getProject($projectKey);

Method: getProjectAvatar

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. 

function getProjectAvatar(
        $projectKey,
        $s = 0)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description
s Optional DefaultValue The desired size of the image. The server will return an image as close as possible to the specified 
         size. |

Example Usage

$projectKey = 'projectKey';
$s = 0;

$result = $project->getProjectAvatar($projectKey, $s);

Method: uploadProjectAvatar

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.

An example curl request to upload an image name 'avatar.png' would be: 

 curl -X POST -u username:password 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. 

function uploadProjectAvatar($projectKey)

Parameters

Parameter Tags Description
projectKey Required TODO: Add a parameter description

Example Usage

$projectKey = 'projectKey';

$result = $project->uploadProjectAvatar($projectKey);

Back to List of Controllers

Class: TaskController

Get singleton instance

The singleton instance of the TaskController class can be accessed from the API Client.

$task = $client->getTask();

Method: createTask

Create a new task.

function createTask($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $task->createTask($dynamic);

Method: deleteTask

Delete a task.

Note that only the task's creator, the context's author or an admin of the context's repository can delete a task. (For a pull request task, those are the task's creator, the pull request's author or an admin on the repository containing the pull request). Additionally a task cannot be deleted if it has already been resolved. 

function deleteTask($taskId)

Parameters

Parameter Tags Description
taskId Required the id identifying the task to delete

Example Usage

$taskId = 192;

$result = $task->deleteTask($taskId);

Method: updateTask

Update a existing task.

As of Stash 3.3, only the state and text of a task can be updated.

Updating the state of a task is allowed for any user having READ access to the repository. However only the task's creator, the context's author or an admin of the context's repository can update the task's text. (For a pull request task, those are the task's creator, the pull request's author or an admin on the repository containing the pull request). Additionally the task's text cannot be updated if it has been resolved. 

function updateTask(
        $dynamic,
        $taskId)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
taskId Required the id identifying the task to delete

Example Usage

$dynamic = array('key' => 'value');
$taskId = 192;

$result = $task->updateTask($dynamic, $taskId);

Method: getTask

Retrieve a existing task.

function getTask($taskId)

Parameters

Parameter Tags Description
taskId Required the id identifying the task to delete

Example Usage

$taskId = 192;

$result = $task->getTask($taskId);

Back to List of Controllers

Class: GroupController

Get singleton instance

The singleton instance of the GroupController class can be accessed from the API Client.

$group = $client->getGroup();

Method: getGroups

Retrieve a page of group names.

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

function getGroups($filter = null)

Parameters

Parameter Tags Description
filter Optional if specified only group names containing the supplied string will be returned

Example Usage

$filter = 'filter';

$result = $group->getGroups($filter);

Back to List of Controllers

Class: ProfileController

Get singleton instance

The singleton instance of the ProfileController class can be accessed from the API Client.

$profile = $client->getProfile();

Method: getProfileRepositoriesRecentlyAccessed

Retrieve a page of recently accessed repositories for the currently authenticated user.

Repositories are ordered from most recently to least recently accessed.

Only authenticated users may call this resource. 

function getProfileRepositoriesRecentlyAccessed($permission = null)

Parameters

Parameter Tags Description
permission Optional (optional) if specified, it must be a valid repository permission level name and will limit 
               the resulting repository list to ones that the requesting user has the specified permission
               level to. If not specified, the default <code>REPO_READ</code> permission level will be assumed. |

Example Usage

$permission = 'permission';

$result = $profile->getProfileRepositoriesRecentlyAccessed($permission);

Back to List of Controllers

Class: ApplicationController

Get singleton instance

The singleton instance of the ApplicationController class can be accessed from the API Client.

$application = $client->getApplication();

Method: getApplicationProperties

Retrieve version information and other application properties.

No authentication is required to call this resource. 

function getApplicationProperties()

Example Usage

$result = $application->getApplicationProperties();

Back to List of Controllers

Class: LogController

Get singleton instance

The singleton instance of the LogController class can be accessed from the API Client.

$log = $client->getLog();

Method: getRootLevel

Retrieve the current log level for the root logger.

The authenticated user must have ADMIN permission or higher to call this resource. 

function getRootLevel()

Example Usage

$result = $log->getRootLevel();

Method: updateSetRootLevel

Set the current log level for the root logger.

The authenticated user must have ADMIN permission or higher to call this resource. 

function updateSetRootLevel($levelName)

Parameters

Parameter Tags Description
levelName Required the level to set the logger to. Either TRACE, DEBUG, INFO, WARN or ERROR

Example Usage

$levelName = 'levelName';

$result = $log->updateSetRootLevel($levelName);

Method: getLevel

Retrieve the current log level for a given logger.

The authenticated user must have ADMIN permission or higher to call this resource. 

function getLevel($loggerName)

Parameters

Parameter Tags Description
loggerName Required the name of the logger.

Example Usage

$loggerName = 'loggerName';

$result = $log->getLevel($loggerName);

Method: updateSetLevel

Set the current log level for a given logger.

The authenticated user must have ADMIN permission or higher to call this resource. 

function updateSetLevel(
        $levelName,
        $loggerName)

Parameters

Parameter Tags Description
levelName Required the level to set the logger to. Either TRACE, DEBUG, INFO, WARN or ERROR
loggerName Required the name of the logger.

Example Usage

$levelName = 'levelName';
$loggerName = 'loggerName';

$result = $log->updateSetLevel($levelName, $loggerName);

Back to List of Controllers

Class: UserController

Get singleton instance

The singleton instance of the UserController class can be accessed from the API Client.

$user = $client->getUser();

Method: getUsers

Retrieve a page of users, optionally run through provided filters.

Only authenticated users may call this resource.

Supported Filters

Filters are provided in query parameters in a standard name=value fashion. The following filters are currently supported:

  • {@code filter} - return only users, whose username, name or email address contain the {@code filter} value
  • {@code permission} - the "root" of a permission filter, whose value must be a valid global, project, or repository permission. Additional filter parameters referring to this filter that specify the resource (project or repository) to apply the filter to must be prefixed with permission.. See the section "Permission Filters" below for more details.
  • {@code permission.N} - the "root" of a single permission filter, similar to the {@code permission} parameter, where "N" is a natural number starting from 1. This allows clients to specify multiple permission filters, by providing consecutive filters as {@code permission.1}, {@code permission.2} etc. Note that the filters numbering has to start with 1 and be continuous for all filters to be processed. The total allowed number of permission filters is 50 and all filters exceeding that limit will be dropped. See the section "Permission Filters" below for more details on how the permission filters are processed.

Permission Filters

The following three sub-sections list parameters supported for permission filters (where [root] is the root permission filter name, e.g. {@code permission}, {@code permission.1} etc.) depending on the permission resource. The system determines which filter to apply (Global, Project or Repository permission) based on the [root] permission value. E.g. {@code ADMIN} is a global permission, {@code PROJECT_ADMIN} is a project permission and {@code REPO_ADMIN} is a repository permission. Note that the parameters for a given resource will be looked up in the order as they are listed below, that is e.g. for a project resource, if both {@code projectId} and {@code projectKey} are provided, the system will use {@code projectId} for the lookup.

Global permissions

The permission value under [root] is the only required and recognized parameter, as global permissions do not apply to a specific resource.

Example valid filter: permission=ADMIN.

Project permissions

  • [root]- specifies the project permission
  • [root].projectId - specifies the project ID to lookup the project by
  • [root].projectKey - specifies the project key to lookup the project by

Example valid filter: permission.1=PROJECT_ADMIN&permission.1.projectKey=TEST_PROJECT.

Repository permissions

  • [root]- specifies the repository permission
  • [root].projectId - specifies the repository ID to lookup the repository by
  • [root].projectKey and [root].repositorySlug- specifies the project key and repository slug to lookup the repository by; both values need to be provided for this look up to be triggered
Example valid filter: permission.2=REPO_ADMIN&permission.2.projectKey=TEST_PROJECT&permission.2.repositorySlug=test_repo. 
function getUsers()

Example Usage

$result = $user->getUsers();

Method: updateUserDetails

Update the currently authenticated user's details. Note that the name attribute is ignored, the update will always be applied to the currently authenticated user.

function updateUserDetails($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $user->updateUserDetails($dynamic);

Method: deleteUserAvatar

Delete the avatar associated to a user.

Users are always allowed to delete their own avatar. To delete someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar. 

function deleteUserAvatar($userSlug)

Parameters

Parameter Tags Description
userSlug Required TODO: Add a parameter description

Example Usage

$userSlug = 'userSlug';

$result = $user->deleteUserAvatar($userSlug);

Method: uploadUserAvatar

Update the avatar for the user with the supplied slug.

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/latest/users/jdoe/avatar.png -F avatar=@avatar.png

Users are always allowed to update their own avatar. To update someone else's avatar the authenticated user must have global ADMIN permission, or global SYS_ADMIN permission to update a SYS_ADMIN user's avatar. 

function uploadUserAvatar($userSlug)

Parameters

Parameter Tags Description
userSlug Required TODO: Add a parameter description

Example Usage

$userSlug = 'userSlug';

$result = $user->uploadUserAvatar($userSlug);

Method: getUser

Retrieve the user matching the supplied userSlug.

function getUser($userSlug)

Parameters

Parameter Tags Description
userSlug Required TODO: Add a parameter description

Example Usage

$userSlug = 'userSlug';

$result = $user->getUser($userSlug);

Method: updateUserPassword

Update the currently authenticated user's password.

function updateUserPassword($dynamic)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');

$result = $user->updateUserPassword($dynamic);

Method: getUserSettings

Retrieve a map of user setting key values for a specific user identified by the user slug.

function getUserSettings($userSlug)

Parameters

Parameter Tags Description
userSlug Required TODO: Add a parameter description

Example Usage

$userSlug = 'userSlug';

$result = $user->getUserSettings($userSlug);

Method: updateUserSettings

Update the entries of a map of user setting key/values for a specific user identified by the user slug.

function updateUserSettings(
        $dynamic,
        $userSlug)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
userSlug Required TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$userSlug = 'userSlug';

$result = $user->updateUserSettings($dynamic, $userSlug);

Back to List of Controllers

Class: MarkupController

Get singleton instance

The singleton instance of the MarkupController class can be accessed from the API Client.

$markup = $client->getMarkup();

Method: createPreviewMarkup

Preview the generated html for given markdown contents.

Only authenticated users may call this resource. 

function createPreviewMarkup(
        $dynamic,
        $urlMode = null,
        $hardwrap = null,
        $htmlEscape = null)

Parameters

Parameter Tags Description
dynamic Required TODO: Add a parameter description
urlMode Optional TODO: Add a parameter description
hardwrap Optional TODO: Add a parameter description
htmlEscape Optional TODO: Add a parameter description

Example Usage

$dynamic = array('key' => 'value');
$urlMode = 'urlMode';
$hardwrap = true;
$htmlEscape = true;

$result = $markup->createPreviewMarkup($dynamic, $urlMode, $hardwrap, $htmlEscape);

Back to List of Controllers