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-11-15 19:22:15 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.

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

                 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

             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

             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

             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

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

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

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

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

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

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

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

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

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

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

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

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

         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

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 , 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 is guaranteed to receive an empty list of repositories as a result. For anonymous requests it is therefore recommended to not specify the parameter at all. 

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

Parameters

                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 , and . | | 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

         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

         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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

              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

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

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

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

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

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

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

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

                 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

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

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

                 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

                 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

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

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

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

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

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

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

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

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

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

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

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

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

           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

                      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

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

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

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

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

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

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

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

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

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

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

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

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

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

              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

              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

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

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

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

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

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

                 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

                 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

                 "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

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

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

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

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

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

                  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

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

                 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

              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

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

            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

             <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

            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

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

            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

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

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

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

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

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

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

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

Example Usage

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

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

Errors

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

            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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

         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

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

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

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

Example Usage

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

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

Method: getTask

Retrieve a existing task.

function getTask($taskId)

Parameters

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

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

               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

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

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

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

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

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

Example Usage

$userSlug = 'userSlug';

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

Method: getUser

Retrieve the user matching the supplied userSlug.

function getUser($userSlug)

Parameters

Example Usage

$userSlug = 'userSlug';

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

Method: updateUserPassword

Update the currently authenticated user's password.

function updateUserPassword($dynamic)

Parameters

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

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

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

Example Usage

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

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

Back to List of Controllers