Documentation | 2025.1

# Projects : Swarm Projects

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

## Get List of Projects

### Summary

Get List of Projects

GET /api/v9/projects/

### Description

Returns a list of projects in Swarm that are visible to the current user. Administrators will see all projects, including private ones.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
fields | An optional comma-separated list (or array) of fields to show for each project. Omitting this parameter or passing an empty value shows all fields. | string | query | No
workflow | An optional parameter to only list projects using a workflow. | string | query | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "project": {
        "id": "jplugin",
        "branches": [],
        "defaults": {
          "reviewers": {
            "users": {
              "allison.clayborne": {
                "required": true
              },
              "jack.boone": [ ],
              "steve.russell": [ ]
            }
          }
        },
        "deleted": false,
        "deploy": {
          "enabled": false,
          "url": ""
        },
        "description": "A Java plugin for continuous integration.",
        "emailFlags": {
          "change_email_project_users": "1",
          "review_email_project_members": "1"
        },
        "jobview": "",
        "members": [
          "allison.clayborne",
          "jack.boone",
          "steve.russell"
        ],
        "minimumUpVotes": 1,
        "name": "JPlugin",
        "owners": [
          "allison.clayborne"
        ],
        "private": false,
        "retainDefaultReviewers": false,
        "subgroups": [ ],
        "tests": {
          "enabled": false,
          "url": "",
          "postBody": "",
          "postFormat": "URL"
        },
        "workflow": null
      },
      "readme":<h1>P4 Plugin</h1>\n<p>Jenkins plugin for a Perforce Helix Versioning Engine (P4D).</p>\n<h2>Contents</h2>\n<ul>\n<li><a href=\"https://github.com/jenkinsci/p4-plugin/blob/main/RELEASE.md\">Release notes</a></li>\n\">
    }

### Example usage

#### Listing projects

To list all projects:

    curl -u "username:password" "https://my-swarm-host/api/v9/projects?fields=id,description,members,name"

Pagination is not currently supported by this endpoint. Swarm responds with a list of all projects:

    HTTP/1.1 200 OK

    {
      "projects": [
        {
          "id": "blue-book",
          "description": "This is a private project for use only by users with sufficient clearance.",
          "members": [
            "alex.randolph",
            "allison.clayborne"
          ],
          "name": "Blue Book"
        },
        {
          "id": "jplugin",
          "description": "A Java plugin for continuous integration.",
          "members": [
            "allison.clayborne",
            "jack.boone",
            "steve.russell"
          ],
          "name": "JPlugin"
        },
        {
          "id": "mercury",
          "description": "Mercury project for code management.",
          "members": [
            "alex.randolph",
            "claire.brevia",
            "jack.boone"
          ],
          "name": "Mercury"
        },
        {
          "id": "test-data",
          "description": "",
          "members": [
            "steve.russell"
          ],
          "name": "Test Data"
        },
        {
          "id": "test-project-for-workflow",
          "description": "This project has been created to test Swarm workflow.",
          "members": [
            "alex.randolph",
            "allison.clayborne",
            "claire.brevia",
            "jack.boone",
            "paula.boyle",
            "steve.russell"
          ],
          "name": "Test project for workflow"
        }
      ]
    }

Project administrators wishing to see the `tests` and `deploy` fields must fetch projects individually.

## Get Project Information

### Summary

Get Project Information

GET /api/v9/projects/{id}

### Description

