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"
}