Retrieve information about a project.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes
fields | An optional comma-separated list (or array) of fields to show for each project. Omitting this parameter or passing an empty value shows all fields. | string | query | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "project": {
        "id": "jplugin",
        "branches": [
          {
            "id": "main",
            "name": "MAIN",
            "workflow": null,
            "paths": [
              "//projects/jplugin/main/..."
            ],
            "defaults": {
              "reviewers": {
                "users": {
                  "steve.russell": [ ]
                }
              }
            },
            "minimumUpVotes": null,
            "retainDefaultReviewers": false,
            "moderators": [
              "claire.brevia"
            ],
            "moderators-groups": [ ]
          },
          {
            "id": "candidate",
            "name": "CANDIDATE",
            "workflow": null,
            "paths": [
              "//projects/jplugin/candidate/..."
            ],
            "defaults": {
              "reviewers": [ ]
            },
            "minimumUpVotes": null,
            "retainDefaultReviewers": false,
            "moderators": [ ],
            "moderators-groups": [ ]
          }
        ],
        "defaults": {
          "reviewers": {
            "users": {
              "allison.clayborne": {
                "required": true
              },
              "jack.boone": [ ],
              "steve.russell": [ ]
            }
          }
        },
        "deleted": false,
        "deploy": {
          "enabled": false,
          "url": ""
        },
        "description": "A Java plugin for continuous integration.",
        "emailFlags": {
          "change_email_project_users": "1",
          "review_email_project_members": "1"
        },
        "jobview": "",
        "members": [
          "allison.clayborne",
          "jack.boone",
          "steve.russell"
        ],
        "minimumUpVotes": 1,
        "name": "JPlugin",
        "owners": [
          "allison.clayborne"
        ],
        "private": false,
        "retainDefaultReviewers": false,
        "subgroups": [ ],
        "tests": {
          "enabled": false,
          "url": "",
          "postBody": "",
          "postFormat": "URL"
        },
        "workflow": null
      },
      "readme":<h1>P4 Plugin</h1>\n<p>Jenkins plugin for a Perforce Helix Versioning Engine (P4D).</p>\n<h2>Contents</h2>\n<ul>\n<li><a href=\"https://github.com/jenkinsci/p4-plugin/blob/main/RELEASE.md\">Release notes</a></li>\n
    }

### Example usage

#### Fetching a project

To fetch an individual project:

    curl -u "username:password" "https://my-swarm-host/api/v9/projects/testproject2?fields=id,description,members,name"

Swarm responds with a project entity:

    HTTP/1.1 200 OK

    {
      "project": {
        "id": "jplugin",
        "description": "A Java plugin for continuous integration.",
        "members": [
          "allison.clayborne",
          "jack.boone",
          "steve.russell"
        ],
        "name": "JPlugin"
      }
    }

Project administrators have access to additional fields (`tests` and `deploy`) when fetching individual projects using this endpoint.

## Create a new Project

### Summary

Create a new Project

POST /api/v9/projects/

### Description

Creates a new project in Swarm.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
name | Project Name (is also used to generate the Project ID) | string | form | Yes
members | An array of project members. | array | form | Yes
subgroups | An optional array of project subgroups. | array | form | No
owners | An optional array of project owners. | array | form | No
description | An optional project description. | string | form | No
private | Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false) | boolean | form | No
deploy | Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"} | array | form | No
tests | Configuration for testing/continuous integration. | array | form | No
branches | Optional branch definitions for this project. | array | form | No
jobview | An optional jobview for associating certain jobs with this project. | string | form | No
emailFlags[change_email_project_users] | Email members, moderators and followers when a change is committed. | boolean | form | No
emailFlags[review_email_project_members] | Email members and moderators when a new review is requested. | boolean | form | No
defaults | An optional array of defaults at a project level (for example default reviewers). | array | form | No
retainDefaultReviewers | An optional to retain the default reviewers. | boolean | form | No
minimumUpVotes | An optional to set the minimum number of up votes required. | string | form | No

### Example responses

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "project": {
        "id": "testproject",
        "branches": [ ],
        "defaults": {
          "reviewers": [ ]
        },
        "deleted": false,
        "deploy": {
          "enabled": false,
          "url": null
        },
        "description": "My project is great",
        "emailFlags": [ ],
        "jobview": null,
        "members": [
          "bruno"
        ],
        "minimumUpVotes": null,
        "name": "testProject",
        "owners": [ ],
        "private": false,
        "retainDefaultReviewers": false,
        "subgroups": [ ],
        "tests": {
          "enabled": false,
          "url": null
        },
        "workflow": null
      },
      "readme": "",
      "mode": "add"
    }

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "project": {
        "id": "project-x",
        "branches": [ ],
        "defaults": {
          "reviewers": {
            "users": {
              "bruno": {
                "required": "1"
              }
            }
          }
        },
        "deleted": false,
        "deploy": {
          "enabled": false,
          "url": null
        },
        "description": "This project is temporary until project Z replaces it",
        "emailFlags": [ ],
        "jobview": null,
        "members": [
          "swarm"
        ],
        "minimumUpVotes": null,
        "name": "project x",
        "owners": [ ],
        "private": false,
        "retainDefaultReviewers": false,
        "subgroups": [ ],
        "tests": {
          "enabled": false,
          "url": null
        },
        "workflow": null
      },
      "readme": "",
      "mode": "add"
    }

### Example usage

#### Creating a new project

To create a project:

    curl -u "username:password" \
         -X POST \
         -d "name=TestProject 3" \
         -d "description=The third iteration of our test project." \
         -d "members[]=alice" \
         -d "members[]=bob" \
         "https://my-swarm-host/api/v9/projects/"

Swarm responds with the new project entity:

    HTTP/1.1 200 OK

    {
      "project": {
        "id": "testproject-3",
        "branches": [ ],
        "defaults": {
          "reviewers": [ ]
        },
        "deleted": false,
        "deploy": {
          "enabled": false,
          "url": null
        },
        "description": "The third iteration of our test project.",
        "emailFlags": [ ],
        "jobview": null,
        "members": [
          "bruno",
          "swarm"
        ],
        "minimumUpVotes": null,
        "name": "TestProject 3",
        "owners": [ ],
        "private": false,
        "retainDefaultReviewers": false,
        "subgroups": [ ],
        "tests": {
          "enabled": false,
          "url": null
        },
        "workflow": null
      },
      "readme": "",
      "mode": "add"
    }

#### Creating a private project with branches

Specifying a branch requires using array notation and providing at least two fields (`name` and `paths`) for each branch you wish to create. Creating more than one branch involves incrementing the `branches[0]` specifier for each branch - an example of this accompanies the PATCH endpoint documentation.

Projects are public by default. To mark a project as private, set the private parameter to true.

    curl -u "username:password" \
         -X POST \
         -d "name=TestProject 4" \
         -d "description=The 4th iteration of our test project." \
         -d "private=true" \
         -d "members[]=bob" \
         -d "branches[0][name]=Branch One" \
         -d "branches[0][paths][]=//depot/main/TestProject/..." \
         "https://my-swarm-host/api/v9/projects"

Swarm responds with the new project entity:

    HTTP/1.1 200 OK

    {
      "project": {
        "id": "testproject-4",
        "branches": [ ],
        "defaults": {
          "reviewers": [ ]
        },
        "deleted": false,
        "deploy": {
          "enabled": false,
          "url": null
        },
        "description": "The 4th iteration of our test project.",
        "emailFlags": [ ],
        "jobview": null,
        "members": [
          "bruno"
        ],
        "minimumUpVotes": null,
        "name": "TestProject 4",
        "owners": [ ],
        "private": true,
        "retainDefaultReviewers": false,
        "subgroups": [ ],
        "tests": {
          "enabled": false,
          "url": null
        },
        "workflow": null
      },
      "readme": "",
      "mode": "add"
    }

## Edit a Project

### Summary

Edit a Project

PATCH /api/v9/projects/{id}

### Description

Change the settings of a project in Swarm. If a project has owners set, only the owners can perform this action.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes
name | Project Name (changing the project name does not change the project ID) | string | form | No
members | An array of project members. | array | form | No
subgroups | An optional array of project subgroups. | array | form | No
owners | An optional array of project owners. | array | form | No
description | Your project description. | string | form | No
private | Private projects are visible only to Members, Moderators, Owners, and Administrators. (Default: false) | boolean | form | No
deploy | Configuration for automated deployment. Example: {"enabled": true, "url": "http://localhost/?change={change}"} | array | form | No
tests | Configuration for testing/continuous integration. | array | form | No
branches | Optional branch definitions for this project. | array | form | No
jobview | A jobview for associating certain jobs with this project. | string | form | No
emailFlags[change_email_project_users] | Email members, moderators and followers when a change is committed. | boolean | form | No
emailFlags[review_email_project_members] | Email members and moderators when a new review is requested. | boolean | form | No
defaults | An optional array of defaults at a project level (for example default reviewers). | array | form | No
retainDefaultReviewers | An optional to retain the default reviewers. | boolean | form | No
minimumUpVotes | An optional to set the minimum number of up votes required. | string | form | No

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "project":{
        "id":"project1",
        "branches":[
          {
            "name":"main",
            "paths":[
              "//depot/dev/APIProject/..."
            ],
            "id":"main",
            "moderators":[ ],
            "moderators-groups":[ ],
            "defaults":{
              "reviewers":[ ]
            },
            "workflow":null,
            "retainDefaultReviewers":false,
            "minimumUpVotes":null
          }
        ],
        "defaults":{
          "reviewers":[ ]
        },
        "deleted":false,
        "deploy":{
          "enabled":false,
          "url":""
        },
        "description":"Updated description",
        "emailFlags":[ ],
        "jobview":"",
        "members":[
          "swarm-admin"
        ],
        "minimumUpVotes":null,
        "name":"API Project",
        "owners":[ ],
        "private":false,
        "retainDefaultReviewers":false,
        "subgroups":[ ],
        "tests":{
          "enabled":false,
          "url":""
        },
        "workflow":null
      },
      "readme":"",
      "mode":"edit"
    }

### Example usage

#### Editing a project

To edit a project:

It is safe to edit a project without specifying branches, but the instructions for adding branches contain important information for modifying branch configuration.

    curl -u "username:password" \
         -X PATCH
         -d "description=Witness the power of a fully operational Swarm project." \
         "https://my-swarm-host/api/v9/projects/jam"

Swarm responds with the updated project entity:

    HTTP/1.1 200 OK

    {
      "project":{
        "id":"jam",
        "branches":[
          {
            "id":"main",
            "name":"Main",
            "workflow":null,
            "paths":[
              "\/\/depot\/Jam\/MAIN\/..."
            ],
            "defaults":{
              "reviewers":[ ]
            },
            "minimumUpVotes":null,
            "retainDefaultReviewers":false,
            "moderators":[ ],
            "moderators-groups":[ ]
          },
          {
            "id":"release-2-1",
            "name":"Release 2.1",
            "workflow":null,
            "paths":[
              "\/\/depot\/Jam\/REL2.1\/..."
            ],
            "defaults":{
              "reviewers":[ ]
            },
            "minimumUpVotes":null,
            "retainDefaultReviewers":false,
            "moderators":[ ],
            "moderators-groups":[ ]
          },
          {
            "id":"release-2-2",
            "name":"Release 2.2",
            "workflow":null,
            "paths":[
              "\/\/depot\/Jam\/REL2.2\/..."
            ],
            "defaults":{
              "reviewers":[ ]
            },
            "minimumUpVotes":null,
            "retainDefaultReviewers":false,
            "moderators":[ ],
            "moderators-groups":[ ]
          }
        ],
        "defaults":{
          "reviewers":[ ]
        },
        "deleted":false,
        "deploy":{
          "enabled":false,
          "url":""
        },
        "description":"Witness the power of a fully operational Swarm project.",
        "emailFlags":{
          "change_email_project_users":"1",
          "review_email_project_members":"1"
        },
        "jobview":"",
        "members":[
          "alex_qc",
          "pubuser"
        ],
        "minimumUpVotes":null,
        "name":"Jam",
        "owners":[
          "bruno"
        ],
        "private":false,
        "retainDefaultReviewers":false,
        "subgroups":[
          "Administrators"
        ],
        "tests":{
          "enabled":false,
          "url":"",
          "postBody":"",
          "postFormat":"URL"
        },
        "workflow":"1"
      },
      "readme":"",
      "mode":"edit"
    }

#### Editing a project to add a moderated branch and make the project public

Specifying a branch requires using array notation and providing at least two fields (`name` and `paths`) for each branch you wish to create. Creating more than one branch involves incrementing the `branches[0]` specifier for each branch.

If you have existing branches, you must specify all of them in the query to avoid data loss. This operation sets the value of the entire `branches` property to match the provided input.

To change a private project to public, set the private parameter to false.

    curl -u "username:password" \
         -X PATCH \
         -d "private=false" \
         -d "branches[0][name]=Branch One" \
         -d "branches[0][paths][]=//depot/main/TestProject/..." \
         -d "branches[1][name]=Branch Two" \
         -d "branches[1][paths][]=//depot/main/SecondBranch/..." \
         -d "branches[1][moderators][]=bob" \
         -d "branches[1][moderators-groups][]=group1" \
         "https://my-swarm-host/api/v9/projects/testproject-4"

Swarm responds with the new project entity:

    HTTP/1.1 200 OK

    {
      "project":{
        "id":"testproject-4",
        "branches":[
          {
            "name":"Branch One",
            "paths":[
              "//depot/main/TestProject/..."
            ],
            "id":"branch-one",
            "moderators":[ ],
            "moderators-groups":[ ],
            "defaults":{
              "reviewers":[ ]
            },
            "workflow":null,
            "retainDefaultReviewers":false,
            "minimumUpVotes":null
          },
          {
            "name":"Branch Two",
            "paths":[
              "//depot/main/SecondBranch/..."
            ],
            "moderators":[
              "non-admin"
            ],
            "moderators-groups":[
              "group1"
            ],
            "id":"branch-two",
            "defaults":{
              "reviewers":[ ]
            },
            "workflow":null,
            "retainDefaultReviewers":false,
            "minimumUpVotes":null
          }
        ],
        "defaults":{
          "reviewers":[ ]
        },
        "deleted":false,
        "deploy":{
          "enabled":false,
          "url":""
        },
        "description":"Updated description",
        "emailFlags":[ ],
        "jobview":null,
        "members":[
          "non-admin"
        ],
        "minimumUpVotes":null,
        "name":"testproject-4",
        "owners":[ ],
        "private":false,
        "retainDefaultReviewers":false,
        "subgroups":[ ],
        "tests":{
          "enabled":false,
          "url":""
        },
        "workflow":null
      },
      "readme":"",
      "mode":"edit"
    }

#### Editing a project to add default reviewers

    curl -u "<user>:<password>" \
         -H "Content-Type: application/json" \
         -X PATCH \
         -d '"defaults":{"reviewers":{"swarm_admin":{"required":true}} \
             "branches":[{ \
               "name":"dev", \
               "paths":{"//depot/dev/API Project/..."} \
               "defaults": { \
                   "reviewers":{ \
                       "groups":{"group1":{"required":"1"}}, \
                       "users":{"non_admin":{"required":true}} \
                   } \
               }]' \
         "https://my-swarm-host/api/v9/projects/API Project"

Or without JSON content:

    curl -u "username:password" \
         -X PATCH \
         -d "name=Udated description" \
         -d "defaults[reviewers][swarm_admin][required]=true" \
         -d "branches[0][name]=dev" \
         -d "branches[0][paths][]=//depot/dev/API Project/..." \
         -d "branches[0][defaults][reviewers][groups][group1][required]=1" \
         -d "branches[0][defaults][reviewers][users][non_admin][required]=true" \
         "https://my-swarm-host/api/v9/projects/API Project"

Swarm responds with project entity similar to:

    HTTP/1.1 200 OK

    {
      "project":{
        "id":"api-project",
        "branches":[
          {
            "name":"dev",
            "paths":[
              "//depot/dev/APIProject/..."
            ],
            "defaults":{
              "reviewers":{
                "users":{
                  "non-admin":{
                    "required":true
                  }
                },
                "groups":{
                  "group1":{
                    "required":"1"
                  }
                }
              }
            },
            "id":"dev",
            "moderators":[ ],
            "moderators-groups":[ ],
            "workflow":null,
            "retainDefaultReviewers":false,
            "minimumUpVotes":null
          }
        ],
        "defaults":{
          "reviewers":{
            "users":{
              "swarm-admin":{
                "required":true
              }
            }
          }
        },
        "deleted":false,
        "deploy":{
          "enabled":false,
          "url":""
        },
        "description":"Updated description",
        "emailFlags":[ ],
        "jobview":null,
        "members":[
          "swarm-admin"
        ],
        "minimumUpVotes":null,
        "name":"API Project",
        "owners":[ ],
        "private":false,
        "retainDefaultReviewers":false,
        "subgroups":[ ],
        "tests":{
          "enabled":false,
          "url":""
        },
        "workflow":null
      },
      "readme":"",
      "mode":"edit"
    }

## Delete a Project

### Summary

Delete a Project

DELETE /api/v9/projects/{id}

### Description

Mark a Swarm project as deleted. The project ID and name cannot be reused. If a project has owners set, only the owners can perform this action.

- Private projects: when a project is made private, only the project owners, moderators, and members, plus users with super-level privileges in the Helix Core Server, can see the project, its activity streams, and ongoing reviews. API responses honor these private project restrictions. For more information about private project restrictions, see Private projects.
- Permissions: if a public review contains files that the user does not have permission to view, the review is returned but the restricted files are not displayed.

### Parameters

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
id | Project ID | string | path | Yes

### Example response

#### Successful Response:

    HTTP/1.1 200 OK

    {
      "id": "testproject"
    }

### Example usage

#### Deleting a project:

Super users, administrators, and owners can delete projects. Members can delete projects that have no owners set.

    curl -u "username:password" -X DELETE "https://my-swarm-host/api/v9/projects/testproject3"

Assuming that the authenticated user has permission, Swarm responds with the id of the deleted project:

    HTTP/1.1 200 OK

    {
      "id": "testproject3"
    }

Your search for returned results